Cordova SDK - 方法参考

关注
Avatar
Jared Ornstead
Updated
文档

Cordova SDK - 方法参考

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

广告收入

Singular.adRevenue 方法

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

签名

adRevenue(adData: Object): void

使用示例

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

// Create ad data object with required fields
var adData = {
  adPlatform: 'AdMob',
  currency: 'USD',
  revenue: 0.05,
  adUnitId: 'ca-app-pub-1234567890123456',
  adType: 'Rewarded',
  adPlacementName: 'level_complete'
};

// Track ad revenue event
Singular.adRevenue(adData);

清除全局属性

Singular.clearGlobalProperties 方法

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

签名

clearGlobalProperties(): void

使用示例

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

// Clear all global properties
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink 方法

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

签名

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

使用示例

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

// Create a short link for referral
var resultHandler = {
  onSuccess: function(link) {
    console.log('Generated short link:', link);
    // Share the link with users
  },
  onError: function(error) {
    console.error('Error creating short link:', error);
  }
};

Singular.createReferrerShortLink(
  'https://sample.sng.link/B4tbmv8fp',
  'John Doe',
  'aq239897',
  { channel: 'sms', campaign: 'summer_promo' },
  resultHandler
);

自定义收入

Singular.customRevenue 方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。这允许使用自定义事件名称进行更具体的收入跟踪。

签名

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

使用示例

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

// Track a custom revenue event
Singular.customRevenue('premium_subscription', 'USD', 9.99);

customRevenueWithArgs

Singular.customRevenueWithArgs 方法

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

签名

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

使用示例

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

// Track a custom revenue event with attributes
Singular.customRevenueWithArgs(
  'in_app_purchase',
  'USD',
  5.99,
  {
    product_id: 'com.app.gems_pack_small',
    quantity: 1
  }
);

事件

Singular.event 方法

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

签名

event(eventName: string): void

使用示例

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

// Track a simple event
Singular.event('level_completed');

eventWithArgs

Singular.eventWithArgs 方法

跟踪具有指定名称和附加自定义属性的事件。 使用此方法可跟踪具有详细参数的用户操作。

签名

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

使用示例

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

// Track an event with additional parameters
Singular.eventWithArgs('level_completed', {
  level_id: 5,
  score: 12500,
  time_spent: 120,
  difficulty: 'medium'
});

获取全局属性

Singular.getGlobalProperties 方法

读取当前设置的所有全局属性。该方法接受一个回调函数，该函数接收一个包含所有已为 SDK 设置的全局属性的对象。

签名

getGlobalProperties(success: Function): void

使用示例

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

// Get all global properties
Singular.getGlobalProperties(function(properties) {
  console.log('Global properties:', properties);
});

getLimitDataSharing

Singular.getLimitDataSharing 方法

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

签名

getLimitDataSharing(success: Function): void

使用示例

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

// Check if data sharing is limited
Singular.getLimitDataSharing(function(isLimited) {
  if (isLimited) {
    console.log('Data sharing is currently limited');
  }
});

handlePushNotification

Singular.handlePushNotification 方法

处理推送通知有效载荷，以确定归属。当应用程序收到推送通知时，应调用此方法，以便 Singular 能正确归属该通知。此方法仅适用于 iOS。

签名

handlePushNotification(pushNotificationPayload: Object): void

使用示例

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

// Handle a received push notification (iOS only)
if (device.platform === 'iOS') {
  var userInfo = remoteMessage.data;
  Singular.handlePushNotification(userInfo);
}

iapPurchase

SingularIAP 构造函数

创建应用程序内购买 (IAP) 对象，用于跟踪应用程序内购买的收入，并进行特定平台的收据验证。该构造函数可处理 iOS App Store 和 Android Play Store 交易中的购买数据，格式化数据以正确归属收入和验证收据。

签名

function SingularIAP(product: Object): SingularIAP

使用示例

JavaScript 
var SingularIAP = require('./SingularIAP');

// Example for Android Play Store purchase
var androidProduct = {
  currency: 'USD',
  price: '$4.99',
  id: 'com.app.premium_gems',
  transaction: {
    type: 'android-playstore',
    receipt: 'eyJvcmRlcklkIjoiR1BBLjEyMzQ...',
    signature: 'signature_string_here'
  }
};

var androidIAP = new SingularIAP(androidProduct);

// Example for iOS App Store purchase
var iosProduct = {
  currency: 'USD',
  price: '$4.99',
  id: 'com.app.premium_gems',
  transaction: {
    type: 'ios-appstore',
    appStoreReceipt: 'MIITtQYJKoZIhvcNAQcCoIITpj...',
    id: 'transaction_identifier_123'
  }
};

var iosIAP = new SingularIAP(iosProduct);

// The resulting object contains:
// - ppc: product currency
// - r: revenue amount (parsed from price string)
// - is_revenue_event: true
// Platform-specific fields:
// Android: ptr, receipt, receipt_signature
// iOS: ptr, pti, pk

启动

Singular.init 方法

使用指定配置初始化 Singular SDK。此方法必须在其他 SDK 方法之前调用。配置对象应包括 API 密钥、保密信息和其他可选设置。

签名

init(singularConfig: SingularConfig): void

使用示例

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

// Create and configure the SDK
var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

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

isAllTrackingStopped

Singular.isAllTrackingStopped 方法

检查是否已停止所有跟踪。该方法接受一个回调函数，该函数接收一个布尔值，表示当前的跟踪状态。

签名

isAllTrackingStopped(success: Function): void

