Cordova SDK - SDK 方法参考

文档

Cordova SDK - SDK 方法参考

本综合参考文档记录了用于 Cordova 应用程序的 Singular SDK 中的所有可用方法。SDK 提供初始化、用户识别、事件跟踪、收入报告、归因、数据隐私合规性和配置等功能。每种方法都附有说明、签名和实际使用示例,以帮助开发人员将 Singular SDK 功能集成到自己的应用程序中。

广告收入

Singular.adRevenue 方法

通过详细的广告数据信息跟踪广告收入事件。通过该方法,您可以报告应用程序中显示的广告所产生的收入,并使用各种参数对广告性能进行分类和分析。

签名

static adRevenue(adData: SingularAdData): void

使用示例

javascript
// Create ad data object
const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData()
    .withAdPlatform("AdMob")
    .withAdType("Rewarded")
    .withNetworkName("Google")
    .withCurrency("USD")
    .withRevenue(0.05);

// Track ad revenue event
cordova.plugins.SingularCordovaSdk.adRevenue(adData);        

清除全局属性

Singular.clearGlobalProperties 方法

删除所有先前设置的全局属性。这在需要重置全局属性时非常有用,例如当用户注销应用程序时。

签名

static clearGlobalProperties(): void

使用示例

javascript
// Clear all global properties, for example when a user logs out
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink 方法

创建带有推荐人信息的短链接,可用于共享和归属。该方法可生成可与用户共享的可跟踪链接,从而将安装和活动归因于特定的推荐来源。

签名

static createReferrerShortLink(url: string, refName: string, refId: string, passthroughParams: Object, resultHandler: Object): void

使用示例

javascript
cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name
    "aq239897", // Referrer ID
    { 
        "channel": "sms", 
        "campaign": "summer_promo" 
    }, // Passthrough parameters
    {
        onSuccess: function(shortLinkURL) {
            console.log("Generated short link:", shortLinkURL);
            // Share the link with users
        },
        onError: function(error) {
            console.error("Error creating short link:", error);
        }
    }
);

自定义收入

Singular.customRevenue 方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。这样就可以使用自定义名称跟踪收入事件,以获得更具体的收入跟踪。

  • 注意:自定义收入事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符,转换为 UTF-8 后,限制为 32 字节。
  • 货币代码必须使用大写字母,并符合三个字母的ISO 4217货币 代码

签名

static customRevenue(eventName: string, currency: string, amount: number): void

使用示例

javascript
// Track a custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue("premium_subscription", "USD", 9.99);

customRevenueWithArgs

Singular.customRevenueWithArgs 方法

使用指定的事件名称、货币、金额和其他自定义属性跟踪自定义收入事件。这允许使用自定义参数进行更详细的收入跟踪。

  • 注意:自定义收入事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符,转换为 UTF-8 后限制为 32 字节。
  • 事件属性名称和属性值限制为 500 ASCII 字符
  • 货币代码必须使用大写字母,并符合三个字母的ISO 4217货币 代码

签名

static customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void

使用示例

javascript
// Track a custom revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.customRevenueWithArgs(
    "in_app_purchase",
    "USD",
    5.99,
    {
        "product_id": "com.app.gems_pack_small",
        "quantity": 1,
        "transaction_id": "T12345678",
        "receipt_id": "R98765432"
    }
);

事件

Singular.event 方法

跟踪具有指定名称的简单事件。使用该方法可跟踪应用程序中的用户操作和参与情况。

签名

static event(eventName: string): void

使用示例

javascript
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");

eventWithArgs

Singular.eventWithArgs 方法

跟踪具有指定名称和附加自定义属性的事件。这允许使用自定义参数进行更详细的事件跟踪。

签名

static eventWithArgs(eventName: string, args: Object): void

使用示例

javascript
// Track an event with additional parameters
cordova.plugins.SingularCordovaSdk.eventWithArgs(
    "level_completed",
    {
        "level_id": 5,
        "score": 12500,
        "time_spent": 120,
        "difficulty": "medium"
    }
);

获取全局属性

Singular.getGlobalProperties 方法

读取当前设置的所有全局属性。该方法返回一个对象,其中包含已为 SDK 设置的所有全局属性。

