Documento

SDK de Cordova - Referencia de métodos

Esta completa referencia documenta todos los métodos disponibles en el SDK de Singular para aplicaciones Cordova. El SDK proporciona funcionalidad para la inicialización, seguimiento de eventos, informes de ingresos, atribución, cumplimiento de privacidad de datos y gestión de SKAdNetwork. Cada método se presenta con una descripción, firma y ejemplos prácticos de uso para ayudar a los desarrolladores a integrar las capacidades del SDK de Singular en sus aplicaciones Cordova.

adRevenue

Método Singular.adRevenue

Realiza un seguimiento de los eventos de ingresos publicitarios con información detallada de los datos publicitarios. Este método le permite informar de los ingresos generados por los anuncios mostrados en su aplicación con varios parámetros para categorizar y analizar el rendimiento de los anuncios.

Firma

adRevenue(adData: Object): void

Ejemplo de uso

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

Singular.clearGlobalProperties Método

Elimina todas las propiedades globales establecidas previamente. Esto resulta útil cuando es necesario restablecer las propiedades globales, por ejemplo, cuando un usuario cierra la sesión de la aplicación.

Firma

clearGlobalProperties(): void

Ejemplo de uso

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

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

createReferrerEnlaceCorto

Singular.createReferrerShortLink Método

Crea un enlace corto con información de referencia que puede utilizarse para compartir y atribuir. Este método genera enlaces rastreables que pueden compartirse con los usuarios, permitiéndole atribuir instalaciones y actividades a fuentes de referencia específicas.

Firma

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

Ejemplo de uso

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

Singular.customRevenue Método

Realiza un seguimiento de los eventos de ingresos personalizados con un nombre de evento, moneda e importe especificados. Esto permite un seguimiento más específico de los ingresos con nombres de eventos personalizados.

Firma

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

Ejemplo de uso

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

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

customRevenueWithArgs

Método Singular.customRevenueWithArgs

Rastrea eventos de ingresos personalizados con un nombre de evento, moneda, importe y atributos adicionales especificados. Esto permite un seguimiento más detallado de los ingresos con parámetros personalizados.

Firma

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

Ejemplo de uso

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

Singular.event Método

Realiza un seguimiento de los eventos con el nombre especificado. Utiliza este método para realizar un seguimiento de las acciones y la participación de los usuarios en tu aplicación.

Firma

event(eventName: string): void

Ejemplo de uso

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

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

eventWithArgs

Singular.eventWithArgs Método

Realiza un seguimiento de los eventos con el nombre especificado y atributos personalizados adicionales. Utilice este método para realizar un seguimiento de las acciones del usuario con parámetros detallados.

Firma

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

Ejemplo de uso

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 las propiedades globales configuradas actualmente. Este método acepta una función de devolución de llamada que recibe un objeto que contiene todas las propiedades globales que se han establecido para el SDK.

Firma

getGlobalProperties(success: Function): void

Ejemplo de uso

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

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

getLimitDataSharing

Singular.getLimitDataSharing Método

Recupera el estado actual de la limitación del uso compartido de datos. Este método acepta una función de devolución de llamada que recibe un booleano que indica si la compartición de datos está actualmente limitada.

Firma

getLimitDataSharing(success: Function): void

Ejemplo de uso

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 Método

Procesa la carga útil de una notificación push para su atribución. Este método debe invocarse cuando la aplicación recibe una notificación push para que Singular pueda atribuirla correctamente. Este método es exclusivo de iOS.

Firma

handlePushNotification(pushNotificationPayload: Object): void

Ejemplo de uso

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

Constructor SingularIAP

Crea un objeto de compra dentro de la aplicación (IAP) para realizar un seguimiento de los ingresos de las compras dentro de la aplicación con validación de recibos específica de la plataforma. Este constructor procesa datos de compra de transacciones de iOS App Store y Android Play Store, formateando los datos para una atribución de ingresos y una verificación de recibos adecuadas.

Firma

function SingularIAP(product: Object): SingularIAP

Ejemplo de uso

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 Singular SDK con la configuración especificada. Este método debe invocarse antes que cualquier otro método del SDK. El objeto de configuración debe incluir la clave API, el secreto y otros parámetros opcionales.

Firma

init(singularConfig: SingularConfig): void

Ejemplo de uso

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 Método

Comprueba si se ha detenido todo el seguimiento. Este método acepta una función de devolución de llamada que recibe un booleano que indica el estado actual del seguimiento.

Firma

isAllTrackingStopped(success: Function): void

Ejemplo de uso

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 Método

Establece el estado de limitación del uso compartido de datos. Utiliza este método para cumplir la normativa de privacidad limitando los datos que se comparten con terceros.

Firma

limitDataSharing(value: boolean): void

Ejemplo de uso

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

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

