딥링크 지원 추가하기

딥링크 는 앱 내의 특정 콘텐츠로 유저를 안내합니다. 앱이 설치된 디바이스에서 유저가 딥링크를 탭하면, 앱이 제품 페이지나 특정 경험과 같은 의도된 콘텐츠로 바로 열립니다.

Singular 트래킹 링크는 표준 딥링크(설치된 앱 대상)와 지연된 딥링크(신규 설치 대상)를 모두 지원합니다. 자세한 내용은 딥링크 FAQ 및 Singular Links FAQ 를 참조하세요.

요구 사항

사전 준비 사항

앱의 딥링크를 활성화하려면 Singular Links 사전 준비 사항 을 완료하세요.

Singular Links 핸들러 구현

SingularLinkHandler는 앱이 열릴 때 Singular 트래킹 링크에서 딥링크, 지연된 딥링크 및 패스스루 파라미터를 가져오는 콜백 메커니즘을 제공합니다.

사용 가능한 파라미터:

• 딥링크 (_dl): 링크를 클릭한 유저를 위한 앱 내 대상 URL
• 지연된 딥링크 (_ddl): 링크를 클릭한 후 앱을 설치하는 유저를 위한 대상 URL
• 패스스루 (_p): 추가 컨텍스트를 위해 트래킹 링크를 통해 전달되는 커스텀 데이터

SDK 구성

AndroidManifest 구성

SDK가 딥링크를 해석하기 전에, 액티비티는 인텐트 필터를 선언하여 Android가 들어오는 ACTION_VIEW 인텐트를 라우팅하도록 해야 합니다. AndroidManifest.xml 의 런처 액티비티(또는 딥링크를 수신해야 하는 액티비티)에 필터를 추가하고 사용자만의 scheme과 host로 대체하세요.

<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Custom URI scheme deep link -->
    <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="yourapp" />
    </intent-filter>

    <!-- HTTPS Singular Link (replace with your branded subdomain) -->
    <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" />
        <data android:scheme="https" />
        <data android:host="yourcompany.sng.link" />
        <data android:pathPrefix="/A"/>
        <data android:pathPrefix="/B"/>
        <data android:pathPrefix="/E"/>
        <data android:pathPrefix="/F"/>
    </intent-filter>
</activity>

Config에 SingularLinkHandler 추가

SDK 초기화 중에 SingularLinkHandler를 구성하여 들어오는 딥링크 및 지연된 딥링크 데이터를 처리하세요.

private fun initSingularSDK() {
    val config = SingularConfig("SDK_KEY", "SDK_SECRET")
        .withSingularLink(intent) { params ->
            val deeplink = params.deeplink
            val passthrough = params.passthrough
            val isDeferred = params.isDeferred

            Log.d("SingularLink", "Deeplink: ${deeplink ?: "null"}")
            Log.d("SingularLink", "Passthrough: ${passthrough ?: "null"}")
            Log.d("SingularLink", "Is Deferred: $isDeferred")

            // Handle deep link routing
            deeplink?.let { url ->
                handleDeepLink(url, isDeferred)
            }
        }

    try {
        Singular.init(applicationContext, config)
        Log.d("Singular", "SDK initialized successfully")
    } catch (e: Exception) {
        Log.e("Singular", "SDK initialization failed: ${e.message}")
    }
}

override fun onNewIntent(intent: Intent?) {
  super.onNewIntent(intent)
  // Configure onNewIntent to handle Warm start deeplinks
  intent?.let {
    setIntent(intent)
    initSingularSDK()
  }
}

private void initSingularSDK() {
    SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
        .withSingularLink(getIntent(), new SingularLinkHandler() {
            @Override
            public void onResolved(SingularLinkParams params) {
                String deeplink = params.getDeeplink();
                String passthrough = params.getPassthrough();
                boolean isDeferred = params.isDeferred();

                Log.d("SingularLink", "Deeplink: " + (deeplink != null ? deeplink : "null"));
                Log.d("SingularLink", "Passthrough: " + (passthrough != null ? passthrough : "null"));
                Log.d("SingularLink", "Is Deferred: " + isDeferred);

                // Handle deep link routing
                if (deeplink != null) {
                    handleDeepLink(deeplink, isDeferred);
                }
            }
        });

    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    // Configure onNewIntent to handle Warm start deeplinks
    if (intent != null) {
        setIntent(intent);
        initSingularSDK();
    }
}

