Cordova SDK - 配置方法参考

关注
Avatar
Jared Ornstead
Updated
文档

Cordova SDK - 配置方法参考

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

withClipboardAttribution

SingularConfig.withClipboardAttribution 方法

为 SDK 启用剪贴板属性。启用后，SDK 将在初始化过程中检查设备剪贴板上的属性链接。

签名

withClipboardAttribution(): SingularConfig

使用示例

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

withConversionValueUpdatedHandler

SingularConfig.withConversionValueUpdatedHandler 方法

设置 SKAdNetwork 转换值更新时调用的回调函数。这是 iOS 特有的功能，可让您对转换值变化做出反应。

签名

withConversionValueUpdatedHandler(conversionValueUpdatedHandler: Function): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withConversionValueUpdatedHandler(function(conversionValue) {
          console.log("Conversion value updated to:", conversionValue);
     }
);

withConversionValuesUpdatedHandler

SingularConfig.withConversionValuesUpdatedHandler 方法

设置 SKAdNetwork 4.0 转换值更新时调用的回调函数。这是 iOS 16.1+ 特有的功能，可让您对精细、粗略和锁定值的变化做出反应。

签名

withConversionValuesUpdatedHandler(conversionValuesUpdatedHandler: Function): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withConversionValuesUpdatedHandler(function(conversionValues) {
          console.log("Fine value:", conversionValues.fineValue);
          console.log("Coarse value:", conversionValues.coarseValue);
          console.log("Lock value:", conversionValues.lockValue);
     }
);

withCustomSdid

SingularConfig.withCustomSdid 方法

设置自定义 SDID（奇异设备 ID）和相关回调。这允许你提供自己的设备标识符，而不是使用 Singular 生成的设备标识符。

签名

withCustomSdid(customSdid: string, didSetSdidCallback: Function, sdidReceivedCallback: Function): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY", "SDK SECRET")
     .withCustomSdid("custom-device-id-12345",
     function(result) {
          console.log("SDID was set successfully:", result);
     },
     function(error) {
          console.error("Failed to set SDID:", error);
     }
);

withCustomUserId

SingularConfig.withCustomUserId 方法

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

签名

withCustomUserId(customUserId: string): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withCustomUserId("user-123456");

withDeviceAttributionCallbackHandler

SingularConfig.withDeviceAttributionCallbackHandler 方法

BETA 功能：设置设备属性数据可用时调用的回调函数。这样您就可以在属性数据可用时立即访问这些数据。

签名

withDeviceAttributionCallbackHandler(deviceAttributionCallbackHandler: Function): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withDeviceAttributionCallbackHandler(function(attributionData) {
     console.log("Attribution data:", attributionData);
     console.log("Campaign:", attributionData.campaign);
     console.log("Source:", attributionData.source);
});

withESPDomains

SingularConfig.withESPDomains 方法

设置电子邮件归因的 ESP（电子邮件服务提供商）域。这样，您就可以指定哪些电子邮件域应被视为归属。

签名

withESPDomains(espDomains: string[]): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withESPDomains([
    "mailchimp.com",
    "sendgrid.net",
    "campaign-monitor.com"
]);

withFacebookAppId

SingularConfig.withFacebookAppId 方法

为 Facebook 归因设置 Facebook 应用程序 ID。这样，SDK 就能对来自 Facebook 活动的安装和事件进行归因。

签名

withFacebookAppId(facebookAppId: string): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withFacebookAppId("123456789012345");

withGlobalProperty

SingularConfig.withGlobalProperty 方法

在 SDK 初始化过程中设置全局属性。该属性将与 SDK 跟踪的所有事件一起发送。

签名

withGlobalProperty(key: string, value: string, overrideExisting: boolean): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withGlobalProperty("app_version", "1.2.3", true);

withLimitDataSharing

SingularConfig.withLimitDataSharing 方法

在 SDK 初始化过程中设置数据共享限制状态。使用该方法可根据用户同意或隐私要求限制数据共享。

签名

withLimitDataSharing(shouldLimitDataSharing: boolean): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLimitDataSharing(true);

withLimitedIdentifiersEnabled

SingularConfig.withLimitedIdentifiersEnabled 方法

启用或禁用有限标识符的使用。该选项会影响 SDK 如何收集和使用设备标识符进行跟踪和归因。

签名

