SDK do Cordova - Referência de métodos

Seguir
Avatar
Jared Ornstead
Updated
Documento de referência

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 na sua aplicação 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.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);

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 utilizador termina a sessão na sua aplicação.

Assinatura

clearGlobalProperties(): void

Exemplo de utilização

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

// 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 partilhados com os utilizadores, permitindo-lhe atribuir instalações e actividades 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.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
);

customRevenue

Método Singular.customRevenue

Rastreia eventos de receita personalizados com um nome de evento, moeda e valor especificados. Isto permite um controlo 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.require('singular-cordova-sdk');

// 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 controlo 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.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
  }
);

evento

Método Singular.event

Rastreia eventos com o nome especificado. Utilize este método para seguir as acções e o envolvimento do utilizador na sua aplicação.

Assinatura

event(eventName: string): void

Exemplo de utilização

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

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

eventWithArgs

Método Singular.eventWithArgs

Utilize este método para acompanhar as acções do utilizador com parâmetros detalhados.

Assinatura

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

Exemplo de utilização

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'
});

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.require('singular-cordova-sdk');

// 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 da partilha de dados. Este método aceita uma função de retorno de chamada que recebe um booleano que indica se a partilha de dados está atualmente limitada.

Assinatura

getLimitDataSharing(success: Function): void

Exemplo de utilização

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

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.require('singular-cordova-sdk');

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

iapCompra

Construtor SingularIAP

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

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 rastreio.

Assinatura

isAllTrackingStopped(success: Function): void

Exemplo de utilização

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

Método Singular.limitDataSharing

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

Assinatura

limitDataSharing(value: boolean): void

Exemplo de utilização

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

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

resumeAllTracking

Método Singular.resumeAllTracking

Retoma todas as actividades de rastreio depois de terem sido interrompidas. Utilize este método para voltar a ativar o rastreio quando os utilizadores optarem por voltar a participar.

Assinatura

resumeAllTracking(): void

Exemplo de utilização

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

// 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.require('singular-cordova-sdk');

// 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 controlo 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.require('singular-cordova-sdk');

// 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 utilizador personalizado para a sessão atual. Isto permite-lhe associar dados Singular ao seu próprio sistema de identificação de utilizadores.

Assinatura

setCustomUserId(userId: string): void

Exemplo de uso

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

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

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.require('singular-cordova-sdk');

// 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.require('singular-cordova-sdk');

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

Método Singular.skanRegisterAppForAdNetworkAttribution

Regista a aplicação para atribuição de SKAdNetwork. Este método deve ser chamado no início do ciclo de vida da aplicação para permitir o rastreio da SKAdNetwork. Este método é exclusivo do iOS.

Assinatura

skanRegisterAppForAdNetworkAttribution(): void

Exemplo de utilização

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

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

skanUpdateConversionValue

Método Singular.skanUpdateConversionValue

Actualiza 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.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

Método Singular.skanUpdateConversionValues

Actualiza 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.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

Método Singular.stopAllTracking

Interrompe todas as actividades de rastreio. Utilize este método para desativar o rastreio quando os utilizadores 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.require('singular-cordova-sdk');

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

trackingOptIn

Método Singular.trackingOptIn

Indica que o utilizador optou por aceitar o rastreio. Chame este método quando o utilizador consentir explicitamente no rastreio e na recolha de dados.

Assinatura

trackingOptIn(): void

Exemplo de utilização

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

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

trackingUnder13

Método Singular.trackingUnder13

Indica que o utilizador tem menos de 13 anos de idade. Chame este método para cumprir a COPPA e outros regulamentos para utilizadores com menos de 13 anos.

Assinatura

trackingUnder13(): void

Exemplo de utilização

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

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

unsetCustomUserId

Método Singular.unsetCustomUserId

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

Assinatura

unsetCustomUserId(): void

Exemplo de utilização

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

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

odedeunsetGlobalProperty(key: string): void

Exemplo de uso

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

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