Cordova SDK - 支持深度链接

关注
Avatar
Jared Ornstead
Updated
文件

添加深度链接支持

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

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

要求

先决条件

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

注释：

  • 本文假设您的组织正在使用 SingularLinks- Singular 的跟踪链接技术。老客户使用的可能是传统的跟踪链接。
  • 您应用程序的深度链接目的地需要在 Singular 的应用程序页面上进行配置（请参阅配置您的应用程序进行归因跟踪）。

实施 Singular 链接处理程序

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

可用参数：

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

平台配置

配置本地平台代码，将深度链接数据传递给 Singular SDK，用于归因跟踪和导航。

安卓配置

更新主活动

修改MainActivity 文件，将Intent 对象传递给 Singular SDK，从而启用 Singular SDK 处理启动相关数据并处理深度链接。

Java 
import singular_cordova_sdk.SingularCordovaSdk;

@Override
public void onNewIntent(Intent intent) {
    SingularCordovaSdk.handleNewIntent(intent);
}

Intent 对象包含有关应用程序启动方式和原因的信息，Singular 将其用于归因跟踪和深度链接导航。

位置：将此代码添加到您的主活动文件中，通常位于platforms/android/app/src/main/java/[your-package]/MainActivity.java

iOS 配置

更新 AppDelegate

通过在 AppDelegate 文件中向 Singular SDK 传递launchOptions 和userActivity 对象，使 Singular SDK 能够处理启动相关数据并处理深层链接。

Swift 
import UIKit
import SingularCordovaSdk

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    var viewController: MainViewController?
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Initialize window
        window = UIWindow(frame: UIScreen.main.bounds)
        
        // Configure view controller
        viewController = MainViewController()
        window?.rootViewController = viewController
        
        // Initialize Singular SDK with launch options
        SingularCordovaSdk.setLaunchOptions(launchOptions)
        
        // Make window visible
        window?.makeKeyAndVisible()
        
        return true
    }
    
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([Any]?) -> Void
    ) -> Bool {
        return SingularCordovaSdk.startSession(with: userActivity)
    }
}

这些方法可确保 Singular SDK 接收到有关应用程序启动方式和原因的重要信息，Singular 会将这些信息用于归因跟踪和深层链接导航。

位置：修改你的 AppDelegate 文件，位置为platforms/ios/[YourAppName]/Classes/AppDelegate.swift或AppDelegate.m （对于 Objective-C 项目）。

SDK 配置

通过在初始化过程中实施withSingularLink 回调，配置 Singular SDK 以处理深层链接和延迟深层链接。

添加 withSingularLink 回调

基本实现

配置withSingularLink 回调，以便在 SDK 初始化期间处理传入的深度链接和延迟深度链接数据。

JavaScript 
// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Define link handler function
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  
  console.log('Deep link:', deeplink);
  console.log('Passthrough:', passthrough);
  console.log('Is deferred:', isDeferred);
  
  // Add link handling logic here
  if (deeplink) {
    handleDeepLink(deeplink, isDeferred);
  }
};

// Attach link handler to configuration
singularConfig.withSingularLink(linkHandler);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

注意：只有当应用程序通过奇异链接打开时，才会触发withSingularLink 回调。有关详细信息，请参阅奇异链接常见问题解答。

高级实现

通过导航逻辑、直通数据解析和生产应用程序的错误处理，实现全面的深度链接处理。

JavaScript 
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Create configuration
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  // Configure deep link handler
  config.withSingularLink(function(params) {
    console.log('=== Singular Link Resolved ===');
    console.log('Full params:', JSON.stringify(params));
    
    var deeplink = params.deeplink;
    var passthrough = params.passthrough;
    var isDeferred = params.isDeferred;
    
    // Log for debugging
    console.log('Deep link:', deeplink || 'null');
    console.log('Passthrough:', passthrough || 'null');
    console.log('Is deferred:', isDeferred);
    
    // Handle passthrough data
    if (passthrough) {
      handlePassthroughData(passthrough);
    }
    
    // Handle deep link navigation
    if (deeplink) {
      handleDeepLinkNavigation(deeplink, isDeferred);
    }
  });
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

function handlePassthroughData(passthroughString) {
  try {
    var data = JSON.parse(passthroughString);
    
    // Apply promo code if present
    if (data.promo_code) {
      applyPromoCode(data.promo_code);
    }
    
    // Set user segment
    if (data.segment) {
      setUserSegment(data.segment);
    }
    
    // Track campaign
    if (data.campaign_id) {
      trackCampaign(data.campaign_id);
    }
  } catch (error) {
    console.error('Error parsing passthrough:', error);
  }
}

function handleDeepLinkNavigation(url, isDeferred) {
  // Parse URL to extract route and parameters
  var urlObj = parseDeepLink(url);
  
  console.log('Navigating to: ' + urlObj.route);
  console.log('Parameters:', urlObj.params);
  console.log('Deferred install:', isDeferred);
  
  // Route based on deep link structure
  switch (urlObj.route) {
    case 'product':
      navigateToProduct(urlObj.params.id);
      break;
    case 'promo':
      navigateToPromo(urlObj.params.code);
      break;
    case 'category':
      navigateToCategory(urlObj.params.name);
      break;
    default:
      navigateToHome();
  }
}

