Android SDK

2026년 3월 5일에 업데이트됨

Android SDK v1.0.0-rc03 (호환성 정보)

Android API 23+

안드로이드 SDK 설치하기

핑거푸시 링크 안드로이드 SDK는 아래 방법으로 설치할 수 있습니다.

알립니다.

Gradle을 사용할 때, 프로젝트 build.gradle 파일에 repositories 블럭이 있다면 gradle (build.gradle)을, 프로젝트 settings.gradle 파일에 repositories 블럭이 있다면 Gradle (settings.gradle)을 참고해주세요.

Gradle (build.gradle)

1. SDK를 설치할 프로젝트 build.gradle 파일의 repositories 블럭 안에 mavenCentral() 저장소를 선언하세요.

프로젝트 build.gradle

allprojects {
    repositories {
        ...
        mavenCentral()
    }
}

2. 어플리케이션 build.gradle 파일에서 핑거푸시 링크 SDK 패키지를 추가하세요. 그리고 아래 링크에서 최신버전을 확인하고 $LATEST_VERSION 에 입력하세요.

• SDK 버전 목록: 링크

사용 중인 언어에 맞는 코드를 참고해주세요.

어플리케이션 build.gradle (Groovy)

dependencies {
    implementation 'link.fingerpush:fplink:$LATEST_VERSION'
}

---

어플리케이션 build.gradle.kts (Kotlin DSL)

dependencies {
    implementation("link.fingerpush:fplink:$LATEST_VERSION")
}

Gradle (settings.gradle)

SDK 초기화하기

핑거푸시 링크 안드로이드 SDK를 Android Application class 내에서 초기화하는 것을 권장합니다.

1. Application class를 생성하세요.

import android.app.Application

class AndroidApplication: Application() {

    override fun onCreate() {
        super.onCreate()
    }
}

2. 생성된 Application 을 AndroidManifest.xml에 설정하세요.

AndroidManifest.xml

<application
        android:name=".AndroidApplication"
        ...>

3. Application class에서 Fplink 를 추가하고, 아래 코드를 추가하세요.

YOUR_APP_ID와 YOUR_MOBILE_APP_API_KEY은 핑거푸시 링크 대시보드의 [모바일 앱] > [앱 관리] > [API 키] 에서 확인할 수 있습니다.

import kr.co.kissoft.fplink.Fplink
import kr.co.kissoft.fplink.data.FplinkOptionsBuilder

override fun onCreate() {
        super.onCreate()
        val options = FplinkOptionsBuilder("YOUR_APP_ID", "YOUR_MOBILE_APP_API_KEY")
            .build()
        Fplink.initialize(this, options)
    }

주의하세요

initialize 함수를 Application 클래스의 onCreate 시점에 호출해야 올바르게 동작합니다.

딥링크

^{이 문서에서 FINGERPUSH.LINK 딥링크는 이하 'FP 딥링크'로 표기합니다.}

링크 생성 시 모바일 딥링크를 설정하면, 사용자가 해당 링크를 클릭했을 때 앱이 실행되며 지정한 화면으로 이동하도록 할 수 있습니다.

딥링크 설정하기

FP 딥링크를 사용하기 위해 먼저 핑거푸시 링크 대시보드에서 앱을 추가하고, 딥링크 설정을 진행합니다.

앱 추가하기

핑거푸시 링크 대시보드에서 아래 경로로 이동하여 앱을 추가합니다.

[모바일 앱] > [앱 관리] > [새 앱 추가] > Android 플랫폼 선택

필수 정보 입력

1. [Package Name]에 패키지 이름(namespace)을 입력합니다.

2. [앱 스킴(App Scheme)]에 Android URI 스킴을 입력합니다. ://를 제외한 URI 스킴을 입력합니다.

3. SHA256 Certificate Fingerprints를 확인해야 합니다. 프로젝트 루트 터미널에서 아래 명령어를 실행합니다.

signingConfigs에 릴리즈 키스토어 정보가 이미 설정되어 있다면, 아래 명령어로 배포용, 개발용 SHA-256 값을 확인할 수 있습니다.

./gradlew signingReport

결과에서 Variant 섹션별 SHA-256 값을 확인합니다.

4. [SHA256 Certificate Fingerprints]에 확인한 SHA-256 값을 입력합니다.

---

FP 딥링크로 앱이 실행될 수 있도록, 앱에서 딥링크 설정을 진행합니다.

딥링크 설정하기

기본 설정

딥링크를 처리하는 Activity를 추가합니다.

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

class MainActivity: AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

AndroidManifest.xml 파일에 Activity를 추가합니다.

AndroidManifest.xml

<application
    ...>

    <activity android:name=".MainActivity"
        ...>

</application>

스킴 딥링크 앱 설정

AndroidManifest.xml에 딥링크를 처리하는 Activity에 Intent Filter를 추가합니다.

추가하는 Intent Filter는 핑거푸시 링크 대시보드에 입력한 앱 스킴 (App Scheme)를 추가합니다.

AndroidManifest.xml

<activity ...>
    ...
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="YOUR_SCHEME" />
    </intent-filter>
    ...
</activity>

주의하세요

반드시 분리된 <intent-filter> 태그로 추가하세요. 하나의 <intent-filter> 태그에 모든 <data> 태그를 추가하면 딥링크로 앱이 열리지 않을 수 있습니다.

앱 링크(App Links) 앱 설정

AndroidManifest.xml에 딥링크를 처리하는 Activity 아래 Intent Filter를 추가합니다.

핑거푸시 링크 대시보드의 [도메인 & 인프라] > [커스텀 도메인] 에서 사용하고자 하는 모든 도메인 정보를 추가합니다.

