모바일 SDK 연동 가이드 — iOS·Android 앱에서 딥링크와 이벤트 추적 시작하기

SDK를 연동하면 뭐가 달라지나요?

SDK 없이도 FINGERPUSH.LINK의 기본 기능(단축 URL, 클릭 통계, 디퍼드 딥링크)은 작동합니다. 하지만 SDK를 연동하면 앱 안에서 일어나는 모든 것을 추적할 수 있습니다.

iOS SDK 연동 (v1.0.0-rc02, iOS 15.0+)

1단계: SDK 설치

현재 xcframework 직접 설치 방식을 지원합니다.

1. fplink.xcframework.zip 다운로드 (약 309KB)
2. 압축 해제 후 fplink.xcframework를 Xcode 프로젝트의 Frameworks 폴더에 추가
3. Target → General → Frameworks, Libraries, and Embedded Content에서 fplink.xcframework를 Embed & Sign으로 설정

참고: CocoaPods, Swift Package Manager는 현재 준비 중입니다.

RunScript 설정 (필수)

Target → Build Phases → New Run Script Phase에 아래 스크립트를 추가합니다. 빌드 시 AssociatedDomains.plist가 자동 생성되어 Universal Links가 활성화됩니다.

PLIST_PATH="${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/AssociatedDomains.plist"
/usr/libexec/PlistBuddy -c "Add :com.apple.developer.associated-domains array" "$PLIST_PATH" 2>/dev/null
# 콘솔에서 설정한 도메인이 자동으로 포함됩니다

2단계: 초기화

AppDelegate.swift에서 SDK를 초기화합니다. App ID와 API Key는 콘솔의 **[모바일 앱] → [앱 관리] → [API 키]**에서 확인할 수 있습니다.

import fplink

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Fplink.initialize(
            appID: "YOUR_APP_ID",
            apiKey: "YOUR_MOBILE_APP_API_KEY"
        )
        return true
    }
}

3단계: 딥링크 콜백 등록

앱이 딥링크를 수신했을 때 호출될 콜백을 등록합니다. AppDelegate의 didFinishLaunchingWithOptions에서 설정하세요.

Fplink.instance().setDeeplinkCallback { url, schemeUrl in
    // url: Universal Link URL
    // schemeUrl: URL Scheme URL (커스텀 스킴 사용 시)
    if let url = url {
        navigateToContent(url: url)
    }
}

4단계: 딥링크 수신 처리

딥링크 유입 경로에 따라 적절한 핸들러를 호출합니다.

Universal Links (앱 링크)

// SceneDelegate.swift
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    let isFingerpushDeeplink = Fplink.instance()
        .handleDeeplink(continue: userActivity)
    // true이면 FINGERPUSH.LINK 딥링크가 처리됨
}

URL Scheme (커스텀 스킴)

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    let isFingerpushDeeplink = Fplink.instance()
        .handleDeeplink(open: url)
}

5단계: 디퍼드 딥링크

앱 미설치 상태에서 링크를 클릭하고, 스토어에서 설치 후 첫 실행 시 원래 목적지로 자동 이동합니다.

Fplink.instance().handleDeferredDeeplink { url, schemeUrl in
    // url: 원래 클릭했던 딥링크 URL
    // schemeUrl: URL Scheme URL
    if let url = url {
        navigateToContent(url: url)
    }
}
// isFirstCalled: true이면 최초 호출

Android SDK 연동 (v1.0.0-rc03, API 23+)

1단계: SDK 설치

build.gradle (프로젝트 레벨)에서 mavenCentral() 확인:

repositories {
    mavenCentral()
}

build.gradle (app 레벨):

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

2단계: 초기화

Application 클래스에서 FplinkOptionsBuilder로 SDK를 초기화합니다.

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

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

3단계: 딥링크 수신

AndroidManifest.xml 인텐트 필터 추가:

<activity android:name=".MainActivity">
    <!-- URL Scheme 딥링크 -->
    <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>
    
    <!-- App Links (https) -->
    <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="https"
              android:host="YOUR_DOMAIN_NAME" />
    </intent-filter>
</activity>

Activity에서 딥링크 처리 — onResume()과 onNewIntent()에서 처리해야 합니다:

class MainActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        Fplink.handleDeeplink(intent) { linkData ->
            // linkData.link → 딥링크 URL
            // linkData.schemeUrl → 커스텀 스킴 URL
            linkData?.let {
                navigateToContent(it.link)
            }
        }
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)  // 인텐트 갱신 필수
    }
}

4단계: 디퍼드 딥링크

앱 미설치 → 스토어 설치 → 첫 실행 시 원래 목적지로 자동 라우팅:

Fplink.handleDeferredDeepLink { linkData ->
    // linkData.link → 원래 클릭했던 딥링크 URL
    linkData?.let {
        navigateToContent(it.link)
    }
}
// isFirstCalled: true이면 최초 호출

React Native SDK 연동 (v1.0.0-rc04)

React Native 0.77.x 이상, Android API 23+, iOS 15.0+ 환경을 지원합니다.

1단계: 패키지 설치

npm install fplink-react-native
cd ios && pod install

2단계: 네이티브 초기화

React Native SDK는 iOS와 Android 네이티브 코드에서 각각 초기화해야 합니다.

iOS — AppDelegate.swift

import FplinkReactNative

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

Android — MainApplication.kt

import kr.co.nicekjm.fplinkreactnative.FplinkReactNative

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

3단계: 딥링크 수신 (React Native)

JavaScript에서 딥링크 콜백을 등록합니다:

import { Fplink } from 'fplink-react-native';

useEffect(() => {
    Fplink.setOnDeeplinkReceived((linkData) => {
        // linkData.link → 딥링크 URL
        // linkData.schemeUrl → 커스텀 스킴 URL
        if (linkData?.link) {
            navigation.navigate('Product', { url: linkData.link });
        }
    });
}, []);

4단계: 네이티브 딥링크 트래킹

딥링크 유입을 SDK에 전달하려면 네이티브 코드에서 트래킹 메서드를 호출해야 합니다.

iOS — AppDelegate.swift

// Universal Links
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    FplinkReactNative.trackDeeplink(continue: userActivity)
    return true
}

// URL Scheme
func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    FplinkReactNative.trackDeeplink(open: url)
    return true
}

Android — MainActivity.kt

import kr.co.nicekjm.fplinkreactnative.FplinkReactNative

override fun onResume() {
    super.onResume()
    FplinkReactNative.trackDeeplink(intent)
}

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

5단계: 디퍼드 딥링크

React Native SDK에서는 디퍼드 딥링크가 자동으로 setOnDeeplinkReceived 콜백을 통해 전달됩니다. 별도의 추가 코드가 필요 없습니다.

하이브리드 앱 (WebView) 연동

웹뷰 기반 하이브리드 앱에서는 click 함수를 사용하여 딥링크 URL을 처리할 수 있습니다.

iOS (WKWebView)

func webView(_ webView: WKWebView,
             decidePolicyFor navigationAction: WKNavigationAction,
             decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
    if let url = navigationAction.request.url {
        Fplink.instance().click(
            url: url,
            onSuccess: { linkData in
                // 딥링크 처리
            },
            onFailure: { error in
                // 일반 URL로 처리
            }
        )
    }
    decisionHandler(.allow)
}

Android (WebView)

Fplink.click(url,
    onSuccess = { linkData ->
        // 딥링크 처리
    },
    onFailure = { error ->
        // 일반 URL로 처리
    }
)

React Native (WebView)

onShouldStartLoadWithRequest={(request) => {
    Fplink.click(request.url, (linkData) => {
        // 딥링크 처리
    });
    return true;
}}

퍼널 추적과 이벤트

SDK 연동 후 FINGERPUSH.LINK 콘솔에서 다음 퍼널을 확인할 수 있습니다:

크로스플랫폼 세션 연결

SDK의 핵심 가치는 웹 세션과 앱 세션을 하나로 연결하는 것입니다.

1. 사용자가 웹에서 링크를 클릭하면 세션 ID가 생성됩니다
2. 앱을 설치하고 열면, SDK가 디퍼드 딥링크에서 세션 ID를 수신합니다
3. 앱 내 이벤트가 같은 세션 ID로 기록됩니다
4. 콘솔에서 웹 클릭 → 앱 설치 → 앱 구매를 하나의 여정으로 볼 수 있습니다

연동 체크리스트