# Android SDK

{% hint style="success" %} <mark style="color:$success;">**Android SDK v1.0.0-rc03 (호환성 정보)**</mark>

**Android** API 23+
{% endhint %}

## 안드로이드 SDK 설치하기

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

{% hint style="info" %}
알립니다.

Gradle을 사용할 때, 프로젝트 <mark style="color:blue;">build.gradle</mark> 파일에 <mark style="color:blue;">repositories</mark> 블럭이 있다면 gradle (build.gradle)을, 프로젝트 <mark style="color:blue;">settings.gradle</mark> 파일에 <mark style="color:blue;">repositories</mark> 블럭이 있다면 Gradle (settings.gradle)을 참고해주세요.
{% endhint %}

{% tabs %}
{% tab title="Gradle (build.gradle)" %}
1\. SDK를 설치할 프로젝트 <mark style="color:blue;">`build.gradle`</mark> 파일의 <mark style="color:blue;">`repositories`</mark> 블럭 안에 mavenCentral() 저장소를 선언하세요.

{% code title="프로젝트 build.gradle" %}

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

{% endcode %}

2\. 어플리케이션 <mark style="color:blue;">`build.gradle`</mark> 파일에서 핑거푸시 링크 SDK 패키지를 추가하세요. 그리고 아래 링크에서 최신버전을 확인하고 <mark style="color:blue;">`$LATEST_VERSION`</mark> 에 입력하세요.

* SDK 버전 목록: [링크](/link/release-note/release-note-android-sdk.md)

{% hint style="info" %}
사용 중인 언어에 맞는 코드를 참고해주세요.
{% endhint %}

{% code title="어플리케이션 build.gradle (Groovy)" %}

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

{% endcode %}

***

{% code title="어플리케이션 build.gradle.kts (Kotlin DSL)" %}

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

{% endcode %}
{% endtab %}

{% tab title="Gradle (settings.gradle)" %}
1\. SDK를 설치할 프로젝트 <mark style="color:blue;">`settings.gradle`</mark> 파일의 <mark style="color:blue;">`repositories`</mark> 블럭 안에 mavenCentral() 저장소를 선언하세요.

{% code title="프로젝트 settings.gradle" %}

```
dependencyResolutionManagement {
  ...
  repositories {
    ...
    mavenCentral()
  }
}
```

{% endcode %}

2\. 어플리케이션 <mark style="color:blue;">`build.gradle`</mark> 파일에서 핑거푸시 링크 SDK 패키지를 추가하세요. 그리고 아래 링크에서 최신버전을 확인하고 <mark style="color:blue;">`$LATEST_VERSION`</mark> 에 입력하세요.

* SDK 버전 목록: [링크](/link/release-note/release-note-android-sdk.md)

{% hint style="info" %}
사용 중인 언어에 맞는 코드를 참고해주세요.
{% endhint %}

{% code title="어플리케이션 build.gradle (Groovy)" %}

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

{% endcode %}

***

{% code title="어플리케이션 build.gradle.kts (Kotlin DSL)" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### SDK 초기화하기

핑거푸시 링크 안드로이드 SDK를 [Android Application class](https://developer.android.com/reference/android/app/Application) 내에서 초기화하는 것을 권장합니다.

1\. Application class를 생성하세요.

```kt
import android.app.Application

class AndroidApplication: Application() {

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

2\. 생성된 Application 을 <mark style="color:blue;">`AndroidManifest.xml`</mark>에 설정하세요.

{% code title="AndroidManifest.xml" %}

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

{% endcode %}

3\. Application class에서 <mark style="color:blue;">`Fplink`</mark> 를 추가하고, 아래 코드를 추가하세요.

YOUR\_APP\_ID와 YOUR\_MOBILE\_APP\_API\_KEY은 핑거푸시 링크 대시보드의 \[모바일 앱] > \[앱 관리] > \[API 키] 에서 확인할 수 있습니다.

```kotlin
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)
    }
```

{% hint style="danger" %} <mark style="color:$danger;">**주의하세요**</mark>

<mark style="color:$danger;">`initialize`</mark> 함수를 <mark style="color:$danger;">`Application`</mark> 클래스의 <mark style="color:$danger;">`onCreate`</mark> 시점에 호출해야 올바르게 동작합니다.&#x20;
{% endhint %}

## 딥링크

<sup>이 문서에서 FINGERPUSH.LINK 딥링크는 이하 '</sup><sup>**FP 딥링크**</sup><sup>'로 표기합니다.</sup>

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

### **딥링크 설정하기**

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

<details>

<summary>앱 추가하기</summary>

[핑거푸시 링크 대시보드](https://console.fingerpush.link/console)에서 아래 경로로 이동하여 앱을 추가합니다.

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

**필수 정보 입력**

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

2\. \[앱 스킴(App Scheme)]에 Android URI 스킴을 입력합니다. <mark style="color:blue;">`://`</mark>를 제외한 URI 스킴을 입력합니다.

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

{% hint style="info" %} <mark style="color:$info;">signingConfigs에 릴리즈 키스토어 정보가 이미 설정되어 있다면, 아래 명령어로 배포용, 개발용 SHA-256 값을 확인할 수 있습니다.</mark>
{% endhint %}

```bash
./gradlew signingReport
```

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

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

</details>

***

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

<details>

<summary>딥링크 설정하기</summary>

#### 기본 설정

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

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

