针对 Cordova 的 Singular SDK 集成指南

 

Singular SDK 可作为 Cordova 的插件使用。下面的说明 向您展示如何将 Singular 集成到您的 Cordova 应用程序中。

先决条件

  • 本文假定您拥有一个功能正常的 Cordova 应用程序。
  • 要初始化 SDK,您需要 Singular SDK 密钥和 SDK Secret。您可以在 Singular 平台的 "开发工具 > SDK 集成 > SDK 密钥 "中获取它们。

添加 Singular 插件

要将 Singular 插件添加到您的 Cordova 项目,请运行以下程序:

cordova plugin add singular_cordova_sdk

Ionic

如果您使用的是 Ionic:

  1. 安装 Singular SDK 插件:

    $ ionic cordova plugin add singular_cordova_sdk
  2. 在您的主 ts 文件中,声明一个 window 变量:

    declare var cordova;
  3. 现在,您可以直接从 Cordova 使用 Singular 插件了:

    import {Component} from '@angular/core';
    import {Platform} from '@ionic/angular';
      declare var cordova;
      ...
      
      export class HomePage {
        constructor(public platform: Platform) {
          this.platform.ready().then(() => {
      
          // 在此处添加代码以初始化 Singular SDK
      
          }); 
        }
    }

初始化 SDK(必填)

每次打开应用程序时,都应调用 Singular SDK 初始化代码。这是所有 Singular 归属功能的前提。它还会向 Singular 发送一个新的用户会话(会话用于计算用户保留率)。

初始化 Singular SDK

  1. 创建一个 SingularConfig 对象。该对象包含你的 Singular SDK 密钥和秘密。
  2. 如果希望应用程序支持深度链接和/或 SKAdNetwork,请配置可选设置(请参阅下面的添加深度链接支持添加 SKAdNetwork支持)。
  3. 支持 META 安装推荐人归属

    启用"元安装推荐人 "属性所需的 SDK 配置

    1. 在奇异配置对象中提供您的Facebook 应用程序 ID
      // 启用 META 安装引荐来源网址
      singularConfig.withFacebookAppId("在此插入您的 FACEBOOK 应用程序 ID");
    在哪里可以找到应用程序的 Facebook 应用程序 ID?
  4. 使用 SingularConfig 对象初始化 SDK。

代码示例(注释了可选设置):

// 创建配置对象
  var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  /*
  // 可选:启用深层链接(需要额外的设置步骤,请参阅指南)
  var linkHandler = function(data){
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  // 在这里添加链接处理逻辑...
  }
  singularConfig.withSingularLink(linkHandler);
  */
  
/*
// 启用 META 安装引荐来源网址
singularConfig.withFacebookAppId("在此插入您的 FACEBOOK 应用程序 ID");
*/
/* // 可选:启用 SKAdNetwork(在托管模式下,请参阅指南了解更多选项) singularConfig.withSkAdNetworkEnabled(true); */ // 初始化单数 cordova.plugins.SingularCordovaSdk.init(singularConfig);

向 Singular 发送用户 ID(可选)

您可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。

注:如果使用Singular 的跨设备解决方案,则必须在所有平台上收集用户 ID。

  • 用户 ID 可以是任何标识符,但不能暴露 PII(个人身份信息),例如,不能使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对第一方数据唯一的哈希值。
  • 传递给Singular的用户ID值也应该是你在所有平台(Web/移动/PC/控制台/离线)上获取的相同的内部用户ID。
  • Singular 将在用户级导出、ETL 和内部 BI 回传(如果配置)中包含用户 ID。用户 ID 是第一方数据,Singular 不会与其他方共享。
  • 使用 Singular SDK 方法设置的用户 ID 值将一直存在,直到使用unsetCustomUserId 方法取消设置或卸载应用程序为止。关闭或重启应用程序不会取消设置用户 ID。

要设置用户 ID,请使用setCustomUserId 方法。要取消设置(例如,如果用户 "注销 "账户),请调用unsetCustomUserId

注意:如果多个用户使用一台设备,我们建议实施注销流程,为每次登录和注销设置取消设置用户 ID。

如果已经知道应用程序打开时的用户 ID,请在初始化 Singular SDK 之前调用setCustomUserId 。这样,Singular 就能从第一次会话中获得用户 ID。不过,在用户注册或登录之前,用户 ID 通常是不可用的。在这种情况下,请在注册流程完成后调用setCustomUserId

