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 安装推荐人归属支持
   自 2025 年 6 月 18 日起，Meta 的高级移动测量报告 (AMM)不再需要实施 Meta Install Referrer。如果启用了 AMM 报告，则不建议实施 Meta 安装 Referrer。
   启用"Meta Install Referrer "归因所需的 SDK 配置：
   1. 在奇异配置对象中提供您的Facebook 应用程序 ID。
      

      // To enable META Install Referrer
      singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

   在哪里可以找到应用程序的 Facebook 应用程序 ID？
4. 使用 SingularConfig 对象初始化 SDK。

代码示例（注释了可选设置）：

// 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);
*/

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

跟踪事件（非收入）

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

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

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

// 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库，可以使用以下代码：

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, // E.g. "purchase"
  currencyCode, // E.g. "USD"
  purchaseAmount // E.g. 3.2
);

混合事件跟踪（高级）

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

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

混合事件跟踪指南

跟踪广告收入归属

添加深度链接支持

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

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

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

   import singular_cordova_sdk.SingularCordovaSdk
   
   override fun 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)
       }
   }
   

   #import "SingularCordovaSdk.h"
   #import "MainViewController.h"
   
   - (BOOL)application:(UIApplication *)application 
   didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       // Initialize window
       self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
       
       // Configure view controller
       self.viewController = [[MainViewController alloc] init];
       self.window.rootViewController = self.viewController;
       
       // Initialize Singular SDK
       [SingularCordovaSdk setLaunchOptions:launchOptions];
       
       // Make window visible
       [self.window makeKeyAndVisible];
       
       return YES;
   }
   
   - (BOOL)application:(UIApplication *)application
   continueUserActivity:(NSUserActivity *)userActivity
   restorationHandler:(void (^)(NSArray<id> *))restorationHandler {
       return [SingularCordovaSdk startSessionWithUserActivity: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);
   

其他选项

跟踪卸载

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

// User has opted into sharing data
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();