使用示例

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

// Check if tracking is stopped
Singular.isAllTrackingStopped(function(isStopped) {
  if (isStopped) {
    console.log('All tracking is currently stopped');
  }
});

limitDataSharing

Singular.limitDataSharing 方法

设置数据共享限制状态。使用此方法可限制与第三方共享的数据，从而遵守隐私法规。

签名

limitDataSharing(value: boolean): void

使用示例

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

// Enable data sharing limitation
Singular.limitDataSharing(true);

resumeAllTracking

Singular.resumeAllTracking 方法

在跟踪活动停止后恢复所有跟踪活动。当用户选择重新加入时，使用此方法可重新启用跟踪功能。

签名

resumeAllTracking(): void

使用示例

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

// Resume tracking when user opts back in
Singular.resumeAllTracking();

收入

Singular.revenue 方法

使用指定的货币和金额跟踪收入事件。这是跟踪收入的基本方法，没有附加属性。

签名

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

使用示例

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

// Track a simple revenue event
Singular.revenue('USD', 9.99);

revenueWithArgs

Singular.revenueWithArgs 方法

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

签名

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

使用示例

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

// Track a revenue event with attributes
Singular.revenueWithArgs(
  'USD',
  9.99,
  {
    product_id: 'premium_monthly',
    transaction_id: 'txn_12345'
  }
);

setCustomUserId

Singular.setCustomUserId 方法

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

签名

setCustomUserId(userId: string): void

使用示例

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

// Set custom user ID after login
Singular.setCustomUserId('user123456');

设置全局属性

Singular.setGlobalProperty 方法

设置一个全局属性，该属性将与所有后续事件一起发送。 这对于跟踪持久用户属性或应用程序状态非常有用。该方法接受一个回调函数，该函数接收一个表示成功的布尔值。

签名

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

使用示例

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

// Set a global property
Singular.setGlobalProperty(
  'user_tier',
  'premium',
  true,
  function(success) {
    if (success) {
      console.log('Global property set successfully');
    }
  }
);

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers 方法

控制是否限制广告标识符（IDFA/GAID）。 使用此方法可遵守隐私偏好和法规。

签名

setLimitAdvertisingIdentifiers(enabled: boolean): void

使用示例

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

// Limit advertising identifiers
Singular.setLimitAdvertisingIdentifiers(true);

设置卸载令牌

Singular.setUninstallToken 方法

设置用于卸载跟踪的推送通知令牌。这样，Singular 就能通过监控推送失败来跟踪应用程序的卸载情况。

签名

setUninstallToken(token: string): void

使用示例

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

// Set the push notification token for uninstall tracking
Singular.setUninstallToken('your-fcm-or-apns-token-here');

skanGetConversionValue

Singular.skanGetConversionValue 方法

读取当前 SKAdNetwork 转换值。该方法接受一个回调函数，以数字形式接收当前转换值。 该方法仅适用于 iOS。

签名

skanGetConversionValue(success: Function): void

使用示例

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

// Get current SKAdNetwork conversion value (iOS only)
if (device.platform === 'iOS') {
  Singular.skanGetConversionValue(function(value) {
    console.log('Current conversion value:', value);
  });
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 方法

为 SKAdNetwork 归属注册应用程序。应在应用程序生命周期的早期调用此方法，以启用 SKAdNetwork 跟踪。此方法仅适用于 iOS。

签名

skanRegisterAppForAdNetworkAttribution(): void

使用示例

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

// Register for SKAdNetwork attribution (iOS only)
if (device.platform === 'iOS') {
  Singular.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue 方法

更新 SKAdNetwork 转换值。该方法用于 SKAdNetwork 2.0-3.0，接受一个回调函数，该函数接收一个布尔值，表示更新是否成功。此方法仅限 iOS。

签名

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

使用示例

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

// Update SKAdNetwork conversion value (iOS only)
if (device.platform === 'iOS') {
  Singular.skanUpdateConversionValue(3, function(success) {
    if (success) {
      console.log('Conversion value updated successfully');
    }
  });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 方法

用精细值、粗略值和锁定状态更新 SKAdNetwork 4.0 转换值。该方法适用于 iOS 16.1+ 并接受一个回调函数，该函数接收一个布尔值，表示成功。此方法仅适用于 iOS。

签名

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

使用示例

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

// Update SKAdNetwork 4.0 conversion values (iOS 16.1+)
if (device.platform === 'iOS') {
  Singular.skanUpdateConversionValues(
    5,     // fine value (0-63)
    1,     // coarse value (0=low, 1=medium, 2=high)
    false, // lock
    function(success) {
      if (success) {
        console.log('Conversion values updated successfully');
      }
    }
  );
}

stopAllTracking

Singular.stopAllTracking 方法

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

签名

stopAllTracking(): void

使用示例

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

// Stop tracking when user opts out
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn 方法

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

签名

trackingOptIn(): void

使用示例

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

// User has opted in to tracking
Singular.trackingOptIn();

trackingUnder13

Singular.trackingUnder13 方法

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

签名

trackingUnder13(): void

使用示例

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

// Notify Singular the user is under 13 years old
Singular.trackingUnder13();

unsetCustomUserId

Singular.unsetCustomUserId 方法

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

签名

unsetCustomUserId(): void

使用示例

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

// Clear custom user ID when user logs out
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty 方法

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

签名

odedeunsetGlobalProperty(key: string): void

使用示例

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

// Remove a global property
Singular.unsetGlobalProperty('user_tier');