SingularCordovaSdk.setCustomUserID 方法
说明 向 Singular 发送用户 ID。
签名 SingularCordovaSdk.setCustomUserId(String customUserId)
使用示例
SingularCordovaSdk.setCustomUserId('CustomUserId');
SingularCordovaSdk.unsetCustomUserID 方法
说明 取消设置已发送至 Singular 的用户 ID。
签名 SingularCordovaSdk.unsetCustomUserId()
使用示
SingularCordovaSdk.unsetCustomUserId();

可选:自定义用户 ID 设备映射

重要: 此高级企业功能仅在特殊情况下可用。实施前请咨询 Singular 解决方案工程师

Singular 可以通过服务器到服务器集成接收额外的移动事件跟踪数据。要使用此功能,必须将用户 ID 映射到 Singular 的移动设备跟踪标识符。

注意:在初始化 Singular SDK 后或获得用户 ID 后,请尽快调用此方法。

SingularCordovaSdk.setDeviceCustomUserId 方法
说明 设置与登录相同的自定义用户 ID,并将其映射到 Singular 的跟踪标识符。
签名 SingularCordovaSdk.setDeviceCustomUserId(String customUserId)
使用示例
SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

跟踪事件(非收入)

除了向 Singular 发送用户会话(通过初始化 SDK),还可以发送用户事件。有关应用程序内事件的数据有助于 Singular 分析用户获取活动的性能并衡量关键绩效指标

例如,您的企业可能希望收集有关用户登录、注册、教程完成或游戏应用中等级提升的数据。

要向 Singular 发送事件,请使用eventWithArgs 方法。为事件命名,并添加要跟踪的任何属性。

// 示例:使用事件属性报告名为“查看产品”的事件
  cordova.plugins.SingularCordovaSdk.eventWithArgs(
    'ViewProduct', // 活动名称
    {
      // 事件属性
      productID:"123",
      productCategory:"Outerwear"
    }
  )

跟踪收入

要让 Singular 跟踪应用程序从应用内购买中获得的收入,请向 Singular 报告 IAP 事件。

我们建议使用eventWithArgs方法,并将 IAP 对象作为事件属性传递。Singular 会使用 IAP 对象验证购买行为,并检测欺诈性购买,以免影响收入指标(请参阅应用内购买验证常见问题)。

如果您使用的是 https://github.com/j3k0/cordova-plugin-purchase,可以使用以下代码:

store.when('product123 verified', onProductVerified);
  product.verify();
  
  function onProductVerified(product){
    const iap = new cordova.plugins.SingularCordovaSdk.SingularIAP(product);
    cordova.plugins.SingularCordovaSdk.eventWithArgs('IAP_EVENT', iap)
  }

发送自定义收入

如果无法向 Singular 发送 IAP 对象,也可以使用自定义收入(customRevenue)方法,该方法接受事件名称、货币代码和购买金额。

例如

cordova.plugins.SingularCordovaSdk.customRevenue(
    customEventName, // 例子 "purchase"
    currencyCode, // 例子 "USD"
    purchaseAmount // 例子 3.2
  );

注意:以三个字母的 ISO 4217 货币代码形式传递货币,例如 "USD"、"EUR"、"INR"。

混合事件跟踪(高级)

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。不过,Singular 也可以从其他来源收集事件和收入。

任何非通过 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求,并提供匹配的设备标识符以正确归属事件。

重要

如果服务器到服务器事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符,就会出现差异。请注意以下可能性:

  • 如果事件请求是在 Singular SDK 从应用程序会话记录设备标识符之前收到的,那么该事件请求将被视为未知设备的 "第一次会话",Singular 将把该设备作为有机归属
  • 如果 Singular SDK 确实记录了设备标识符,但 Singular SDK 标识符与服务器到服务器事件请求中指定的设备标识符不同,那么事件将被错误归属

混合事件跟踪指南

从内部服务器发送事件

Singular可以收集来自服务器的收入数据,帮助分析营销活动的表现和投资回报率。