function parseDeepLink(url) {
  // Parse myapp://product/123?variant=blue
  var parts = url.split('?');
  var path = parts[0];
  var queryString = parts[1];
  
  var pathParts = path.replace(/^[^:]+:\/\//, '').split('/');
  var route = pathParts[0];
  
  // Parse parameters
  var params = {};
  
  // Add path parameters
  if (pathParts.length > 1) {
    params.id = pathParts[1];
  }
  
  // Add query parameters
  if (queryString) {
    queryString.split('&').forEach(function(pair) {
      var keyValue = pair.split('=');
      params[keyValue[0]] = decodeURIComponent(keyValue[1]);
    });
  }
  
  return { route: route, params: params };
}

// Navigation functions
function navigateToProduct(productId) {
  console.log('Navigating to product:', productId);
  // Your navigation logic
}

function navigateToPromo(promoCode) {
  console.log('Navigating to promo:', promoCode);
  // Your navigation logic
}

function navigateToCategory(categoryName) {
  console.log('Navigating to category:', categoryName);
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

// Utility functions
function applyPromoCode(code) {
  console.log('Applying promo code:', code);
}

function setUserSegment(segment) {
  console.log('Setting user segment:', segment);
}

function trackCampaign(campaignId) {
  console.log('Tracking campaign:', campaignId);
}

参数详情

了解 Singular Link 回调中提供的参数，有助于构建强大的深度链接逻辑。

参数 类型 说明
deeplink 字符串 用户点击链接后在应用程序中的目标 URL（例如，myapp://product/123)
passthrough 字符串 通过跟踪链接传递的自定义数据，通常为 JSON 编码，用于附加上下文
isDeferred 布尔 表示此链接是否为延迟深度链接（用户在点击链接后安装应用程序

最佳实践

  • 安全解析 URL：在将深度链接 URL 用于导航之前，始终对其进行验证和消毒，以防止恶意重定向
  • 处理缺失数据：在访问深层链接参数前检查是否存在空值或未定义的值
  • 测试延迟链接：测试即时和延迟的深层链接方案，以确保新安装后的正确导航
  • 日志调试：在开发过程中启用详细日志记录，以验证是否正确接收和解析了深度链接
  • 使用 "直通 "获取上下文：利用直通参数发送活动 ID、促销代码或用户细分等附加内容
  • 与营销部门协调：与营销团队合作，定义并记录应用程序的深度链接 URL 结构

有关完整的方法文档，请参阅withSingularLink 参考资料。

处理程序行为

了解回调触发器

withSingularLink 回调行为因应用程序是全新安装还是已存在于设备上而有所不同。

全新安装场景

刚安装时，应用程序启动时没有打开 URL。Singular 必须完成最后一个接触点的归因，并确定跟踪链接是否包含已配置的深度链接或延迟深度链接 (DDL) 值。

工作原理

  • 当 Singular SDK 向 Singular 服务器发送第一个会话时，就会发生归因过程。
  • 如果适用，深度链接值会返回到 SDK 的withSingularLink 处理程序中
  • 深层链接出现在deeplink 参数中，isDeferred 设置为true
  • 这个过程可能需要几秒钟，因为它需要服务器通信

已安装场景

如果应用程序已安装，单击奇异链接可立即打开应用程序。操作系统会提供完整的跟踪链接 URL，Singular SDK 会在初始化过程中对其进行解析，以提取deeplink 和passthrough 值。

工作原理

  • 触发处理程序后，深度链接立即可用
  • isDeferred 参数设置为false
  • 无需服务器通信，从而加快了回调执行速度

测试深层链接

请按照以下步骤在开发环境中测试延迟深度链接行为。

测试要求：

  1. 从测试设备上卸载应用程序（如果当前已安装）
  2. 重置广告标识符（iOS 上为 IDFA，Android 上为 GAID）
  3. 点击设备上的 Singular 跟踪链接。确保该链接配置了深度链接值
  4. 安装并打开应用程序
  5. 验证归因是否完成，DDL 值是否传递给您的处理程序

开发构建测试：使用不同软件包名称（如com.example.dev 而不是com.example.prod ）的开发版本进行测试时，确保跟踪链接是专门为开发应用程序的软件包名称配置的。点击测试链接后，将开发构建直接安装到测试设备上（通过 CLI 或 IDE），而不是从应用商店下载。

高级功能

直通数据

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

JavaScript 
// Example tracking link with passthrough:
// https://example.sng.link/A?_dl=myapp://product/123&_p={"campaign":"summer","promo":"SAVE20"}

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  
  if (passthrough) {
    // Parse JSON passthrough data
    var passthroughData = JSON.parse(passthrough);
    console.log('Campaign:', passthroughData.campaign);
    console.log('Promo code:', passthroughData.promo);
  }
});

查询参数转发

要从跟踪链接 URL 获取所有查询参数，请在 Singular 跟踪链接中附加_forward_params=2 参数。所有查询参数都将包含在处理程序的deeplink 参数中。

JavaScript 
// Example tracking link with parameter forwarding:
// https://example.sng.link/A?_dl=myapp://product&_forward_params=2&category=electronics&sort=price

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  // deeplink will contain: myapp://product?category=electronics&sort=price
  
  console.log('Deep link with parameters:', deeplink);
  // Parse and use the forwarded parameters
});

重要：只有当应用程序通过 Singular 链接打开时，才会触发withSingularLink 回调。没有深度链接的常规应用程序启动不会触发处理程序。