签名

static getGlobalProperties(success: Function): void

使用示例

javascript
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    console.log("Current global properties:", properties);
});

getLimitDataSharing

Singular.getLimitDataSharing 方法

读取当前的数据共享限制状态。该方法返回一个布尔值,表示当前数据共享是否受限。

签名

static getLimitDataSharing(success: Function): void

使用示例

javascript
// Check if data sharing is limited
cordova.plugins.SingularCordovaSdk.getLimitDataSharing(function(isLimited) {
    console.log("Data sharing is limited:", isLimited);
});

处理推送通知

Singular.handlePushNotification 方法

处理推送通知的有效载荷,以便进行归属。当应用程序接收到推送通知时,应调用此方法,以便 Singular 能正确归属该通知。

签名

static handlePushNotification(pushNotificationPayload: Object): void

使用示例

javascript
// Handle a received push notification
document.addEventListener('push-notification', function(event) {
    var notification = event.notification;
    cordova.plugins.SingularCordovaSdk.handlePushNotification(notification);
}, false);

启动

Singular.init 方法

使用提供的配置初始化 Singular SDK。这是开始使用 Singular SDK 时应该调用的第一个方法。

签名

static init(singularConfig: SingularConfig): void

使用示例

javascript
document.addEventListener('deviceready', function() {
    // Create configuration object
    var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
        "SDK KEY", 
        "SDK SECRET"
    );
    
    // Initialize the SDK
    cordova.plugins.SingularCordovaSdk.init(singularConfig);
}, false);

isAllTrackingStopped

Singular.isAllTrackingStopped 方法

检查当前是否停止了所有跟踪。此方法返回一个布尔值,表示当前跟踪是否停止。

签名

static isAllTrackingStopped(success: Function): void

使用示例

javascript
// Check if tracking is stopped
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped(function(isStopped) {
    console.log("Tracking is stopped:", isStopped);
});

limitDataSharing

Singular.limitDataSharing 方法

设置数据共享限制状态。使用该方法可根据用户同意或隐私要求限制数据共享。

签名

static limitDataSharing(value: boolean): void

使用示例

javascript
// Limit data sharing based on user consent
function onUserConsentChanged(hasConsent) {
    cordova.plugins.SingularCordovaSdk.limitDataSharing(!hasConsent);
}

收入

Singular.revenue 方法

使用指定的货币和金额跟踪收入事件。该方法用于报告应用程序中产生的收入。

  • 货币代码必须是大写字母,并符合三个字母的ISO 4217货币 代码

签名

static revenue(currency: string, amount: number): void

使用示例

javascript
// Track a revenue event
cordova.plugins.SingularCordovaSdk.revenue("USD", 4.99);

revenueWithArgs

Singular.revenueWithArgs 方法

使用指定的货币、金额和其他自定义属性跟踪收入事件。这允许使用自定义参数进行更详细的收入跟踪。

  • 事件属性名称和属性值限制为 500 ASCII 字符
  • 货币代码必须使用大写字母,并符合三个字母的ISO 4217 货币代码

签名

static revenueWithArgs(currency: string, amount: number, args: Object): void

使用示例

javascript
// Track a revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.revenueWithArgs(
    "USD",
    4.99,
    {
        "product_id": "com.app.premium_upgrade",
        "transaction_id": "T12345678"
    }
);

resumeAllTracking

Singular.resumeAllTracking 方法

恢复之前停止的所有跟踪活动。使用该方法可在停止跟踪后重新启用跟踪。

签名

static resumeAllTracking(): void

使用示例

javascript
// Resume tracking, for example when user opts back in
function onUserOptIn() {
    cordova.plugins.SingularCordovaSdk.resumeAllTracking();
}

setCustomUserId

Singular.setCustomUserId 方法

为当前用户设置自定义用户 ID。这样就可以将 Singular 数据与自己的用户识别系统关联起来。

签名

static setCustomUserId(userId: string): void

使用示例

javascript
// Set custom user ID after user logs in
function onUserLogin(userId) {
    cordova.plugins.SingularCordovaSdk.setCustomUserId(userId);
}

设置全局属性