AndroidManifest.xml

<activity ...>
    ...
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        
        <data android:scheme="http" android:host="YOUR_DOMAIN_NAME" />
        <data android:scheme="https" android:host="YOUR_DOMAIN_NAME" />
    </intent-filter>
    ...
</activity>

주의하세요

반드시 분리된 <intent-filter> 태그로 추가하세요. 하나의 <intent-filter> 태그에 모든 <data> 태그를 추가하면 딥링크로 앱이 열리지 않을 수 있습니다.

딥링크 처리하기

딥링크로 앱이 실행될 때, 딥링크를 처리하는 Activity가 Fplink.handleDeeplink 함수를 활용해 FP 딥링크를 설정한 url과 schemeUrl 링크 정보로 변환합니다.

변환된 링크 정보를 이용해 유저를 원하는 화면으로 이동시켜주세요.

override fun onResume() {
    super.onResume()
    val isFplink = Fplink.handleDeeplink(intent) {
        // 핑거푸시 링크를 사용하여 앱이 실행된 경우
    }
}

override fun onNewIntent(intent: Intent?) {
	super.onNewIntent(intent)
	setIntent(intent)
}

Notice

Fplink.handleDeeplink 함수는 FP 딥링크인 경우 true를 반환하고, 변환된 링크 정보를 onSuccess 에 전달합니다.

FP 딥링크가 아닌 경우 false를 반환하며, SDK 처리는 수행되지 않습니다.

Fplink.handleDeeplink 함수는 고객 화면 자동으로 수행하지 않습니다.

Fplink.handleDeeplink 함수의 onSuccess 로 전달된 링크 정보를 기반으로 앱에서 직접 화면 이동을 구현하셔야 합니다.

디퍼드 딥링크 설정하기

앱이 설치되지 않은 상태에서 디퍼드 딥링크가 설정된 FP 딥링크를 클릭하면, 해당 딥링크 정보가 서버에 저장됩니다. 이후 앱이 설치되고 처음 실행될 때, SDK를 통해 저장된 딥링크 정보를 전달받을 수 있습니다.

Fplink.handleDeferredDeepLink 함수는 저장된 FP 딥링크를 획득한 후에 링크 정보로 변환해 앱에 전달합니다. onSuccess 로 전달된 링크 정보를 이용해 유저를 원하는 화면으로 이동시켜주세요.

val isFirstCalled = Fplink.handleDeferredDeepLink { linkData ->
    // 설치 후 handleDeferredDeeplink가 처음 호출될 때
    if (linkData != null) {
        // linkData 를 사용하여 목적지로 이동
    }
}

Fplink.handleDeferredDeepLink 함수는 앱이 설치되고 처음으로 호출되었으면 true를 반환하고, SDK가 초기화되지 않았거나 Fplink.handleDeferredDeepLink 함수를 처음으로 호출하는 것이 아닌 경우 false를 전달합니다.

주의하세요

디퍼드 딥링크로 앱을 설치하고, 실행없이 딥링크로 앱을 열면 FP 딥링크는 디퍼드 딥링크 유무에 관계없이 null을 onSuccess에 전달해서 딥링크만 처리되도록 합니다.

추가 설정하기

앱 내에서 FP 딥링크 활용하기

링크를 여는 방식에 따라, FP 딥링크가 정상적으로 동작하지 않을 수 있습니다.

이 경우 Fplink.click 함수를 사용하여 앱 내에서 FP 딥링크를 정상적으로 처리할 수 있습니다 .

click 함수 사용 방법

click 함수는 전달된 URL이 FP 딥링크인지 확인하고, FP 딥링크인 경우 SDK를 통해 처리합니다.

앱 내에서 FP 딥링크를 클릭

유저가 앱 내에서 FP 딥링크 클릭하면 Fplink.click 함수를 호출합니다. 해당 함수를 호출하면 딥링크 설정에 따라 링크 정보를 획득합니다.

Fplink.click("핑거푸시 링크 주소".toUri())

웹뷰에서 딥링크 동작하기

웹뷰는 기본적으로 딥링크 실행을 지원하지 않기 때문에, 웹뷰 내에서 FP 딥링크를 클릭하는 경우 의도와 다르게 동작할 수 있습니다.

이 경우 Fplink.click 함수를 호출하여 SDK가 딥링크 처리를 대신 수행하도록 설정해야 합니다.

Fplink.click 함수는 입력된 주소가 FP 링크면 true를 반환합니다. 그리고 주소로 링크 정보를 획득하면 onSuccess 함수를 호출합니다.

FP 딥링크가 아닌 경우 false를 반환하며, SDK에서 처리를 수행하지 않습니다.

웹뷰에서 FP 딥링크를 클릭

WebViewClient에서 WebViewClient#shouldOverrideUrlLoading를 구현하면 특정 URL이 로딩되는 것을 확인한 후에 계속 로딩할지 또는 로딩하지 않을지 결정할 수 있습니다. WebViewClient에 대한 자세한 내용은 안드로이드 개발자 가이드를 참고해 주세요.

private val webViewClient = object : WebViewClient() {

    private fun handleDomain(view: WebView, uri: Uri): Boolean =
        Fplink.click(uri.toString())

    override fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
        if (view === null) return false
        if (url == null) return false

        val uri = Uri.parse(url) ?: return false
        return handleDomain(view, uri)
    }

    @RequiresApi(Build.VERSION_CODES.N)
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?
    ): Boolean {
        if (view === null) return false

        val uri = request?.url ?: return false
        return handleDomain(view, uri)
    }
}