先决条件

在安装 Singular Cordova SDK 之前，请完成以下前提步骤，以确保集成过程顺利进行。

安装

安装 Singular 插件

使用 Cordova CLI 将 Singular 插件添加到您的 Cordova 项目中。 该插件为 iOS 和 Android 的本地 Singular SDK 提供 JavaScript 绑定。

通过 Cordova CLI 安装

1. 打开终端：导航至 Cordova 项目的根目录。
2. 添加插件：运行以下命令安装 Singular SDK 插件：
   bash

   cordova plugin add singular_cordova_sdk

3. 验证安装：通过检查config.xml 文件中的插件条目或运行以下命令，确认插件已添加：
   bash

   cordova plugin list

Ionic 框架集成

如果您使用 Ionic Framework 构建 Cordova 应用程序，请按照以下额外步骤正确集成 Singular SDK。

为 Ionic 安装插件

1. 通过 Ionic CLI 安装：使用 Ionic Cordova 命令添加插件：
   bash

   ionic cordova plugin add singular_cordova_sdk

2. 声明 Cordova 变量：在您的主 TypeScript 文件（通常为app.component.ts 或home.page.ts ）中，在顶部声明 Cordova 变量：
   TypeScript

   declare var cordova;

3. 在平台就绪时初始化：使用平台就绪事件确保在 SDK 初始化之前加载本地插件：
   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(() => {
         // Initialize Singular SDK here (see SDK Integration section)
   
       });
     }
   }

平台配置

安卓配置

配置特定于 Android 的权限和设置，以启用核心 SDK 功能和属性跟踪。

添加所需的权限

在 Cordovaconfig.xml 文件中添加必要的 Android 权限，以启用归因、网络访问和安装推荐人跟踪。

1. 打开 config.xml：导航至 Cordova 项目的根目录并打开config.xml 文件。
2. 添加权限：在<platform name="android"> 部分，添加以下权限：
   config.xml

   <platform name="android">
       <!-- Required for GAID collection and attribution -->
       <edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest">
           <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
       </edit-config>
   </platform>

其他权限（自动添加）

Singular Cordova 插件会自动添加以下权限，无需手动配置：

• android.permission.INTERNET - 数据传输的网络访问
• android.permission.ACCESS_NETWORK_STATE - 网络状态监控
• BIND_GET_INSTALL_REFERRER_SERVICE - 安装推荐人跟踪

iOS 配置

iOS 配置由 Cordova 插件自动处理。iOS 项目无需额外的手动配置步骤。

SDK 集成

每次启动应用程序时都要初始化Singular SDK。SDK 初始化对所有 Singular 归因功能都至关重要，并可创建一个新会话，用于计算用户留存指标。

基本 SDK 初始化

使用 SDK 凭据创建SingularConfig 对象，并使用init() 方法初始化 SDK。这项工作应在应用程序生命周期内尽早完成。

初始化示例

1. 获取凭据：登录Singular 账户，导航至 "开发工具" > "SDK 集成" > "SDK 密钥"，找到 SDK 密钥和秘钥。
2. 创建配置：使用凭据实例化SingularConfig 对象。
3. 初始化 SDK：调用init() 启动 SDK。

// Create the Singular configuration object
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

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

高级配置

在调用init() 之前，通过链式配置方法配置其他 SDK 功能。本示例演示了常用的配置选项，包括深度链接、日志记录和会话超时。

// Create configuration with credentials
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable debug logging (disable in production)
singularConfig.withLoggingEnabled();

// Set custom session timeout (default is 60 seconds)
singularConfig.withSessionTimeoutInSec(120);

// Configure deep linking handler
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;

  console.log("Received deep link:", deeplink);
  console.log("Is deferred:", isDeferred);

  // Handle navigation based on deep link
  if (deeplink) {
    // Navigate to appropriate screen
  }
};
singularConfig.withSingularLink(linkHandler);

// Set custom user ID (if user is logged in)
singularConfig.withCustomUserId("user_12345");

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

元安装推荐人归属

配置 Meta（Facebook）安装推荐人归因，以跟踪来自 Facebook 和 Instagram 广告系列的安装。

启用元安装推荐器

如果未启用 AMM 或需要使用 Meta Install Referrer 进行传统跟踪，请将您的 Facebook 应用程序 ID 添加到 SDK 配置中。

1. 查找 Facebook 应用 ID：登录Facebook Developer 帐户并导航到应用程序的控制面板以查找应用程序 ID。
2. 添加到配置：使用withFacebookAppId() 方法启用 Meta Install Referrer：
   JavaScript

   // Create configuration
   var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
     "YOUR_SDK_KEY",
     "YOUR_SDK_SECRET"
   );
   
   // Enable Meta Install Referrer
   singularConfig.withFacebookAppId("YOUR_FACEBOOK_APP_ID");
   
   // Initialize SDK
   cordova.plugins.SingularCordovaSdk.init(singularConfig);