文件

添加深度链接支持

深度链接可引导用户访问应用程序中的特定内容。当用户在已安装应用的设备上点击深层链接时，应用会直接打开到目标内容，如产品页面或特定体验。

奇异跟踪链接支持标准深度链接（适用于已安装的应用）和延迟深度链接（适用于新安装的应用）。有关详细信息，请参阅深度链接常见问题解答和奇异链接常见问题解答。

要求

先决条件

完成Singular Links 先决条件，为您的应用程序启用深度链接。

实施奇异链接处理程序

SingularLinkHandler 提供了一种回调机制，用于在应用程序打开时从 Singular 跟踪链接检索深度链接、延迟深度链接和直通参数。

可用参数：

深度链接 (_dl)：点击链接的用户在应用程序中的目标 URL
延迟深度链接 (_ddl)：点击链接后安装应用程序的用户的目标 URL
直通 (_p)：通过跟踪链接传递的自定义数据，以获取更多上下文信息

SDK 配置

在配置中添加 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 仅在应用程序通过 Singular Link 打开时触发。有关详细信息，请参阅Singular Links FAQ。

处理程序行为

了解 SingularLinkHandler 的执行

根据应用程序是新安装还是已安装，SingularLinkHandler 的行为会有所不同。

全新安装（延迟深度链接）

刚安装时，应用程序启动时不存在打开 URL。Singular 会完成归因，以确定跟踪链接是否包含深度链接或延迟深度链接值。

延迟深度链接流程：

用户点击配置了深度链接值的 Singular 跟踪链接
用户安装并首次打开应用程序
Singular SDK 向 Singular 服务器发送第一个会话
归因完成，并从跟踪链接中识别深层链接
深度链接值通过isDeferred = true返回到deeplink 参数中的 SingularLinkHandler。

测试延迟深度链接：

从测试设备上卸载应用程序（如果当前已安装）
重置设备上的谷歌广告 ID (GAID)
点击设备上的 Singular 跟踪链接（确保配置了深度链接值
安装并打开应用程序

归因应成功完成，延迟的深层链接值将传递给 SingularLinkHandler。

专业提示在使用不同的软件包名称（如com.example.dev而不是com.example.prod ）的开发构建中测试深度链接时，请专门针对开发应用的软件包名称配置跟踪链接。点击测试链接后，通过 Android Studio 或 APK 将开发构建直接安装到设备上，而不是从应用商店下载生产应用。

已安装（即时深度链接）

当应用程序已安装时，点击奇异链接可使用 Android 应用链接技术立即打开应用程序。

即时深度链接流程：

用户点击奇异跟踪链接
安卓操作系统提供一个包含整个 Singular 跟踪链接的开放 URL
在SDK初始化过程中，Singular会解析安卓意图（Android Intent
Singular提取deeplink 和passthrough值
通过SingularLinkHandler返回值，isDeferred = false

直通参数

使用直通参数从跟踪链接点击中获取其他数据。

如果跟踪链接中包含passthrough (_p) 参数，SingularLinkHandler 的passthrough 参数就会包含相应的数据。使用该参数可捕获营销活动元数据、用户细分数据或应用程序中需要的任何自定义信息。

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSingularLink(intent) { params ->
        // Extract passthrough data
        params.passthrough?.let { passthroughData ->
            // 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")
        }
    }

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");
                }
            }
        }
    });

转发所有查询参数

通过添加_forward_params=2 参数，从跟踪链接 URL 获取所有查询参数。

当_forward_params=2 添加到跟踪链接时，所有查询参数都会包含在 SingularLinkHandler 的deeplink 参数中，从而让您可以访问包含所有参数的完整 URL。

跟踪链接示例：
https://yourapp.sng.link/A1b2c/abc123?_dl=myapp://product/123&_forward_params=2&utm_source=facebook&promo=SALE2024

SingularLinkHandler 将接收：
deeplink = "myapp://product/123?utm_source=facebook&promo=SALE2024"

Android SDK - 支持深度链接

添加深度链接支持

要求

先决条件

实施奇异链接处理程序

SDK 配置

在配置中添加 SingularLinkHandler

处理程序行为

了解 SingularLinkHandler 的执行

全新安装（延迟深度链接）

已安装（即时深度链接）

直通参数

转发所有查询参数