class MainActivity: AppCompatActivity() {

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

<mark style="color:blue;">`AndroidManifest.xml`</mark> 파일에 Activity를 추가합니다.

{% code title="AndroidManifest.xml" %}

```xml
<application
    ...>

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

</application>
```

{% endcode %}

#### **스킴 딥링크 앱 설정**

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

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

{% code title="AndroidManifest.xml" %}

```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>
```

{% endcode %}

{% hint style="danger" %} <mark style="color:$danger;">**주의하세요**</mark>

반드시 분리된 <mark style="color:$danger;">`<intent-filter>`</mark> 태그로 추가하세요. 하나의 <mark style="color:$danger;">`<intent-filter>`</mark> 태그에 모든 <mark style="color:$danger;">`<data>`</mark> 태그를 추가하면 딥링크로 앱이 열리지 않을 수 있습니다.
{% endhint %}

#### **앱 링크**(App Links) **앱 설정**

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

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

{% code title="AndroidManifest.xml" %}

```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>
```

{% endcode %}

{% hint style="danger" %} <mark style="color:$danger;">**주의하세요**</mark>

반드시 분리된 <mark style="color:$danger;">`<intent-filter>`</mark> 태그로 추가하세요. 하나의 <mark style="color:$danger;">`<intent-filter>`</mark> 태그에 모든 <mark style="color:$danger;">`<data>`</mark> 태그를 추가하면 딥링크로 앱이 열리지 않을 수 있습니다.
{% endhint %}

</details>

### **딥링크 처리하기**

딥링크로 앱이 실행될 때, 딥링크를 처리하는 Activity가 <mark style="color:blue;">`Fplink.handleDeeplink`</mark> 함수를 활용해 FP 딥링크를 설정한 url과 schemeUrl 링크 정보로 변환합니다.

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

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

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

{% hint style="info" %} <mark style="color:$tint;">**Notice**</mark>

<mark style="color:blue;">`Fplink.handleDeeplink`</mark> 함수는 FP 딥링크인 경우 true를 반환하고, 변환된 링크 정보를  <mark style="color:blue;">`onSuccess`</mark> 에 전달합니다.&#x20;

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

<mark style="color:blue;">`Fplink.handleDeeplink`</mark> 함수는 고객 화면 자동으로 수행하지 않습니다.&#x20;

<mark style="color:blue;">`Fplink.handleDeeplink`</mark> 함수의 <mark style="color:blue;">`onSuccess`</mark> 로 전달된 링크 정보를 기반으로 앱에서 직접 화면 이동을 구현하셔야 합니다.
{% endhint %}

### 디퍼드 딥링크 설정하기

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

<mark style="color:blue;">`Fplink.handleDeferredDeepLink`</mark> 함수는 저장된 FP 딥링크를 획득한 후에 링크 정보로 변환해 앱에 전달합니다. \ <mark style="color:blue;">`onSuccess`</mark> 로 전달된 링크 정보를 이용해 유저를 원하는 화면으로 이동시켜주세요.

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

<mark style="color:blue;">`Fplink.handleDeferredDeepLink`</mark> 함수는 앱이 설치되고 처음으로 호출되었으면 true를 반환하고, SDK가 초기화되지 않았거나 <mark style="color:blue;">`Fplink.handleDeferredDeepLink`</mark> 함수를 처음으로 호출하는 것이 아닌 경우 false를 전달합니다.

{% hint style="danger" %} <mark style="color:$danger;">**주의하세요**</mark>

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

## 추가 설정하기

#### 앱 내에서 FP 딥링크 활용하기 &#x20;

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

이 경우 <mark style="color:blue;">`Fplink.click`</mark> 함수를 사용하여 앱 내에서 FP 딥링크를 정상적으로 처리할 수 있습니다 .

### click 함수 사용 방법&#x20;

<mark style="color:blue;">`click`</mark> 함수는 전달된 URL이 FP 딥링크인지 확인하고, FP 딥링크인 경우 SDK를 통해 처리합니다.

<details>

<summary>앱 내에서 FP 딥링크를 클릭</summary>

유저가 앱 내에서 FP 딥링크 클릭하면 <mark style="color:blue;">`Fplink.click`</mark>  함수를 호출합니다. 해당 함수를 호출하면 딥링크 설정에 따라 링크 정보를 획득합니다.

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

</details>

### 웹뷰에서 딥링크 동작하기

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

이 경우 <mark style="color:blue;">`Fplink.click`</mark>  함수를 호출하여 SDK가 딥링크 처리를 대신 수행하도록 설정해야 합니다.

<mark style="color:blue;">`Fplink.click`</mark> 함수는 입력된 주소가 FP 링크면 true를 반환합니다. 그리고 주소로 링크 정보를 획득하면 <mark style="color:blue;">`onSuccess`</mark> 함수를 호출합니다.&#x20;

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

<details>

<summary>웹뷰에서 FP 딥링크를 클릭 </summary>

<mark style="color:blue;">`WebViewClient`</mark>에서 <mark style="color:blue;">`WebViewClient#shouldOverrideUrlLoading`</mark>를 구현하면 특정 URL이 로딩되는 것을 확인한 후에 계속 로딩할지 또는 로딩하지 않을지 결정할 수 있습니다. [WebViewClient](https://developer.android.com/reference/android/webkit/WebViewClient#shouldOverrideUrlLoading\(android.webkit.WebView,%20android.webkit.WebResourceRequest\))에 대한 자세한 내용은 안드로이드 개발자 가이드를 참고해 주세요.

```kotlin
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)
    }
}
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.fingerpush.com/link/android-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.