Cordova SDK - 配置方法参考

关注
Avatar
Jared Ornstead
Updated
文档

Cordova SDK - 配置参考

本文档全面介绍了用于 Cordova 应用程序的 Singular SDK 中的所有配置选项。通过 SingularConfig 对象，您可以自定义 SDK 的行为，包括跟踪设置、属性选项、隐私控制等。每个配置属性都附有说明、签名和实际使用示例。

apikey

SingularConfig.apikey 属性

你的 Singular API 密钥。这是配置初始化过程中必须设置的属性。

签名

apikey: string

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

品牌域名

SingularConfig.brandedDomains 属性

为网络到应用程序属性设置品牌域。这允许你指定为归因目的而跟踪的自定义域名。

签名

brandedDomains: Array<string>

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET');
config.withBrandedDomains(['yourcompany.com', 'go.yourcompany.com']);

剪贴板属性

SingularConfig.clipboardAttribution 属性

启用 iOS 的剪贴板属性。启用后，SDK 将检查剪贴板中的属性数据。

签名

clipboardAttribution: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withClipboardAttribution();

collectOAID

SingularConfig.collectOAID 属性

为 Android 启用 OAID（开放式匿名设备标识符）收集功能。 该功能主要用于在无法使用 Google Play 服务的中国进行跟踪。默认值为 false。

签名

collectOAID: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withOAIDCollection();

conversionValueUpdatedHandler

SingularConfig.conversionValueUpdatedHandler 属性

设置 SKAdNetwork 转换值更新时调用的回调处理程序。这对跟踪 iOS 上转换值的变化非常有用。

签名

conversionValueUpdatedHandler: Function

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withConversionValueUpdatedHandler(function(conversionValue) {
    console.log('Conversion value updated:', conversionValue);
  });

conversionValuesUpdatedHandler

SingularConfig.conversionValuesUpdatedHandler 属性

设置 SKAdNetwork 4.0 转换值更新时调用的回调处理程序。该回调接收精细值、粗略值和 iOS 16.1+ 的锁定状态。

签名

conversionValuesUpdatedHandler: Function

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withConversionValuesUpdatedHandler(function(values) {
    console.log('Conversion values updated:', values);
  });

自定义值

企业功能--请联系您的客户成功经理为您的账户启用此功能。

SingularConfig.customSdid 属性

设置自定义 SDID（Singular 设备 ID）。这允许您提供自己的设备标识符，而不是使用 Singular 生成的标识符。

签名

customSdid: string

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id-12345',
    function(sdid) {
      console.log('SDID was set:', sdid);
    },
    function(sdid) {
      console.log('SDID received:', sdid);
    }
  );

自定义用户标识

SingularConfig.customUserId 属性

在 SDK 初始化过程中设置自定义用户 ID。这样就可以从一开始就将 Singular 数据与自己的用户识别系统关联起来。

签名

customUserId: string

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomUserId('user123456');

deviceAttributionCallbackHandler

BETA 功能- 设置设备属性数据可用时调用的回调函数。

SingularConfig.deviceAttributionCallbackHandler 属性

设置设备属性数据可用时调用的回调处理程序。这样就可以在属性数据解析后立即访问该数据。

签名

deviceAttributionCallbackHandler: Function

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withDeviceAttributionCallbackHandler(function(attributes) {
    console.log('Attribution data received:', attributes);
    var campaign = attributes.campaign;
    var source = attributes.source;
  });

didSetSdidCallback

企业功能- 设置自定义 SDID 时调用的回调。

SingularConfig.didSetSdidCallback 属性

设置自定义 SDID 设置时调用的回调函数，与 customSdid 属性结合使用。

签名

didSetSdidCallback: Function

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id',
    function(result) {
      console.log('SDID was set:', result);
    },
    function(result) {
      console.log('SDID received:', result);
    }
  );

启用记录

SingularConfig.enableLogging 属性

为调试目的启用 SDK 日志。这在开发和故障排除过程中非常有用。建议在生产构建中禁用日志记录。默认值为 false。

签名

enableLogging: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLoggingEnabled();

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval 属性

启用具有指定超时间隔的设备上测量。此功能允许进行注重隐私的测量。默认值为-1（禁用）。

签名

enableOdmWithTimeoutInterval: number

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withEnableOdmWithTimeoutInterval(30);

espDomains

SingularConfig.espDomains 属性

为基于电子邮件的归因设置 ESP（电子邮件服务提供商）域，以便跟踪电子邮件营销活动的归因。

签名

espDomains: Array<string>

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withESPDomains(['email.example.com', 'mail.company.com']);

facebookAppId

SingularConfig.facebookAppId 属性

为 Facebook 归因整合设置 Facebook 应用程序 ID。这可实现与 Facebook 归因系统的深度集成。