要求

  • 从应用内注册或登录事件中捕获并传递设备标识符,并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化,因此请确保在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备。
  • 服务器端事件是平台特定的,只能使用与设备平台相匹配的设备标识符发送(如 iOS 设备的 IDFA 或 IDFV)。
  • 您可以使用 Singular 内部 BI 回传机制将事件实时推送到内部端点,以便更新服务器端的数据集。请参阅内部 BI 回传常见问题
  • 查看服务器到服务器集成指南中的"跟踪收入 "部分,了解详情。
从收入提供商发送事件
RevenueCatadapty等第三方提供商可以向Singular提供购买和订阅收入

请点击以下链接了解如何启用这些合作伙伴。

从分段发送事件

要使 Segment 能与 Singular SDK 并行发送事件到 Singular,必须在 Segment 中添加一个"云模式 "目的地。请点击此处查看我们的指南。

跟踪广告收入归属

您可以使用 Singular 插件设置广告收入归属(请参阅 广告收入归属常见问题解答)。

设置广告收入归属:

  1. 添加适当的代码段,以便广告收入数据中介平台获取广告收入信息 请参阅我们的 Android SDK 文档中的代码段

注:以三个字母的 ISO 4217 货币代码传递货币,如 "USD," "EUR", "INR"。

使用以下代码向 Singular 报告广告收入事件
  1. 使用相关数据初始化SingularAdData对象
  2. 向 Singular 报告数据
Javascript
const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
   mediationPlatform,
   currencyCode, // e.g., "USD"
   revenueAmount)

cordova.plugins.SingularCordovaSdk.adRevenue(adData);

添加深度链接支持

深度链接是在用户手机上打开应用程序并将用户直接发送到特定页面或用户体验的链接,而不仅仅是应用程序的主窗口小部件。

深度链接通常用于重定向营销活动,目标用户是手机上已有应用程序但可能有一段时间没有使用过的用户。

Singular 支持通过 Singular Links 进行深度链接(请参阅 Singular Links 常见问题)。

在应用程序中使用 Singular Links:

  1. 按照 Singular Links Prerequisites 中的说明操作。
  2. 对于 Android,将此代码添加到主活动中:

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

    对于 iOS,请将此代码添加到您的 AppDelegate 中:

    #import "SingularCordovaSdk.h"
      
        - (BOOL)application:(UIApplication*)application
        didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
        {
           self.viewController = [[MainViewController alloc] init];
           [SingularCordovaSdk setLaunchOptions: launchOptions];
           return [super
        application:application didFinishLaunchingWithOptions:launchOptions];
        }
      
        - (BOOL)application:(UIApplication *)application
        continueUserActivity:(NSUserActivity *)userActivity
        restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
         [SingularCordovaSdk startSessionWithUserActivity:userActivity];
         return
        YES;
        }
  3. 在代码中初始化 Singular SDK 之前,在 Singular 配置对象中添加.withSingularLink 并指定链接处理函数:

    var singularConfig = new
        cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
      
      var linkHandler = function(data){
        var deeplink = data.deeplink;
        var passthrough = data.passthrough;
        var isDeferred = data.isDeferred;
        // 此处添加链接处理逻辑
      }
      
      singularConfig.withSingularLink(linkHandler);
      
      cordova.plugins.SingularCordovaSdk.init(singularConfig);

添加 SKAdNetwork 支持

Singular 插件支持 SKAdNetwork 框架。您可以使用以下配置选项为应用程序启用 SKAdNetwork 跟踪功能。

托管模式(推荐)

在托管模式下,Singular 会根据您选择的转换模型自动为您管理 SKAdNetwork 转换值,您可以在 Singular 平台中设置该转换模型。

要了解更多信息,请参阅 了解 Singular 的转换值管理 SKAdNetwork 模型配置常见问题解答。 有关与 Singular 一起使用 SKAdNetwork 的分步指南,请参阅 如何开始使用 SKAdNetwork。

要在托管模式下启用 SKAdNetwork,请使用以下代码:

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // 启用 SKAdNetwork(默认处于托管模式)
  singularConfig.withSkAdNetworkEnabled(true);
  
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

手动模式

如果您已经有自己的策略和工具来管理 SKAdNetwork 转换值,则可以在手动模式下使用 SKAdNetwork。

要在手动模式下启用 SKAdNetwork,请使用以下代码:

