# 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 버전 목록: [링크](https://developers.fingerpush.com/link/release-note/release-note-android-sdk)

{% 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 버전 목록: [링크](https://developers.fingerpush.com/link/release-note/release-note-android-sdk)

{% 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>