SDK de Cordova - Seguimiento de eventos dentro de la aplicación

Seguir
Avatar
Jared Ornstead
Updated

Seguimiento de los ingresos dentro de la aplicación

Realice un seguimiento de los ingresos procedentes de compras dentro de la aplicación (IAP), suscripciones y fuentes de ingresos personalizadas para medir el rendimiento de la campaña y el retorno de la inversión publicitaria (ROAS).

Los datos de ingresos fluyen a través de tres canales:

  • Informes interactivos: Visualiza las métricas de ingresos en el panel de control de Singular.
  • Registros de exportación: Acceso a datos ETL detallados para análisis personalizados
  • Postbacks en tiempo real: Envíe eventos de ingresos a plataformas externas

¿Por qué realizar un seguimiento de los eventos de ingresos?

  • Análisis enriquecidos: Capture datos detallados de transacciones para mejorar los informes de Singular
  • Prevención del fraude: Incluya recibos de transacciones (por ejemplo, de Google Play o Apple App Store) para validar las compras y combatir el fraude dentro de la aplicación.
  • Optimización de campañas: Mida el ROI vinculando los ingresos a los esfuerzos de marketing

Práctica recomendada: Pasar el objeto de compra completo

Recomendamos encarecidamente pasar el objeto de compra devuelto desde el proceso In-App Purchase (IAP) de Android (Google Play Billing) o iOS (StoreKit). Esto asegura que Singular reciba detalles completos de la transacción, incluyendo:

  • ID del producto
  • Precio
  • Moneda
  • ID de la transacción
  • Datos del recibo (para validación)

Al pasar el objeto de compra completo, permite una generación de informes más rica y aprovecha las capacidades de detección de fraude de Singular, en particular para las transacciones de Google Play.

Integración de compras dentro de la aplicación

Captura del objeto de compra IAP

Utilice los plugins IAP de Cordova para recuperar el objeto de compra con los detalles completos de la transacción desde las tiendas de la plataforma.

Constructor SingularIAP

Crea un objeto de compra dentro de la aplicación para realizar un seguimiento de los ingresos con validación de recibos específica de la plataforma y prevención del fraude.

Firma del constructor : 

function SingularIAP(product: Object): SingularIAP

Para ver la referencia completa del constructor, consulta Referencia del constructor SingularIAP .

Ejemplo de implementación de IAP completo

Implemente un receptor de compras completo que capture eventos IAP y los envíe a Singular con objetos de compra específicos de la plataforma.

JavaScript 
// Import Singular SDK and SingularIAP constructor
var Singular = cordova.plugins.SingularCordovaSdk;
var SingularIAP = cordova.require('singular-cordova-sdk.SingularIAP');

// iOS App Store purchase example
function handleiOSPurchase(purchase) {
  // Create iOS product object
  var iosProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'ios-appstore',
      appStoreReceipt: purchase.receipt, // Base64 receipt from StoreKit
      id: purchase.transactionId // Transaction identifier
    }
  };

  // Create SingularIAP object
  var iosIAP = new SingularIAP(iosProduct);

  // Track the purchase with Singular
  // The SingularIAP object is passed as additional args
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', iosIAP);
}

// Android Play Store purchase example
function handleAndroidPurchase(purchase) {
  // Create Android product object
  var androidProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'android-playstore',
      receipt: purchase.receipt, // JSON receipt from Google Play
      signature: purchase.signature // Signature from Google Play
    }
  };

  // Create SingularIAP object
  var androidIAP = new SingularIAP(androidProduct);

  // Track the purchase with Singular
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', androidIAP);
}

// Example integration with cordova-plugin-purchase
document.addEventListener('deviceready', function() {
  // Initialize the store
  store.register({
    id: 'com.app.premiumgems',
    type: store.CONSUMABLE
  });

  // Handle purchase approved
  store.when('com.app.premiumgems').approved(function(product) {
    // Determine platform and handle accordingly
    if (device.platform === 'iOS') {
      handleiOSPurchase(product.transaction);
    } else if (device.platform === 'Android') {
      handleAndroidPurchase(product.transaction);
    }

    // Finish the transaction
    product.finish();
  });

  // Refresh the store
  store.refresh();
});

Puntos clave :

  • El constructor SingularIAP formatea los datos de compra para las plataformas iOS y Android.
  • Pase el objeto IAP resultante como el parámetro args en eventWithArgs()
  • El objeto IAP incluye datos de validación de recibos para la prevención del fraude
  • Singular extrae automáticamente los ingresos, la divisa y los detalles del producto

Seguimiento manual de ingresos

Ingresos sin validación de compra

Realice un seguimiento de los ingresos pasando la divisa, el importe y los detalles opcionales del producto sin el objeto de compra. Tenga en cuenta que este método no proporciona recibos de transacción para su validación.

Importante: Al enviar eventos de ingresos sin un objeto de compra válido, Singular no valida las transacciones. Recomendamos encarecidamente utilizar el constructor SingularIAP descrito anteriormente siempre que sea posible.

Nota: Pase la divisa como un código de divisa ISO 4217 de tres letras, por ejemplo, USD , EUR , INR .

Método de ingresos

