先决条件

在安装 Singular Cordova SDK 之前，请完成以下先决条件步骤，以确保集成过程顺利。

安装

安装 Singular 插件

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

通过 Cordova CLI 安装

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

   cordova plugin add singular_cordova_sdk

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

   cordova plugin list

Ionic Framework 集成

如果您正在使用 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. 在 platform ready 事件中初始化：使用 platform ready 事件，确保在 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 配置

配置 Android 专属权限和设置，以启用 SDK 核心 功能及归因追踪。

添加必需权限

在 Cordova 的 config.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 安装来源归因

配置 Meta（Facebook）安装来源归因，以追踪 来自 Facebook 和 Instagram 广告活动的安装。

启用 Meta 安装来源

如果未启用 AMM，或者您需要 Meta 安装来源追踪功能进行旧版追踪， 请在 SDK 配置中添加您的 Facebook 应用 ID。

1. 查找 Facebook App ID：登录您的 Facebook 开发者账户 并导航至应用仪表盘以查找 App 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);

高级配置

Google Ads iOS 集成转化测量必备

如果您的应用运行针对 iOS 14.5 及以上版本用户的 Google Ads 广告系列，则需要执行额外的 SDK 配置步骤以支持 iOS 集成转化 测量 (ICM)。这包括：

• 集成 Google 的设备端测量 (ODM) SDK
• 更新至 Singular iOS SDK v12.8.1 及以上版本（Unity 版本需 v5.5.0 及以上，Flutter/Cordova 版本需 v1.8.0 及以上，React Native 版本需 v3.9.0 及以上）
• 添加-ObjC 链接器标志，并在SingularConfig中启用 enableOdmWithTimeoutInterval

注意：启用enableOdmWithTimeoutInterval 会延迟 SDK 的初始化，并可能推迟深度链接回调。请在初始 SDK 实现阶段完成此配置， 以避免后续返工。

参阅完整的 iOS ICM 技术要求