Cordova SDK - SDK 方法参考
本综合参考文档记录了用于 Cordova 应用程序的 Singular SDK 中的所有可用方法。SDK 提供初始化、用户识别、事件跟踪、收入报告、归因、数据隐私合规性和配置等功能。每种方法都附有说明、签名和实际使用示例,以帮助开发人员将 Singular SDK 功能集成到自己的应用程序中。
广告收入
Singular.adRevenue 方法
通过详细的广告数据信息跟踪广告收入事件。通过该方法,您可以报告应用程序中显示的广告所产生的收入,并使用各种参数对广告性能进行分类和分析。
签名
static adRevenue(adData: SingularAdData): void
使用示例
// 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
使用示例
// 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
使用示例
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
使用示例
// 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
使用示例
// 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
使用示例
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");
eventWithArgs
Singular.eventWithArgs 方法
跟踪具有指定名称和附加自定义属性的事件。这允许使用自定义参数进行更详细的事件跟踪。
签名
static eventWithArgs(eventName: string, args: Object): void
使用示例
// 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
使用示例
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
console.log("Current global properties:", properties);
});
getLimitDataSharing
Singular.getLimitDataSharing 方法
读取当前的数据共享限制状态。该方法返回一个布尔值,表示当前数据共享是否受限。
签名
static getLimitDataSharing(success: Function): void
使用示例
// 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
使用示例
// 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
使用示例
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
使用示例
// 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
使用示例
// Limit data sharing based on user consent
function onUserConsentChanged(hasConsent) {
cordova.plugins.SingularCordovaSdk.limitDataSharing(!hasConsent);
}
收入
Singular.revenue 方法
使用指定的货币和金额跟踪收入事件。该方法用于报告应用程序中产生的收入。
签名
static revenue(currency: string, amount: number): void
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// 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
使用示例
// Stop tracking, for example when user opts out
function onUserOptOut() {
cordova.plugins.SingularCordovaSdk.stopAllTracking();
}
trackingOptIn
Singular.trackingOptIn 方法
表示用户已选择接受跟踪。当用户明确同意跟踪和数据收集时调用此方法。
签名
static trackingOptIn(): void
使用示例
// User has opted in to tracking
function onUserConsentGiven() {
cordova.plugins.SingularCordovaSdk.trackingOptIn();
}
trackingUnder13
Singular.trackingUnder13 方法
表示用户未满 13 周岁。调用此方法可遵守 COPPA 和其他针对 13 岁以下用户的规定。
签名
static trackingUnder13(): void
使用示例
// 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
使用示例
// Clear custom user ID when user logs out
function onUserLogout() {
cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
}
unsetGlobalProperty
Singular.unsetGlobalProperty 方法
删除先前设置的全局属性。如果不想再通过事件发送特定全局属性,请调用此方法。
签名
static unsetGlobalProperty(key: string): void
使用示例
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");