Realiza el seguimiento de eventos de ingresos simples con una divisa y un importe especificados.

JavaScript 
// Track revenue without product details
cordova.plugins.SingularCordovaSdk.revenue('USD', 4.99);

Firma del método : 

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

Para ver la lista completa de métodos, consulte la referencia del método revenue .

Método RevenueWithArgs

Realiza el seguimiento de eventos de ingresos con una divisa, un importe y atributos personalizados adicionales especificados.

JavaScript 
// Track revenue with attributes
cordova.plugins.SingularCordovaSdk.revenueWithArgs('USD', 9.98, {
  productSKU: 'coin_package_abc123',
  productName: 'Coin Pack 10',
  productCategory: 'Bundles',
  productQuantity: 2,
  productPrice: 4.99,
  transaction_id: 'T12345'
});

Firma del método : 

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

Para obtener la lista completa de métodos, consulte la referencia del método revenue WithArgs.

Método CustomRevenue

Realiza el seguimiento de eventos de ingresos personalizados con un nombre de evento, moneda e importe especificados.

JavaScript 
// Track custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue('PremiumUpgrade', 'USD', 9.99);

Firma del método : 

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

Para obtener la lista completa de métodos, consulte la referencia del método customRevenue .

Método CustomRevenueWithArgs

Realiza el seguimiento de eventos de ingresos personalizados con un nombre de evento, divisa, importe y atributos personalizados adicionales especificados.

JavaScript 
// Track custom revenue event with attributes
cordova.plugins.SingularCordovaSdk.customRevenueWithArgs('PremiumBundlePurchase', 'USD', 99.99, {
  productSKU: 'premium_bundle_xyz',
  productName: 'Premium Bundle',
  productCategory: 'Bundles',
  productQuantity: 1,
  productPrice: 99.99,
  discount_applied: true
});

Firma del método : 

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

Para obtener la lista completa de métodos, consulte la referencia del método custom RevenueWithArgs.

Ingresos por suscripción

Seguimiento de suscripciones

Singular ofrece una guía completa sobre la implementación de eventos de suscripción utilizando Singular SDK. La guía cubre el seguimiento de eventos de suscripción dentro de la aplicación en varias plataformas.

Seguimiento de eventos híbridos (avanzado)

Singular recomienda enviar todos los eventos e ingresos a través del SDK de Singular integrado en su aplicación para una atribución óptima. Sin embargo, Singular puede recopilar eventos de otras fuentes cuando sea necesario.

Los eventos enviados fuera del SDK de Singular deben cumplir con los requisitos de documentación de eventos de servidor a servidor de Singular y proporcionar identificadores de dispositivo coincidentes para una atribución correcta.

Importante:

Se producirán discrepancias si los identificadores de dispositivo utilizados en las solicitudes de eventos de servidor a servidor no tienen un identificador de dispositivo coincidente en Singular. Tenga en cuenta las siguientes posibilidades:

  • Eventos tempranos: Si se recibe una solicitud de evento antes de que Singular SDK haya registrado el identificador de dispositivo de una sesión de aplicación, la solicitud de evento se considerará la "primera sesión" para el dispositivo desconocido, y Singular atribuirá el dispositivo como una atribución orgánica .
  • Identificadores no coincidentes: Si Singular SDK registró un identificador de dispositivo, pero difiere del identificador de dispositivo especificado en la solicitud de evento de servidor a servidor, el evento se atribuirá incorrectamente .

Guías de seguimiento de eventos híbridos

Envío de eventos desde un servidor interno

Recopile datos de ingresos de su servidor interno para analizar el rendimiento de la campaña y el ROI.

Requisitos:

  • Capturar identificadores de dispositivos: Desde un evento de registro o inicio de sesión dentro de la aplicación, capture y pase los identificadores de dispositivo y almacene estos datos con el ID de usuario en su servidor. Dado que los identificadores de dispositivo pueden cambiar para un usuario, actualice los identificadores cuando un usuario genere una sesión de aplicación. Esto garantiza que el evento del lado del servidor se atribuya al dispositivo correcto.
  • Identificadores específicos de la plataforma: Los eventos del lado del servidor son específicos de cada plataforma y sólo deben enviarse con el identificador de dispositivo que coincida con la plataforma del dispositivo (por ejemplo, IDFA o IDFV para dispositivos iOS, GAID para dispositivos Android)
  • Actualizaciones en tiempo real: Utilice el mecanismo Singular Internal BI postback para empujar un evento en tiempo real a su endpoint interno para que pueda actualizar el conjunto de datos en el lado del servidor. Consulte las preguntas frecuentes sobre postback de BI interno
  • Detalles de Implementación: Revise la sección de Seguimiento de Ingresos en la guía de Integración Servidor a Servidor para más detalles.

Envío de Eventos desde un Proveedor de Ingresos

Integre proveedores de ingresos de terceros como RevenueCat o adapty para enviar ingresos por compras y suscripciones a Singular.

Proveedores compatibles:

Envío de eventos desde Segment

Habilite Segment para enviar eventos a Singular en paralelo con el SDK de Singular añadiendo un destino "Cloud-Mode" en Segment.

Siga la guía de implementación Integración Singular-Segment para obtener instrucciones detalladas de configuración.