resumeAllTracking

Singular.resumeAllTracking Método

Reanuda todas las actividades de seguimiento después de que se hayan detenido. Utilice este método para volver a activar el seguimiento cuando los usuarios vuelvan a optar por él.

Firma

resumeAllTracking(): void

Ejemplo de uso

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

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

ingresos

Singular.revenue Método

Realiza un seguimiento de los eventos de ingresos con una moneda y un importe especificados. Este es el método básico para rastrear ingresos sin atributos adicionales.

Firma

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

Ejemplo de uso

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

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

revenueWithArgs

Método Singular.revenueWithArgs

Realiza un seguimiento de los eventos de ingresos con una divisa, un importe y atributos adicionales especificados. Esto permite un seguimiento más detallado de los ingresos con parámetros personalizados.

Firma

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

Ejemplo de uso

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 Método

Establece un ID de usuario personalizado para la sesión actual. Esto le permite asociar los datos de Singular con su propio sistema de identificación de usuarios.

Firma

setCustomUserId(userId: string): void

Ejemplo de uso

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

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

setGlobalProperty

Singular.setGlobalProperty Método

Establece una propiedad global que se enviará con todos los eventos posteriores. Esto resulta útil para realizar un seguimiento de los atributos persistentes del usuario o del estado de la aplicación. El método acepta una función de devolución de llamada que recibe un booleano que indica el éxito.

Firma

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

Ejemplo de uso

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 Método

Controla si deben limitarse los identificadores publicitarios (IDFA/GAID). Utilice este método para cumplir las preferencias y normativas sobre privacidad.

Firma

setLimitAdvertisingIdentifiers(enabled: boolean): void

Ejemplo de uso

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

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

setUninstallToken

Singular.setUninstallToken Método

Establece el token de notificación push para el seguimiento de la desinstalación. Esto permite a Singular realizar un seguimiento de las desinstalaciones de aplicaciones mediante el control de los fallos de entrega de notificaciones push.

Firma

setUninstallToken(token: string): void

Ejemplo de uso

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 el valor de conversión actual de SKAdNetwork. Este método acepta una función de devolución de llamada que recibe el valor de conversión actual como un número. Este método es exclusivo de iOS.

Firma

skanGetConversionValue(success: Function): void

Ejemplo de uso

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

skanRegisterAppParaAtribuciónAdNetwork

Singular.skanRegisterAppForAdNetworkAttribution Método

Registra la aplicación para la atribución SKAdNetwork. Este método debe invocarse al principio del ciclo de vida de la aplicación para permitir el seguimiento de SKAdNetwork. Este método es exclusivo de iOS.

Firma

skanRegisterAppForAdNetworkAttribution(): void

Ejemplo de uso

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

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

skanUpdateConversionValue

Singular.skanUpdateConversionValue Método

Actualiza el valor de conversión de SKAdNetwork. Este método se utiliza para SKAdNetwork 2.0-3.0 y acepta una función de devolución de llamada que recibe un booleano que indica si la actualización se ha realizado correctamente. Este método es exclusivo de iOS.

Firma

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

Ejemplo de uso

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 Método

Actualiza los valores de conversión de SKAdNetwork 4.0 con el valor fino, el valor grueso y el estado de bloqueo. Este método es para iOS 16.1+ y acepta una función callback que recibe un booleano indicando éxito. Este método es sólo para iOS.

Firma

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

Ejemplo de uso

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 Método

Detiene todas las actividades de seguimiento. Utilice este método para desactivar el seguimiento cuando los usuarios opten por no participar o por motivos de privacidad.

Firma

stopAllTracking(): void

Ejemplo de uso

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

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

trackingOptIn

Método Singular.trackingOptIn

Indica que el usuario ha aceptado el seguimiento. Llame a este método cuando el usuario consienta explícitamente el seguimiento y la recopilación de datos.

Firma

trackingOptIn(): void

Ejemplo de uso

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

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

trackingUnder13

Método Singular.trackingUnder13

Indica que el usuario es menor de 13 años. Llame a este método para cumplir con COPPA y otras regulaciones para usuarios menores de 13 años.

Firma

trackingUnder13(): void

Ejemplo de uso

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

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

unsetCustomUserId

Singular.unsetCustomUserId Método

Elimina el ID de usuario personalizado establecido previamente. Llame a este método cuando el usuario cierre la sesión o cuando ya no desee asociar eventos al ID de usuario actual.

Firma

unsetCustomUserId(): void

Ejemplo de uso

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

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

unsetGlobalProperty

Singular.unsetGlobalProperty Método

Elimina una propiedad global establecida previamente. Llame a este método cuando ya no desee que una propiedad global específica se envíe con los eventos.

Firma

odedeunsetGlobalProperty(key: string): void

Ejemplo de uso

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

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