핸들러 동작

SingularLinkHandler 실행 이해하기

SingularLinkHandler는 앱이 새로 설치되었는지 이미 설치되어 있는지에 따라 다르게 동작합니다.

신규 설치 (지연된 딥링크)

신규 설치에서는 앱이 실행될 때 Open URL이 존재하지 않습니다. Singular는 트래킹 링크에 딥링크 또는 지연된 딥링크 값이 포함되어 있는지 판단하기 위해 어트리뷰션을 완료합니다.

지연된 딥링크 흐름:

1. 유저가 딥링크 값으로 구성된 Singular 트래킹 링크를 클릭합니다
2. 유저가 앱을 설치하고 처음으로 엽니다
3. Singular SDK가 첫 번째 세션을 Singular 서버로 전송합니다
4. 어트리뷰션이 완료되고 트래킹 링크의 딥링크가 식별됩니다
5. 딥링크 값이 isDeferred = true 와 함께 deeplink 파라미터로 SingularLinkHandler에 반환됩니다

이미 설치됨 (즉시 딥링크)

앱이 이미 설치되어 있는 경우, Singular Link를 클릭하면 Android App Links 기술을 사용하여 앱이 즉시 열립니다.

즉시 딥링크 흐름:

1. 유저가 Singular 트래킹 링크를 클릭합니다
2. Android OS가 전체 Singular 트래킹 링크가 포함된 Open URL을 제공합니다
3. SDK 초기화 중에 Singular가 Android Intent를 파싱합니다
4. Singular가 deeplink 및 passthrough 값을 추출합니다
5. 값은 isDeferred = false 와 함께 SingularLinkHandler를 통해 반환됩니다

패스스루 파라미터

패스스루 파라미터를 사용하여 트래킹 링크 클릭에서 추가 데이터를 캡처하세요.

트래킹 링크에 passthrough (_p) 파라미터가 포함되어 있는 경우, SingularLinkHandler의 passthrough 파라미터는 해당 데이터를 포함합니다. 이를 사용하여 캠페인 메타데이터, 유저 세그멘테이션 데이터 또는 앱에서 필요한 모든 커스텀 정보를 캡처할 수 있습니다.

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSingularLink(intent) { params ->
        // Extract passthrough data
        params.passthrough?.let { passthroughData ->
            try {
                // Parse and use custom data
                val jsonData = JSONObject(passthroughData)
                val campaignId = jsonData.optString("campaign_id")
                val userSegment = jsonData.optString("segment")

                Log.d("SingularLink", "Campaign ID: $campaignId")
                Log.d("SingularLink", "User Segment: $userSegment")
            } catch (e: JSONException) {
                Log.e("SingularLink", "Error parsing passthrough data", e)
            }
        }
    }

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // Extract passthrough data
            String passthroughData = params.getPassthrough();
            if (passthroughData != null) {
                try {
                    // Parse and use custom data
                    JSONObject jsonData = new JSONObject(passthroughData);
                    String campaignId = jsonData.optString("campaign_id");
                    String userSegment = jsonData.optString("segment");

                    Log.d("SingularLink", "Campaign ID: " + campaignId);
                    Log.d("SingularLink", "User Segment: " + userSegment);
                } catch (JSONException e) {
                    Log.e("SingularLink", "Error parsing passthrough data");
                }
            }
        }
    });

모든 쿼리 파라미터 전달

트래킹 링크 URL의 모든 쿼리 파라미터를 캡처하려면 _forward_params=2 파라미터를 추가하세요.

_forward_params=2 가 트래킹 링크에 추가되면, 모든 쿼리 파라미터가 SingularLinkHandler의 deeplink 파라미터에 포함되어 모든 파라미터가 포함된 완전한 URL에 액세스할 수 있습니다.