SDK de Cordova - Referencia de métodos SDK

Seguir
Avatar
Jared Ornstead
Updated
Documento

SDK de Cordova - Referencia de métodos SDK

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, identificación de usuarios, seguimiento de eventos, informes de ingresos, atribución, cumplimiento de privacidad de datos y configuración. 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.

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

static adRevenue(adData: SingularAdData): void

Ejemplo de uso

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

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

static clearGlobalProperties(): void

Ejemplo de uso

javascript
// Clear all global properties, for example when a user logs out
cordova.plugins.SingularCordovaSdk.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

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

Ejemplo de uso

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

customRevenue

Singular.customRevenue Método

Realiza el seguimiento de un evento de ingresos personalizado con un nombre de evento, moneda e importe especificados. Esto le permite rastrear eventos de ingresos con nombres personalizados para un rastreo de ingresos más específico.

  • Nota: Los nombres de eventos de ingresos personalizados están limitados a 32 caracteres ASCII. Para caracteres no ASCII, el límite es de 32 bytes una vez convertidos a UTF-8.
  • Los códigos de divisa deben escribirse TODO EN MAYÚSCULAS y ajustarse al código de divisa ISO 4217 de tres letras.

Firma

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

Ejemplo de uso

javascript
// Track a custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue("premium_subscription", "USD", 9.99);

customRevenueWithArgs

Singular.customRevenueWithArgs Método

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

  • Nota: Los Nombres de Eventos de Ingresos Personalizados están limitados a 32 caracteres ASCII. Para caracteres no ASCII, el límite es de 32 bytes una vez convertidos a UTF-8.
  • Los nombres de atributos de eventos y los valores de atributos están limitados a 500 caracteres ASCII.
  • Los códigos de moneda deben escribirse TODO EN MAYÚSCULAS y ajustarse al código de moneda ISO 4217 de tres letras.

Firma

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

Ejemplo de uso

javascript
// 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"
    }
);

evento

Singular.event Método

Realiza el seguimiento de un evento simple 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

static event(eventName: string): void

Ejemplo de uso

javascript
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");

eventWithArgs

Método Singular.eventWithArgs

Realiza el seguimiento de un evento con el nombre especificado y atributos personalizados adicionales. Esto permite un seguimiento de eventos más detallado con parámetros personalizados.

Firma

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

Ejemplo de uso

javascript
// Track an event with additional parameters
cordova.plugins.SingularCordovaSdk.eventWithArgs(
    "level_completed",
    {
        "level_id": 5,
        "score": 12500,
        "time_spent": 120,
        "difficulty": "medium"
    }
);

getGlobalProperties

Singular.getGlobalProperties Método

Recupera todas las propiedades globales configuradas actualmente. Este método devuelve un objeto que contiene todas las propiedades globales que se han establecido para el SDK.

Firma

static getGlobalProperties(success: Function): void

Ejemplo de uso

javascript
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    console.log("Current global properties:", properties);
});

getLimitDataSharing

Singular.getLimitDataSharing Método

Obtiene el estado actual de la limitación del uso compartido de datos. Este método devuelve un booleano que indica si la compartición de datos está actualmente limitada.

Firma

static getLimitDataSharing(success: Function): void

Ejemplo de uso

javascript
// Check if data sharing is limited
cordova.plugins.SingularCordovaSdk.getLimitDataSharing(function(isLimited) {
    console.log("Data sharing is limited:", isLimited);
});

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.

Firma

static handlePushNotification(pushNotificationPayload: Object): void

Ejemplo de uso

javascript
// Handle a received push notification
document.addEventListener('push-notification', function(event) {
    var notification = event.notification;
    cordova.plugins.SingularCordovaSdk.handlePushNotification(notification);
}, false);

init

Método Singular.init

Inicializa el SDK de Singular con la configuración proporcionada. Este es el primer método que debe llamar para empezar a utilizar Singular SDK.

Firma

static init(singularConfig: SingularConfig): void

Ejemplo de uso

javascript
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

Método Singular.isAllTrackingStopped

Comprueba si todo el seguimiento está detenido. Este método devuelve un booleano que indica si se ha detenido el seguimiento.

Firma

static isAllTrackingStopped(success: Function): void

Ejemplo de uso

javascript
// Check if tracking is stopped
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped(function(isStopped) {
    console.log("Tracking is stopped:", isStopped);
});

limitDataSharing

