SDK do Cordova - Referência de métodos

Seguir
Avatar
Jared Ornstead
Updated

SDK Cordova - Referência de Métodos

Esta referência abrangente documenta todos os métodos disponíveis no SDK da Singular para aplicativos Cordova. O SDK fornece funcionalidade para inicialização, rastreamento de eventos, relatórios de receita, atribuição, conformidade com a privacidade de dados e gerenciamento de SKAdNetwork. Cada método é apresentado com uma descrição, assinatura e exemplos práticos de uso para ajudar os desenvolvedores a integrar os recursos do SDK da Singular em seus aplicativos Cordova.

adRevenue

Método Singular.adRevenue

Rastreia eventos de receita de anúncios com informações detalhadas sobre os dados do anúncio. Este método permite-lhe comunicar as receitas geradas pelos anúncios apresentados no seu aplicativo com vários parâmetros para categorizar e analisar o desempenho do anúncio.

Assinatura

adRevenue(adData: Object): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

// Create ad data object with required fields
var adData = {
  ad_platform: 'AdMob',
  ad_currency: 'USD',
  ad_revenue: 0.05,
  ad_unit_id: 'ca-app-pub-1234567890123456',
  ad_type: 'Rewarded',
  ad_placement_name: 'level_complete'
};

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

clearGlobalProperties

Método Singular.clearGlobalProperties

Remove todas as propriedades globais definidas anteriormente. Isto é útil quando é necessário repor as propriedades globais, por exemplo, quando um usuário termina a sessão no seu aplicativo.

Assinatura

clearGlobalProperties(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

createReferrerShortLink

Método Singular.createReferrerShortLink

Cria um link curto com informações do referenciador que podem ser usadas para compartilhamento e atribuição. Este método gera links rastreáveis que podem ser compartilhados com os usuários, permitindo-lhe atribuir instalações e atividades a fontes de referência específicas.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

// 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
);

customRevenue

Método Singular.customRevenue

Rastreia eventos de receita personalizados com um nome de evento, moeda e valor especificados. Isto permite um controle de receitas mais específico com nomes de eventos personalizados.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

customRevenueWithArgs

Método Singular.customRevenueWithArgs

Rastreia eventos de receitas personalizados com um nome de evento, moeda, montante e atributos adicionais especificados. Isto permite um controle mais detalhado das receitas com parâmetros personalizados.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

event

Método Singular.event

Rastreia eventos com o nome especificado. Utilize este método para seguir as ações e o envolvimento do usuário no seu aplicativo.

Assinatura

event(eventName: string): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

eventWithArgs

Método Singular.eventWithArgs

Utilize este método para acompanhar as ações do usuário com parâmetros detalhados.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

getGlobalProperties

Método Singular.getGlobalProperties

Recupera todas as propriedades globais atualmente definidas. Este método aceita uma função de retorno de chamada que recebe um objeto que contém todas as propriedades globais que foram definidas para o SDK.

Assinatura

getGlobalProperties(success: Function): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

getLimitDataSharing

Método Singular.getLimitDataSharing

Recupera o estado atual da limitação do compartilhamento de dados. Este método aceita uma função de retorno de chamada que recebe um booleano que indica se o compartilhamento de dados está atualmente limitado.

Assinatura

getLimitDataSharing(success: Function): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

handlePushNotification

Método Singular.handlePushNotification

Processa uma carga útil de notificação push para atribuição. Este método deve ser chamado quando seu aplicativo recebe uma notificação push para permitir que o Singular a atribua corretamente. Este método é apenas para iOS.

Assinatura

handlePushNotification(pushNotificationPayload: Object): void

Exemplo de uso

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

iapPurchase

Método Singular.iapPurchase

Cria um objeto de compra in-app (IAP) para rastrear a receita de compras in-app com validação de recibo específica da plataforma. Este construtor processa dados de compra de transacções da iOS App Store e da Android Play Store, formatando os dados para uma atribuição de receitas e verificação de recibos adequadas.

Assinatura

function SingularIAP(product: Object): SingularIAP

Exemplo de utilização

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

init

Método Singular.init

Inicializa o Singular SDK com a configuração especificada. Este método deve ser chamado antes de qualquer outro método do SDK. O objeto de configuração deve incluir sua chave de API, segredo e outras configurações opcionais.

Assinatura

init(singularConfig: SingularConfig): void

Exemplo de uso

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;
var SingularConfig = cordova.plugins.SingularCordovaSdk.SingularConfig;

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

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

isAllTrackingStopped

Método Singular.isAllTrackingStopped

Verifica se todo o rastreamento foi interrompido. Este método aceita uma função de retorno de chamada que recebe um booleano indicando o estado atual do rastreamento.

Assinatura

isAllTrackingStopped(success: Function): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

limitDataSharing

Método Singular.limitDataSharing

