用于 Cordova 的 Singular SDK 集成

文档

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

前提条件

  • 本文假定您有一个功能完善的 Cordova 应用程序。
  • 要初始化 SDK,您需要 Singular SDK Key 和 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 插件了:

    TypeScript
    import {Component} from '@angular/core';
    import {Platform} from '@ionic/angular';
    declare var cordova;
    ...
    
    export class HomePage {
    constructor(public platform: Platform) {
    this.platform.ready().then(() => {
    
        // Add code to initialize the Singular SDK here
    
    
    
    }); 
    }}
    

初始化 SDK(必填)

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

初始化 Singular SDK

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

    启用"元安装推荐人 "归因所需的 SDK 配置

    1. 在奇异配置对象中提供您的Facebook 应用程序 ID
      // To enable META Install Referrer
      
      
      singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
    在哪里可以找到应用程序的 Facebook 应用程序 ID?
  4. 使用 SingularConfig 对象初始化 SDK。

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

JavaScript
// Create the configuration object


var singularConfig = new
cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

/*
// Optional: Enable deep linking (requires additional setup steps, see guide)


var linkHandler = function(data){
var deeplink = data.deeplink;
var passthrough = data.passthrough;
var isDeferred = data.isDeferred;
// Add link handling logic here


}
singularConfig.withSingularLink(linkHandler);
*/

/*
// To enable META Install Referrer


singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
*/

/*
// Optional: Enable SKAdNetwork (in Managed Mode, see guide for more options)


singularConfig.withSkAdNetworkEnabled(true);
*/

// Initialize Singular


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 方法。为事件命名,并添加要跟踪的任何属性。

JavaScript
// Example: Report an event called View Product with event attributes


cordova.plugins.SingularCordovaSdk.eventWithArgs(
  'ViewProduct', // Event name


  {
    // Event attributes


    productID:"123",
    productCategory:"Outerwear"
  }
)

跟踪收入

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

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

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

JavaScript
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)方法,该方法接受事件名称、货币代码和购买金额。

例如

JavaScript
cordova.plugins.SingularCordovaSdk.customRevenue(
  customEventName, // E.g. "purchase"


  currencyCode, // E.g. "USD"


  purchaseAmount // E.g. 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与谷歌AdMob、AppLovin、Unity LevelPlay(IronSource)和TradPlus等中介平台集成,用于广告收入归因。通过我们的通用广告收入 SDK 集成,Singular 还支持其他中介平台。

通过在 Singular SDK 集成中添加代码片段,您可以从中介平台获取广告收入归因数据。这也允许您获取 SKAdNetwork 活动的广告收入数据。

从您的调解平台获取用户级广告收入后,Singular 就能将归属广告收入发送回媒体源,这些媒体源可以接受这些数据来运行 AdROAS 广告系列。

请参阅 SDK 实施说明和代码片段[此处]。

添加深度链接支持

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

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

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

在应用程序中使用 Singular Links:

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

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

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

    Swift Objective-C
    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
    
            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)
        }
    }
    
  3. 在代码中初始化 Singular SDK 之前,在 Singular 配置对象中添加.withSingularLink 并指定链接处理函数:

    JavaScript
    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;
      // Add link handling logic here
    
    
    }
    
    singularConfig.withSingularLink(linkHandler);
    
    cordova.plugins.SingularCordovaSdk.init(singularConfig);
    

添加 SKAdNetwork 支持

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

托管模式(推荐)

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

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

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

JavaScript
var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("", "");

// Enable SKAdNetwork (in managed mode by default)


singularConfig.withSkAdNetworkEnabled(true);

cordova.plugins.SingularCordovaSdk.init(singularConfig);

手动模式

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

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

JavaScript
var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

// Enable SKAdNetwork


singularConfig.withSkAdNetworkEnabled(true);

// Select SKAdNetwork manual mode


singularConfig.withManualSkanConversionManagement();

// Optional: define handler to track changes to the conversion value


var conversionHandler = function(updatedConversionValue){
  // Do something with updatedConversionValue


}

singularConfig.withConversionValueUpdatedHandler(conversionHandler);

// Initialize the Singular SDK


cordova.plugins.SingularCordovaSdk.init(singularConfig);

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

JavaScript
cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
  newConversionValue,
  function(isSuccess){
    // isSuccess == true if the update was successful


  }
)

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

JavaScript
cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
  function(conversionValue){
    // Do something with conversionValue


  }
)

其他选项

跟踪卸载

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

Android:

JavaScript
cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS

JavaScript
cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

创建短推荐人链接

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

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

要创建短链接,您需要

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

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

JavaScript
cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    longLinkURL, 
    referrerName,
    referrerID,
    {
        // Tracking link parameters to add to the short link, e.g. "channel":"sms"


        param1: value1,
        param2: value2,
        ...
    },
    {
        onSuccess: function (shortLinkURL) {
        // Do something with shortLinkURL


        },
        onError: function (error) {
        // Handle error


        }
    }
)

遵守数据隐私法

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

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

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

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

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

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

SingularCordovaSdk.limitDataSharing方法
签名 SingularCordovaSdk.limitDataSharing(booleanshouldLimitDataSharing)
说明 通知 Singular 用户同意(opt-in)共享私人数据。限制数据共享方法为您提供了一个选项,以控制您的应用程序是否向第三方发送用户数据。如果您想根据用户偏好或隐私要求限制数据共享,这将非常有用。
使用示例
// User has opted into sharing data


cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

遵守 GDPR 的其他方法

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

SingularCordovaSdk.trackingOptIn 方法
说明 通知 Singular 用户同意(选择加入)跟踪。TrackingOptIn()方法用于向Singular服务器发送 "gdpr "事件。如果您不调用此方法,应用程序将继续跟踪用户,就像用户已经同意一样,但不会特别将其标记为 GDPR 选择加入。如果您的应用程序需要遵守 GDPR(《通用数据保护条例》),则应调用此功能,以确保正确记录用户同意。
使用示例
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();