withLimitedIdentifiersEnabled(limitedIdentifiersEnabled: boolean): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLimitedIdentifiersEnabled(true);

withLogLevel

SingularConfig.withLogLevel 方法

设置 SDK 的日志级别。这将控制 SDK 生成的日志的冗长程度。

签名

withLogLevel(level: string): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLogLevel("verbose");

withLoggingEnabled

SingularConfig.withLoggingEnabled 方法

启用 SDK 的详细日志记录。启用后，SDK 将输出有助于调试的详细日志。

签名

withLoggingEnabled(): SingularConfig

使用示例

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

withManualSkanConversionManagement

SingularConfig.withManualSkanConversionManagement 方法

启用手动管理 SKAdNetwork 转换值。启用后，SDK 不会自动更新转换值，您可以手动控制转换值。

签名

withManualSkanConversionManagement(): SingularConfig

使用示例

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

withOAIDCollection

SingularConfig.withOAIDCollection 方法

在支持的 Android 设备上启用 OAID（开放式匿名设备标识符）收集。这是某些地区（尤其是中国）使用的替代标识符。

签名

withOAIDCollection(): SingularConfig

使用示例

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

withPushNotificationsLinkPaths

SingularConfig.withPushNotificationsLinkPaths 方法

设置在推送通知有效载荷中查找深度链接的路径。这有助于 SDK 查找和处理推送通知中的属性链接。

签名

withPushNotificationsLinkPaths(pushNotificationsLinkPaths: string[][]): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withPushNotificationsLinkPaths([
    ["data", "deeplink"],
    ["notification", "data", "url"],
    ["custom", "link"]
]);

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 方法

以秒为单位设置会话超时。这决定了应用程序进入后台后用户会话的持续时间。

签名

withSessionTimeoutInSec(sessionTimeout: number): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withSessionTimeoutInSec(120); // 2 minutes

withShortLinkResolveTimeout

SingularConfig.withShortLinkResolveTimeout 方法

设置解析短链接的超时（以秒为单位）。这决定了 SDK 在继续初始化之前等待短链接解析的时间。

签名

withShortLinkResolveTimeout(shortLinkResolveTimeout: number): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withShortLinkResolveTimeout(15); // 130 seconds

withSingularLink

SingularConfig.withSingularLink 方法

设置一个回调函数，用于处理由 Singular 处理的深层链接。这样，您的应用程序就能对归属中使用的深层链接做出响应。

签名

withSingularLink(singularLinkHandler: Function): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withSingularLink(function(data) {
    var deeplink = data.deeplink;
    var passthrough = data.passthrough;
    var isDeferred = data.isDeferred;
    
    console.log("Deep link received:", deeplink);
    
    if (deeplink) {
        // Handle the deep link, e.g., navigate to a specific screen
        navigateToScreen(deeplink);
    }
});

withSkAdNetworkEnabled

SingularConfig.withSkAdNetworkEnabled 方法

启用或禁用 SKAdNetwork 支持。这是 iOS 特有的功能，用于控制 SDK 是否使用 Apple 的 SKAdNetwork 进行归属。

签名

withSkAdNetworkEnabled(skAdNetworkEnabled: boolean): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withSkAdNetworkEnabled(true);

withWaitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval 方法

设置在 iOS 14+ 上等待用户跟踪授权响应的超时间隔（以秒为单位）。这将决定 SDK 在继续初始化之前等待 ATT 提示响应的时间。

签名

withWaitForTrackingAuthorizationWithTimeoutInterval(waitForTrackingAuthorizationWithTimeoutInterval: number): SingularConfig

使用示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withWaitForTrackingAuthorizationWithTimeoutInterval(30); // 30 seconds

完整配置示例

连锁多个配置选项

下面的示例演示了如何通过将多个配置方法连锁在一起来创建综合配置。

完整示例

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withWaitForTrackingAuthorizationWithTimeoutInterval(30)    
     .withCustomUserId("user-123456")
     .withGlobalProperty("key_1", "value1", true)     
     .withLimitDataSharing(false)
     .withFacebookAppId("123456789012345"); 
     .withSingularLink(function(data) {
          var deeplink = data.deeplink;
          var passthrough = data.passthrough;
          var isDeferred = data.isDeferred;
          console.log("Deep link received:", deeplink);

          if (deeplink) {
               // Handle the deep link
               navigateToScreen(deeplink);
          }
     })
    
// Initialize the SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);