> For the complete documentation index, see [llms.txt](https://developers.fingerpush.com/link/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.fingerpush.com/link/rn-sdk.md).

# React Native SDK

2026년 7월 29일에 업데이트됨

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

**RN** 0.77.x | **Android** API 23+ | **iOS** 15.0+
{% endhint %}

## 리액트 네이티브 SDK 설치하기

핑거푸시 링크 리액트 네이티브 SDK는 아래 방법으로 설치할 수 있습니다.

1. npm 또는 yarn을 이용하여 fplink-react-native를 설치해 주세요.

```bash
npm install fplink-react-native
```

```bash
yarn add fplink-react-native
```

2. CocoaPods를 이용하여 iOS 의존성을 설치해 주세요. Android 의존성은 자동으로 설치됩니다.

```bash
cd ios; pod install
```

### SDK 초기화하기

iOS SDK와 Android SDK는 초기화 방법이 다릅니다. 아래 가이드를 참고해 주세요.

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

#### iOS

&#x20;1\.  Xcode 메뉴 바에서 File > New > File from Template 에서 Header File을 추가합니다.

<div data-with-frame="true"><figure><img src="https://3038700150-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeoSKISgBZXnZ708j5r5d%2Fuploads%2Fm31EitLd3YHRxI1XErec%2FXcode-New%20Header%20File.png?alt=media&amp;token=68751e49-78dd-4d9d-a979-5b56defcf747" alt=""><figcaption></figcaption></figure></div>

파일명은 <mark style="color:blue;">{ProjectName}-Bridging-Header.h</mark> 으로 추가합니다.

파일이 생성되면 최상단에 #import "FplinkReactNative.h" 를 추가 합니다.

```objective-c
#import "FplinkReactNative.h"
```

2\.  Build Settings에서 Objective-C Bridging Header에 'ProjectName-Bridging-Header.h'의 경로를 추가합니다.

<figure><img src="https://3038700150-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeoSKISgBZXnZ708j5r5d%2Fuploads%2FwvlvpgPRvydabnN2tcQf%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-02-10%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.07.26.png?alt=media&amp;token=082bcaa4-3124-4058-9604-d4edeacf6542" alt=""><figcaption></figcaption></figure>

3\.  Build Settings에서 **'User Script Sandboxing'** 값을 **No**로 변경합니다.

4\.  RunScript 를 추가합니다.\
\[Targets 프로젝트] > \[Build Phases] > '+' 클릭 > 'New RunScript Phase' 클릭 후 아래의 스크립트를 추가합니다.

{% code title="fplink script" overflow="wrap" expandable="true" %}

```sh
set -euo pipefail

: "${CODE_SIGN_ENTITLEMENTS:=}"
[ -n "$CODE_SIGN_ENTITLEMENTS" ] || exit 0

ENTITLEMENTS_PATH="${SRCROOT}/${CODE_SIGN_ENTITLEMENTS}"
[ -f "$ENTITLEMENTS_PATH" ] || exit 0

RESOURCES_DIR="${TARGET_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}"
OUTPUT_PLIST="$RESOURCES_DIR/AssociatedDomains.plist"

[ -f "$ENTITLEMENTS_PATH" ] || exit 0

mkdir -p "$RESOURCES_DIR"
rm -f "$OUTPUT_PLIST"

/usr/libexec/PlistBuddy -c "Add :applinks array" "$OUTPUT_PLIST"

i=0
added=0
while true; do
  raw=$(/usr/libexec/PlistBuddy -c "Print :com.apple.developer.associated-domains:${i}" "$ENTITLEMENTS_PATH" 2>/dev/null) || break

  if [[ "$raw" == applinks:* ]]; then
    domain="${raw#applinks:}"
    /usr/libexec/PlistBuddy -c "Add :applinks:$added string $domain" "$OUTPUT_PLIST"
    added=$((added+1))
  fi

  i=$((i+1))
done
```

{% endcode %}

5\.  ios/YOUR\_PROJECT\_NAME/AppDelegate.swift 파일에 아래와 같이 코드를 추가해 주세요.

{% code title="AppDelegate.swift" %}

```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    FplinkReactNative.initialize(appId:"YOUR_APP_ID", apiKey:"YOUR_MOBILE_APP_API_KEY")
    ...
}
```

{% endcode %}

#### Android

android/app/src/main/java/.../MainApplication.kt 파일에 아래와 같이 코드를 추가해 주세요.

{% code title="MainApplication.kt" %}

```kt
override fun onCreate() {
    super.onCreate()
    FplinkReactNative.initialize(this, "YOUR_APP_ID", "YOUR_MOBILE_APP_API_KEY")
    ...
}
```

{% endcode %}

## 딥링크

딥링크를 설정하면 트래킹 링크가 있는 광고를 클릭한 유저를 원하는 앱의 특정 페이지로 이동시킬 수 있습니다.

### 딥링크로 앱이 실행되도록 설정하기

유저가 트래킹 링크를 클릭한 후에 앱이 핑거푸시 딥링크로 실행되도록 설정합니다.

#### iOS

1\. 딥링크의 스킴 딥링크 앱 설정이 필요합니다. Xcode에서 \[YOUR\_PROJECT]>\[Info]>\[URL Types]로 이동합니다.

2\. '+'를 클릭한 후에 URL Schemes에 핑거푸시 링크 대시보드에서 입력한 iOS URI 스킴을 입력합니다.

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

<mark style="color:$danger;">**://**</mark> 를 제외한 iOS URL 스킴을 입력해야 합니다.
{% endhint %}

3\. 딥링크의 유니버셜 링크 앱 설정이 필요합니다. Xcode에서 \[YOUR\_PROJECT]>\[Signing & Capabilities]로 이동합니다.

4\. '+ Capability'를 클릭하면 Associated Domains를 추가할 수 있습니다.

5\. 핑거푸시 링크 대시보드의 \[커스텀 도메인] 에서 생성한 도메인 정보를 Associated Domains에 applinks:\[커스텀 도메인] 형태로 추가합니다.

#### Android

1\. 딥링크의 스킴 딥링크 앱 설정이 필요합니다. AndroidManifest.xml에 딥링크를 처리하는 Activity에 Intent Filter를 추가합니다.

추가하는 Intent Filter는 핑거푸시 링크 대시보드에 입력한 안드로이드 URI Scheme를 사용해야 합니다. ://를 제외한 안드로이드 URI 스킴을 입력합니다.

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

2\. 딥링크의 앱 링크(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 %}

### 앱에서 딥링크 이벤트 수집하기

딥링크 이벤트를 핑거푸시 링크 SDK에 전달해 수집합니다. 딥링크로 앱이 열리면서 호출되는 OS 콜백의 가장 위에 FplinkReactNative.trackDeeplink 함수를 호출합니다.

전달받은 딥링크 데이터를 활용해 유저를 설정한 목적지도 보냅니다.

#### React Native

{% code title="React Native" %}

```jsx
import {Fplink} from 'fplink-react-native';
Fplink.setOnDeeplinkReceived((linkData) => {
    // 딥링크 데이터로 link, scheme 값을 확인할 수 있습니다.
})
```

{% endcode %}

#### iOS

ios/YOUR\_PROJECT\_NAME/AppDelegate.swift 파일에 아래와 같이 코드를 추가해 주세요.

{% code title="AppDelegate.swift" %}

```swift
// when app is opened with scheme deeplink
func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey : Any] = [:]
) -> Bool {
    FplinkReactNative.trackDeeplink(open: url)

    return true
}
...
// when app is opened with universal links
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    FplinkReactNative.trackDeeplink(continue: userActivity)

    return true
}
```

{% endcode %}

#### Android

android/app/src/main/java/.../MainActivity.kt 파일에 아래와 같이 코드를 추가해 주세요.

{% code title="MainActivity.kt" %}

```kotlin
override fun onResume() {
    super.onResume()
    FplinkReactNative.trackDeeplink(intent)
}
...
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    setIntent(intent)
}
```

{% endcode %}

#### 수집한 핑거푸시 링크 딥링크로 유저를 이동시키기&#x20;

핑거푸시 딥링크가 실행되면 [OnDeeplinkReceived](#undefined-1) 콜백에 전달됩니다.

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

디퍼드 딥링크는 자동으로 [OnDeeplinkReceived](#undefined-1)에 전달되기 때문에 별도의 설정이 필요하지 않습니다.

### 하이브리드 앱 설정하기

웹뷰는 기본적으로 딥링크를 지원하지 않습니다. 따라서 Fplink.click 함수로 SDK가 대신 트래킹 링크의 딥링크를 실행하도록 설정해야 합니다.

Fplink.click 함수는 입력된 주소가 핑거푸시 링크에서 생성한 링크면 True 를 반환합니다. 그리고 주소로 앱을 실행하면 onSuccess 함수를 호출합니다.&#x20;

입력된 주소가 다른 플랫폼의 딥링크가 실행되면 false 로 반환합니다.

{% code title="React Native" %}

```jsx
...
const onShouldStartLoadWithRequest = (request: WebViewNavigation) => {
    const { url } = request;

    const isHandled = Fplink.click(
      url,
      () => {
        // 성공 콜백
      }
    );

    if (isHandled) {
      return false; // 핑거푸시 딥링크 주소로 웹뷰 로딩을 중단합니다.
    }

    return true; // 일반 링크는 로딩을 허용합니다.
  };
...
<WebView
    source={{ uri: 'https://...' }}
    onShouldStartLoadWithRequest={onShouldStartLoadWithRequest}
/>
...
```

{% endcode %}