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。

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

要设置用户 ID，请使用setCustomUserId 方法。要取消设置（例如，如果用户 "注销 "账户），请调用unsetCustomUserId 。

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

SingularCordovaSdk.setCustomUserId('CustomUserId');

SingularCordovaSdk.unsetCustomUserId();

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

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

混合事件跟踪（高级）

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

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

混合事件跟踪指南

跟踪广告收入归属

添加深度链接支持

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

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

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），并将此信息传递给需要的合作伙伴，以遵守相关法规。更多信息请参阅"用户隐私和限制数据共享"。

// 用户已选择共享数据
cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

遵守 GDPR 的其他方法

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

cordova.plugins.SingularCordovaSdk.trackingOptIn();

cordova.plugins.SingularCordovaSdk.stopAllTracking();

cordova.plugins.SingularCordovaSdk.resumeAllTracking();

cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();