Singular.limitDataSharing Método

Establece el estado de limitación del uso compartido de datos. Utiliza este método para limitar el uso compartido de datos en función del consentimiento del usuario o de requisitos de privacidad.

Firma

static limitDataSharing(value: boolean): void

Ejemplo de uso

javascript
// Limit data sharing based on user consent
function onUserConsentChanged(hasConsent) {
    cordova.plugins.SingularCordovaSdk.limitDataSharing(!hasConsent);
}

ingresos

Singular.revenue Método

Rastrea un evento de ingresos con la moneda y el importe especificados. Este método se utiliza para informar de los ingresos generados en su aplicación.

Firma

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

Ejemplo de uso

javascript
// Track a revenue event
cordova.plugins.SingularCordovaSdk.revenue("USD", 4.99);

revenueWithArgs

Método Singular.revenueWithArgs

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

  • Los nombres y valores de los atributos del evento están limitados a 500 caracteres ASCII.
  • Los códigos de divisa deben ser TODO MAYÚSCULAS y respetar el código de divisa ISO 4217 de tres letras.

Firma

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

Ejemplo de uso

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

Reanuda todas las actividades de seguimiento previamente detenidas. Utilice este método para volver a activar el seguimiento después de haberlo detenido.

Firma

static resumeAllTracking(): void

Ejemplo de uso

javascript
// Resume tracking, for example when user opts back in
function onUserOptIn() {
    cordova.plugins.SingularCordovaSdk.resumeAllTracking();
}

setCustomUserId

Singular.setCustomUserId Método

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

Firma

static setCustomUserId(userId: string): void

Ejemplo de uso

javascript
// Set custom user ID after user logs in
function onUserLogin(userId) {
    cordova.plugins.SingularCordovaSdk.setCustomUserId(userId);
}

setGlobalProperty

Singular.setGlobalProperty Método

Establece una propiedad global que se enviará con todos los eventos. Esto te permite añadir atributos consistentes a todos los eventos sin tener que especificarlos cada vez.

Firma

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

Ejemplo de uso

javascript
// Set a global property
cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    "user_tier", 
    "premium", 
    true, 
    function(isSuccess) {
        console.log("Global property set successfully:", isSuccess);
    }
);

setUninstallToken

Singular.setUninstallToken Método

Establece el token del dispositivo para el seguimiento de la desinstalación. Este método debe invocarse con el token de notificación push para habilitar el seguimiento de la desinstalación.

Firma

static setUninstallToken(token: string): void

Ejemplo de uso

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

Recupera el valor de conversión actual de SKAdNetwork. Este método es específico de iOS y devuelve el valor de conversión actual utilizado para la atribución de SKAdNetwork.

Firma

static skanGetConversionValue(success: Function): void

Ejemplo de uso

javascript
// Get the current SKAdNetwork conversion value
cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(conversionValue) {
    console.log("Current conversion value:", conversionValue);
});

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution Método

Registra la aplicación para la atribución SKAdNetwork. Este método es específico de iOS y debe invocarse para activar la atribución de SKAdNetwork.

Firma

static skanRegisterAppForAdNetworkAttribution(): void

Ejemplo de uso

javascript
// Register for SKAdNetwork attribution
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue Método

Actualiza el valor de conversión de SKAdNetwork. Este método es específico de iOS y permite actualizar manualmente el valor de conversión utilizado para la atribución SKAdNetwork.

Firma

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

Ejemplo de uso

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

Actualiza los valores de conversión de SKAdNetwork con parámetros adicionales. Este método es específico de iOS 16.1+ y permite actualizar los valores fino, grueso y de bloqueo para la atribución SKAdNetwork 4.0.

Firma

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

Ejemplo de uso

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

static stopAllTracking(): void

Ejemplo de uso

javascript
// Stop tracking, for example when user opts out
function onUserOptOut() {
    cordova.plugins.SingularCordovaSdk.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

static trackingOptIn(): void

Ejemplo de uso

javascript
// User has opted in to tracking
function onUserConsentGiven() {
    cordova.plugins.SingularCordovaSdk.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

static trackingUnder13(): void

Ejemplo de uso

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

static unsetCustomUserId(): void

Ejemplo de uso

javascript
// Clear custom user ID when user logs out
function onUserLogout() {
    cordova.plugins.SingularCordovaSdk.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

static unsetGlobalProperty(key: string): void

Ejemplo de uso

javascript
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");