var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // 启用 SKAdNetwork
  singularConfig.withSkAdNetworkEnabled(true);
  
  // 选择SKAdNetwork手动模式
  singularConfig.withManualSkanConversionManagement();
  
  // 可选:定义处理程序以跟踪转换值的更改
  var conversionHandler = function(updatedConversionValue){
    // 使用updatedConversionValue做一些事情
  }
  
  singularConfig.withConversionValueUpdatedHandler(conversionHandler);
  
  // 初始化Singular SDK
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

更新转换值,请使用以下代码:

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
    newConversionValue,
    function(isSuccess){
      // isSuccess == true 如果更新成功
    }
  )

检索当前转换值,请使用以下代码:

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
    function(conversionValue){
      // 用 conversionValue 做一些事情
    }
  )

其他选项

跟踪卸载

要让 Singular 跟踪应用程序卸载情况,请使用以下代码向 Singular 发送 APNS/FCM 令牌:

Android

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

创建短推荐人链接

使用短链接可将冗长、充满参数的 Singular 链接转换为更短、更安全的链接,方便分享。

通常情况下,您需要动态创建短链接,以便应用程序的用户可以与朋友分享,邀请他们使用应用程序。

要创建短链接,您需要

  • 指向应用程序下载的奇异链接(请参阅 奇异链接常见问题)。
  • 要动态添加到链接中的任何参数(选项列表请参阅 跟踪链接参数)。
  • 推荐用户的姓名和 ID,如果您希望跟踪新应用的安装情况,并追溯到共享链接的用户。

要创建短链接,请使用以下代码:

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
      longLinkURL, 
      referrerName,
      referrerID,
      {
          // 添加到短链接的跟踪链接参数,例如 “频道”:“短信”
          param1: value1,
          param2: value2,
          ...
      },
      {
          onSuccess: function (shortLinkURL) {
          // 用shortLinkURL做一些事情
          },
          onError: function (error) {
          // 处理错误
          }
      }
  )

遵守数据隐私法

Singular提供隐私保护功能,帮助您与任何可能遵守消费者隐私法(如GDPR和CCPA(加州消费者隐私法))的合作伙伴合作。 如果最终用户同意共享其私人信息,这些合作伙伴希望得到通知。

如果你已经实现了征求用户同意共享其信息的方法,请使用limitDataSharing方法通知 Singular 用户的选择:

使用SingularCordovaSdk.limitDataSharing(false)来表示用户同意(选择加入)共享其信息。

如果用户不同意,则使用SingularCordovaSdk.limitDataSharing(true)

Singular在"用户隐私回传"(User Privacy Postbacks)中使用限制数据分享(LimitDataSharing),并将此信息传递给需要的合作伙伴,以遵守相关法规。更多信息请参阅"用户隐私和限制数据共享"。

注意: 该方法的使用是可选的,但可能会有归属信息,只有在明确通知用户已选择的情况下,合作伙伴才会与Singular共享这些信息。

SingularCordovaSdk.limitDataSharing方法
签名 SingularCordovaSdk.limitDataSharing(booleanshouldLimitDataSharing)
说明 通知 Singular 用户同意(选择加入)共享私人数据。
使用示例
// 用户已选择共享数据
cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

遵守 GDPR 的其他方法

Singular SDK 提供了多种方法来帮助您遵守 GDPR 政策,并让 Singular 了解用户是否同意跟踪。

SingularCordovaSdk.trackingOptIn 方法
说明 通知 Singular 用户同意(选入)跟踪。
使用示例
cordova.plugins.SingularCordovaSdk.trackingOptIn();
SingularCordovaSdk.stopAllTracking 方法
说明

停止此用户在此应用程序上的所有跟踪活动。

注意:调用此方法将有效禁用 SDK,即使应用程序重新启动后也是如此(状态是持久的)!重新启用跟踪的唯一方法是调用 resumeAllTracking()。
使用示例
cordova.plugins.SingularCordovaSdk.stopAllTracking();
SingularCordovaSdk.resumeAllTracking 方法
说明 恢复此用户在此应用程序上的跟踪。
使用示例
cordova.plugins.SingularCordovaSdk.resumeAllTracking();
SingularCordovaSdk.isAllTrackingStopped 方法
说明 检查此应用程序中该用户的跟踪状态。如果使用 StopAllTracking() 停止了跟踪且未恢复,则返回 true。
使用示例
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();