Singular.setGlobalProperty 方法

设置将与所有事件一起发送的全局属性。这样,您就可以为所有事件添加一致的属性,而无需每次都指定这些属性。

签名

static setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

使用示例

javascript
// Set a global property
cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    "user_tier", 
    "premium", 
    true, 
    function(isSuccess) {
        console.log("Global property set successfully:", isSuccess);
    }
);

设置卸载令牌

Singular.setUninstallToken 方法

设置用于卸载跟踪的设备令牌。该方法应与推送通知令牌一起调用,以启用卸载跟踪。

签名

static setUninstallToken(token: string): void

使用示例

javascript
// Set uninstall token when push token is received
document.addEventListener('push-registration', function(event) {
    var token = event.registrationId;
    cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
}, false);

skanGetConversionValue

Singular.skanGetConversionValue 方法

读取当前 SKAdNetwork 转换值。该方法专用于 iOS,并返回用于 SKAdNetwork 归属的当前转换值。

签名

static skanGetConversionValue(success: Function): void

使用示例

javascript
// Get the current SKAdNetwork conversion value
cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(conversionValue) {
    console.log("Current conversion value:", conversionValue);
});

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 方法

为 SKAdNetwork 归因注册应用程序。此方法专用于 iOS,应调用此方法启用 SKAdNetwork 归因。

签名

static skanRegisterAppForAdNetworkAttribution(): void

使用示例

javascript
// Register for SKAdNetwork attribution
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue 方法

更新 SKAdNetwork 转换值。该方法专用于 iOS,允许您手动更新用于 SKAdNetwork 归属的转换值。

签名

static skanUpdateConversionValue(value: number, success: Function): void

使用示例

javascript
// Update the SKAdNetwork conversion value
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(5, function(isSuccess) {
        console.log("Conversion value updated successfully:", isSuccess);
    });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 方法

使用附加参数更新 SKAdNetwork 转换值。此方法专用于 iOS 16.1+,允许您更新 SKAdNetwork 4.0 属性的精细、粗略和锁定值。

签名

static skanUpdateConversionValues(value: number, coarse: string, lock: boolean, success: Function): void

使用示例

javascript
// Update the SKAdNetwork 4.0 conversion values
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
        5,           // fine value (0-63)
        "medium",    // coarse value (low/medium/high)
        false,       // lock
        function(isSuccess) {
            console.log("Conversion values updated successfully:", isSuccess);
        }
    );
}

stopAllTracking

Singular.stopAllTracking 方法

停止所有跟踪活动。使用该方法可在用户选择退出或符合隐私保护规定时禁用跟踪。

签名

static stopAllTracking(): void

使用示例

javascript
// Stop tracking, for example when user opts out
function onUserOptOut() {
    cordova.plugins.SingularCordovaSdk.stopAllTracking();
}

trackingOptIn

Singular.trackingOptIn 方法

表示用户已选择接受跟踪。当用户明确同意跟踪和数据收集时调用此方法。

签名

static trackingOptIn(): void

使用示例

javascript
// User has opted in to tracking
function onUserConsentGiven() {
    cordova.plugins.SingularCordovaSdk.trackingOptIn();
}

trackingUnder13

Singular.trackingUnder13 方法

表示用户未满 13 周岁。调用此方法可遵守 COPPA 和其他针对 13 岁以下用户的规定。

签名

static trackingUnder13(): void

使用示例

javascript
// If user is determined to be under 13 years old
cordova.plugins.SingularCordovaSdk.trackingunder13();
console.log("User marked as under 13, GDPR_UNDER_13 flag applied");

unsetCustomUserId

Singular.unsetCustomUserId 方法

删除之前设置的自定义用户 ID。当用户注销或不想再将事件与当前用户 ID 关联时,调用此方法。

签名

static unsetCustomUserId(): void

使用示例

javascript
// Clear custom user ID when user logs out
function onUserLogout() {
    cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
}

unsetGlobalProperty

Singular.unsetGlobalProperty 方法

删除先前设置的全局属性。如果不想再通过事件发送特定全局属性,请调用此方法。

签名

static unsetGlobalProperty(key: string): void

使用示例

javascript
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");