签名

facebookAppId: string

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withFacebookAppId('1234567890123456');

globalProperties

SingularConfig.globalProperties 属性

在初始化过程中设置全局属性，这些属性将随所有后续事件一起发送。这对于跟踪持久用户属性或应用程序状态非常有用。

签名

globalProperties: Object

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withGlobalProperty('user_tier', 'premium', true)
  .withGlobalProperty('region', 'north_america', true);

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers 属性

控制是否限制广告标识符（IDFA/GAID）。 使用此属性可遵守隐私偏好和法规。默认值为 false。

签名

limitAdvertisingIdentifiers: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLimitAdvertisingIdentifiers(true);

limitDataSharing

SingularConfig.limitDataSharing 属性

在初始化过程中设置数据共享限制状态。使用此属性可限制与第三方共享的数据，从而遵守隐私法规。默认值为空。

签名

limitDataSharing: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLimitDataSharing(true);

日志级别

SingularConfig.logLevel 属性

设置 SDK 日志级别，以便对日志输出进行更精细的控制。 这样就可以指定 SDK 日志的冗长程度。

签名

logLevel: number

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLogLevel(3); // Set appropriate log level

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 属性

启用手动 SKAdNetwork 转换值管理。启用后，您必须手动更新转换值，而不是依赖自动更新。默认值为 false。

签名

manualSkanConversionManagement: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withManualSkanConversionManagement();

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths 属性

配置从推送通知有效负载中提取深度链接的自定义路径。这样就可以指定深层链接在通知有效负载中的位置。

签名

pushNotificationsLinkPaths: Array<Array<string>>

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withPushNotificationsLinkPaths([
    ['data', 'deeplink'],
    ['notification', 'data', 'url'],
    ['custom', 'link']
  ]);

sdidReceivedCallback

企业功能- 收到 SDID 时调用的回调。

SingularConfig.sdidReceivedCallback 属性

设置从服务器接收 SDID 时调用的回调函数。此属性与自定义 SDID 属性结合使用。

签名

sdidReceivedCallback: Function

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id',
    function(result) { console.log('SDID set:', result); },
    function(result) { console.log('SDID received:', result); }
  );

秘密

SingularConfig.secret 属性

你的 Singular SDK 密钥。这是配置初始化时必须设置的属性。

签名

secret: string

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

sessionTimeout

SingularConfig.sessionTimeout 属性

设置会话超时（以秒为单位）。这决定了应用程序进入后台后用户会话的持续时间。默认值为-1（使用默认超时 60 秒）。

签名

sessionTimeout: number

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withSessionTimeoutInSec(120); // 2 minutes

shortLinkResolveTimeout

SingularConfig.shortLinkResolveTimeout 属性

设置短链接解析超时（以秒为单位）。这决定了 SDK 等待短链接解析的时间。默认值为 10 秒。

签名

shortLinkResolveTimeout: number

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withShortLinkResolveTimeout(15);

singularLinkHandler

SingularConfig.singularLinkHandler 属性

设置奇异链接（深度链接）的回调处理程序。当应用程序通过奇异链接打开时，将调用该回调，以便处理深度链接逻辑。

签名

singularLinkHandler: Function

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withSingularLink(function(singularLinkParams) {
    console.log('Deep link opened:', singularLinkParams);
    var deeplink = singularLinkParams.deeplink;
    var passthrough = singularLinkParams.passthrough;
    // Handle navigation based on deep link data
  });

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled 属性

启用或禁用 iOS 的 SKAdNetwork 支持。启用后，SDK 将自动处理 SKAdNetwork 归属。默认值为 true。

签名

skAdNetworkEnabled: boolean

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withSkAdNetworkEnabled(true);

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval 属性

设置在初始化 SDK 之前等待 iOS ATT（应用程序跟踪透明度）授权的超时时间间隔。默认值为 0（不等待）。

签名

waitForTrackingAuthorizationWithTimeoutInterval: number

使用示例

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withWaitForTrackingAuthorizationWithTimeoutInterval(60); // Wait up to 60 seconds

完整配置示例

下面是一个综合示例，展示如何通过多个选项配置 Singular SDK：

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

// Create configuration with API key and secret
var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET')
  .withCustomUserId('user123456')
  .withSessionTimeoutInSec(120)
  .withLoggingEnabled()
  .withSingularLink(function(params) {
    console.log('Deep link:', params.deeplink);
  })
  .withConversionValueUpdatedHandler(function(value) {
    console.log('Conversion value:', value);
  })
  .withGlobalProperty('user_tier', 'premium', true)
  .withGlobalProperty('app_version', '2.1.0', true)
  .withShortLinkResolveTimeout(15);

// Initialize the SDK
Singular.init(config);