Define o estado de limitação do compartilhamento de dados. Utilize este método para cumprir os regulamentos de privacidade, limitando os dados que são compartilhados com terceiros.

Assinatura

limitDataSharing(value: boolean): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

resumeAllTracking

Método Singular.resumeAllTracking

Retoma todas as atividades de rastreamento depois de terem sido interrompidas. Utilize este método para voltar a ativar o rastreamento quando os usuários optarem por voltar a participar.

Assinatura

resumeAllTracking(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

revenue

Método Singular.revenue

Rastreia eventos de receita com uma moeda e um montante especificados. Este é o método básico para rastrear receitas sem atributos adicionais.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

revenueWithArgs

Método Singular.revenueWithArgs

Monitoriza eventos de receitas com uma moeda, um montante e atributos adicionais especificados. Isto permite um controle mais detalhado das receitas com parâmetros personalizados.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

setCustomUserId

Método Singular.setCustomUserId

Define um ID de usuário personalizado para a sessão atual. Isto permite-lhe associar dados Singular ao seu próprio sistema de identificação de usuários.

Assinatura

setCustomUserId(userId: string): void

Exemplo de uso

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

setGlobalProperty

Método Singular.setGlobalProperty

Define uma propriedade global que será enviada com todos os eventos subsequentes. Isso é útil para rastrear atributos persistentes do usuário ou estado do aplicativo. O método aceita uma função de retorno de chamada que recebe um booleano indicando sucesso.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

setLimitAdvertisingIdentifiers

Método Singular.setLimitAdvertisingIdentifiers

Controla se os identificadores de publicidade (IDFA/GAID) devem ser limitados. Utilize este método para cumprir as preferências e os regulamentos em matéria de privacidade.

Assinatura

setLimitAdvertisingIdentifiers(enabled: boolean): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

setUninstallToken

Método Singular.setUninstallToken

Define o token de notificação push para rastreamento de desinstalação. Isso permite que o Singular rastreie as desinstalações de aplicativos monitorando as falhas de entrega de notificações push.

Assinatura

setUninstallToken(token: string): void

Exemplo de uso

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

skanGetConversionValue

Método Singular.skanGetConversionValue

Recupera o valor de conversão atual de SKAdNetwork. Este método aceita uma função de retorno de chamada que recebe o valor de conversão atual como um número. Este método é apenas para iOS.

Assinatura

skanGetConversionValue(success: Function): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

skanRegisterAppForAdNetworkAttribution

Método Singular.skanRegisterAppForAdNetworkAttribution

Registra o aplicativo para atribuição de SKAdNetwork. Este método deve ser chamado no início do ciclo de vida do aplicativo para permitir o rastreamento da SKAdNetwork. Este método é exclusivo do iOS.

Assinatura

skanRegisterAppForAdNetworkAttribution(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

skanUpdateConversionValue

Método Singular.skanUpdateConversionValue

Atualiza o valor de conversão SKAdNetwork. Este método é utilizado para SKAdNetwork 2.0-3.0 e aceita uma função de retorno de chamada que recebe um booleano indicando se a atualização foi bem sucedida. Este método é exclusivo do iOS.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

skanUpdateConversionValues

Método Singular.skanUpdateConversionValues

Atualiza os valores de conversão da SKAdNetwork 4.0 com o valor fino, o valor grosso e o estado de bloqueio. Este método é para iOS 16.1+ e aceita uma função de retorno de chamada que recebe um booleano indicando sucesso. Este método é exclusivo do iOS.

Assinatura

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

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

// 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

Método Singular.stopAllTracking

Interrompe todas as atividades de rastreamento. Utilize este método para desativar o rastreamento quando os usuários optam por não o fazer ou para garantir a conformidade com a privacidade.

Assinatura

stopAllTracking(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

trackingOptIn

Método Singular.trackingOptIn

Indica que o usuário optou por aceitar o rastreamento. Chame este método quando o usuário consentir explicitamente no rastreamento e na coleta de dados.

Assinatura

trackingOptIn(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

trackingUnder13

Método Singular.trackingUnder13

Indica que o usuário tem menos de 13 anos de idade. Chame este método para cumprir a COPPA e outros regulamentos para usuários com menos de 13 anos.

Assinatura

trackingUnder13(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

unsetCustomUserId

Método Singular.unsetCustomUserId

Remove o ID de usuário personalizado definido anteriormente. Chame este método quando o usuário terminar a sessão ou quando já não pretender associar eventos ao ID de usuário atual.

Assinatura

unsetCustomUserId(): void

Exemplo de utilização

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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

unsetGlobalProperty

Método Singular.unsetGlobalProperty

Remove uma propriedade global previamente definida. Chame este método quando já não quiser que uma propriedade global específica seja enviada com eventos.

Assinatura

unsetGlobalProperty(key: string): void

Exemplo de uso

JavaScript 
var Singular = cordova.plugins.SingularCordovaSdk;

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