Documento

Seguimiento de eventos dentro de la aplicación

Realice un seguimiento de los eventos dentro de la aplicación para analizar el rendimiento de la campaña y medir los indicadores clave de rendimiento (KPI), como inicios de sesión de usuarios, registros, finalización de tutoriales o hitos de progresión.

Eventos estándar y atributos

Uso de eventos estándar

Singular admite eventosestándar que son reconocidos por las redes publicitarias para la generación de informes y la optimización. Utilice nombres de eventos estándar siempre que sea posible para un reconocimiento automático y una configuración simplificada.

Su equipo de UA, marketing o comercial debe compilar la lista de eventos basándose en los KPI de marketing de su organización. Consulte la guía How to Track In-App Events: Guide For Singular AttributionCustomers para la planificación.

Cada evento admite varios atributos. Consulte los atributos estándar recomendados por eventopara obtener detalles de implementación.

Envío de eventos

Directrices de implementación de eventos

Envíe eventos a Singular utilizando los métodos event o eventWithArgs para el seguimiento de las acciones y comportamientos de los usuarios.

Eventos estándar: Utilice el nombre iOS del eventode la lista de eventos estándar, por ejemplo, EVENT_SNG_LOGIN.
Eventos personalizados: Para los eventos exclusivos de tu aplicación que no coincidan con los eventos estándar, utiliza cualquier cadena descriptiva que cumpla con las limitaciones de caracteres

Limitacionesde eventospersonalizados:

Idioma: Pasa los nombres y atributos de los eventos en inglés para garantizar la compatibilidad con socios y soluciones analíticas de terceros
Nombres de eventos: Limitados a 32 caracteres ASCII. Las cadenas no ASCII deben tener menos de 32 bytes cuando se convierten a UTF-8
Atributos y valores: Limitado a 500 caracteres ASCII

Método de eventos

Notificar eventos de usuario sin información adicional para escenarios de seguimiento sencillos.

Firma del método:

+ (void)event:(NSString *)name;

Ejemplos de uso

// Example 1: Standard event
Singular.event(EVENT_SNG_LOGIN)

// Example 2: Custom event
Singular.event("signup")

// Example 1: Standard event
[Singular event:EVENT_SNG_LOGIN];

// Example 2: Custom event
[Singular event:@"signup"];

Método eventWithArgs

Reporta eventos de usuario con información adicional utilizando el formato de diccionario para datos estructurados.

Firma del método:

+ (void)event:(NSString *)name withArgs:(NSDictionary *)args;

Nota: El parámetro args es un NSDictionary que contiene uno o más pares clave-valor. Las claves deben ser cadenas y los valores pueden ser de cualquier tipo permitido en un NSDictionary.

Ejemplos de uso

// Example 1: Standard event with recommended attributes
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "video"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "32"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "Telugu"
dic[ATTRIBUTE_SNG_ATTR_SUCCESS] = "yes"

Singular.event(EVENT_SNG_TUTORIAL_COMPLETE, withArgs: dic)

// Example 2: Custom event with custom attributes
var bonusData: [AnyHashable: Any] = [
    "level": 10,
    "points": 500
]
Singular.event("Bonus Points Earned", withArgs: bonusData)

// Example 1: Standard event with recommended attributes
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"video" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
[dic setValue:@"32" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
[dic setValue:@"Telugu" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
[dic setValue:@"yes" forKey:ATTRIBUTE_SNG_ATTR_SUCCESS];

[Singular event:EVENT_SNG_TUTORIAL_COMPLETE withArgs:dic];

// Example 2: Custom event with custom attributes
NSMutableDictionary *bonusData = [[NSMutableDictionary alloc] init];
[bonusData setValue:@10 forKey:@"level"];
[bonusData setValue:@500 forKey:@"points"];

[Singular event:@"Bonus Points Earned" withArgs:bonusData];

Seguimiento de los ingresos desde 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

Limitacionesde eventos de ingresos:

Nombres de eventos: Los nombres de eventos de ingresos personalizados están limitados a 32 caracteres ASCII (o 32 bytes para no ASCII cuando se convierten a UTF-8)
Atributos: Los nombres y valores de atributos de eventos están limitados a 500 caracteres ASCII
Códigos de moneda: Deben ser TODO MAYÚSCULAS y seguir el estándar ISO 4217de tres letras (por ejemplo, USD, EUR, INR)

Buenas prácticas

Nombres estándar: Utilice la convención de nomenclatura estándar de eventos y atributosde Singular.
Idioma: Envíe los nombres de los eventos de ingresos personalizados en inglés para mejorar la compatibilidad con la red publicitaria.
Importes distintos de cero: Sólo envía eventos de ingresos cuando el importe es mayor o menor que 0

Compras dentro de la aplicación sin suscripción

Integración de SKPaymentTransaction

Pase el objeto SKPaymentTransactionde StoreKit al método iapComplete para obtener informes enriquecidos y validación de transacciones.

Ventajas:

Datos enriquecidos: Singular recibe detalles completos de la transacción para informes exhaustivos
Prevención del fraude: Los recibos de transacciones permiten la validación para combatir el fraude in-app

Notas:

Objeto requerido: El método iapCompleterequiere el objeto SKPaymentTransaction
Conversión de divisas: Los ingresos en diferentes monedas se convierten automáticamente a la moneda preferida de su organización
Nombres de evento personalizados: Utilice el parámetro withNamepara clasificar los ingresos por tipo de evento en los informes

Método iapComplete

Envíe un evento de ingresos con el objeto SKPaymentTransaction para una validación automática y datos enriquecidos.

Firmas de métodos:

+ (void)iapComplete:(id)transaction;
+ (void)iapComplete:(id)transaction withName:(NSString *)name;

Ejemplos de uso

// Get the SKPaymentTransaction object
let transaction: SKPaymentTransaction = ...

// Send transaction without custom event name
Singular.iapComplete(transaction)

// Send transaction with custom event name
Singular.iapComplete(transaction, withName: "MyCustomRevenue")

// Get the SKPaymentTransaction object
SKPaymentTransaction *transaction = ...;

// Send transaction without custom event name
[Singular iapComplete:transaction];

// Send transaction with custom event name
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

Ingresos por suscripción

Implementación de eventos de suscripción

Realice un seguimiento de las compras y renovaciones de suscripciones para obtener información sobre el comportamiento de los usuarios y la generación de ingresos recurrentes.

Guía de implementación: Consulte la completa Guía de implementación técnica de eventos de suscripciónpara obtener instrucciones detalladas sobre el seguimiento de suscripciones con Singular SDK.

Ingresos personalizados sin validación de compras

Seguimiento manual de ingresos

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

Importante: Cuando se utilizan estos métodos, Singular no puede validar transacciones. Recomendamos encarecidamente utilizar los métodos SKPaymentTransaction descritos anteriormente siempre que sea posible.

Método revenue

Envía eventos de ingresos con moneda, importe y detalles opcionales del producto.

Firmas de métodos:

+ (void)revenue:(NSString *)currency amount:(double)amount;

+ (void)revenue:(NSString *)currency 
         amount:(double)amount
     productSKU:(NSString *)productSKU 
    productName:(NSString *)productName 
productCategory:(NSString *)productCategory
productQuantity:(int)productQuantity 
   productPrice:(double)productPrice;

+ (void)revenue:(NSString *)currency 
         amount:(double)amount
 withAttributes:(NSDictionary *)attributes;

Ejemplos de uso

// Without product details
Singular.revenue("USD", amount: 1.99)

// With product details
Singular.revenue("EUR", 
    amount: 5.00, 
    productSKU: "SKU1928375", 
    productName: "Reservation Fee",
    productCategory: "Fee", 
    productQuantity: 1, 
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Without product details
[Singular revenue:@"USD" amount:1.99];

// With product details
[Singular revenue:@"EUR" 
           amount:5.00 
       productSKU:@"SKU1928375"
      productName:@"Reservation Fee" 
  productCategory:@"Fee" 
  productQuantity:1 
     productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular revenue:@"USD" amount:19.99 withAttributes:dic];

Método customRevenue

Envía eventos de ingresos personalizados con un nombre de evento especificado, divisa, importe y atributos de transacción opcionales.

Firmas de métodos:

+ (void)customRevenue:(NSString *)eventName 
             currency:(NSString *)currency 
               amount:(double)amount;

+ (void)customRevenue:(NSString *)eventName 
             currency:(NSString *)currency 
               amount:(double)amount 
           productSKU:(NSString *)productSKU 
          productName:(NSString *)productName
      productCategory:(NSString *)productCategory 
      productQuantity:(int)productQuantity
         productPrice:(double)productPrice;

+ (void)customRevenue:(NSString *)eventName 
             currency:(NSString *)currency 
               amount:(double)amount 
       withAttributes:(NSDictionary *)attributes;

Ejemplos de uso

// Without product details
Singular.customRevenue("MyCustomRevenue", currency: "USD", amount: 1.99)

// With product details
Singular.customRevenue("MyCustomRevenue", 
    currency: "EUR", 
    amount: 5.00, 
    productSKU: "SKU1928375", 
    productName: "Reservation Fee", 
    productCategory: "Fee", 
    productQuantity: 1, 
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.customRevenue("CustomRevenueWithArgsDic", 
    currency: "USD", 
    amount: 44.99, 
    withAttributes: dic)

// Without product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];

// With product details
[Singular customRevenue:@"MyCustomRevenue" 
               currency:@"EUR" 
                 amount:5.00 
             productSKU:@"SKU1928375" 
            productName:@"Reservation Fee" 
        productCategory:@"Fee"  
        productQuantity:1 
           productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt" 
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular customRevenue:@"MyCustomRevenue" 
               currency:@"USD" 
                 amount:44.99 
         withAttributes:dic];

Soporte de StoreKit2

Seguimiento de ingresos de StoreKit2

Para las apps que utilizan el marco StoreKit2, utilice el método customRevenuecon representaciones JSON de transacciones y productos.

Importante: La validación de compras no es compatible con StoreKit2. Los métodos requieren el formato jsonRepresentationpara los objetos de transacción y producto.

Firmas de métodos:

+ (void)customRevenue:(NSData *)transactionJsonRepresentation 
productJsonRepresentation:(NSData *)productJsonRepresentation;

+ (void)customRevenue:(NSString *)eventName 
transactionJsonRepresentation:(NSData *)transactionJsonRepresentation 
productJsonRepresentation:(NSData *)productJsonRepresentation;

Ejemplos de uso

// Fetch transaction and product from StoreKit2
let transaction = ... // Valid StoreKit2 transaction
let product = ... // Valid StoreKit2 product

// Custom Revenue with default __iap__ event name
Singular.customRevenue(
    transactionJsonRepresentation: transaction.jsonRepresentation, 
    productJsonRepresentation: product.jsonRepresentation)

// Custom Revenue with custom event name
Singular.customRevenue(
    "PaymentSuccess", 
    transactionJsonRepresentation: transaction.jsonRepresentation, 
    productJsonRepresentation: product.jsonRepresentation)

// Fetch transaction and product from StoreKit2
SKTransaction *transaction = ...;  // Valid StoreKit2 transaction
SKProduct *product = ...;          // Valid StoreKit2 product

// Convert JSON representations to NSData
NSData *transactionData = [transaction.jsonRepresentation 
    dataUsingEncoding:NSUTF8StringEncoding];
NSData *productData = [product.jsonRepresentation 
    dataUsingEncoding:NSUTF8StringEncoding];

// Custom Revenue with default __iap__ event name
[Singular customRevenue:transactionData 
    productJsonRepresentation:productData];

// Custom Revenue with custom event name
[Singular customRevenue:@"PaymentSuccess" 
    transactionJsonRepresentation:transactionData 
    productJsonRepresentation:productData];

Seguimiento de eventos híbrido (avanzado)

Envía todos los eventos e ingresos a través del SDK de Singular integrado en tu app 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 la documentación de eventos de servidor a servidor de Singular y proporcionar identificadores de dispositivo coincidentes para una atribución correcta.

Importante:

Se producen discrepancias cuando los identificadores de dispositivo en las solicitudes de servidor a servidor no coinciden con los identificadores registrados por Singular SDK:

Eventos tempranos: Si un evento llega antes de que Singular SDK registre el identificador del dispositivo, el evento se convierte en la "primera sesión" de un dispositivo desconocido, lo que da lugar a una atribución orgánica.
Identificadores no coincidentes: Si Singular SDK registra un identificador de dispositivo diferente al de la solicitud 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 desde su servidor interno para analizar el rendimiento de la campaña y el ROI.

Requisitos:

Capturar identificadores de dispositivos: Durante los eventos de registro o inicio de sesión dentro de la aplicación, capture y pase los identificadores de dispositivo y, a continuación, almacene estos datos con el ID de usuario en su servidor. Actualice los identificadores cuando los usuarios generen nuevas sesiones de aplicación para garantizar una atribución correcta.
Identificadores específicos de la plataforma: Envíe eventos del lado del servidor con el identificador de dispositivo que coincida con la plataforma (por ejemplo, IDFA o IDFV para dispositivos iOS)
Actualizaciones en tiempo real: Utilice el mecanismo Singular Internal BI postback para enviar eventos en tiempo real a su endpoint. Consulte las preguntas frecuentes sobre postback de BIinterno
Detalles de implementación: Revise la sección "Seguimiento de ingresos" en la guía de integración de servidor a servidor

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:

RevenueCat: Más información en la documentación de RevenueCat
adapty: Más información en la documentaciónde adapty

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.

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

Seguimiento de eventos dentro de la aplicación

Eventos estándar y atributos

Uso de eventos estándar

Envío de eventos

Directrices de implementación de eventos

Método de eventos

Ejemplos de uso

Método eventWithArgs

Ejemplos de uso

Seguimiento de los ingresos desde la aplicación

Buenas prácticas

Compras dentro de la aplicación sin suscripción

Integración de SKPaymentTransaction

Método iapComplete

Ejemplos de uso

Ingresos por suscripción

Implementación de eventos de suscripción

Ingresos personalizados sin validación de compras

Seguimiento manual de ingresos

Método revenue

Ejemplos de uso

Método customRevenue

Ejemplos de uso

Soporte de StoreKit2

Seguimiento de ingresos de StoreKit2

Ejemplos de uso

Seguimiento de eventos híbrido (avanzado)

Guías de seguimiento de eventos híbridos

Envío de eventos desde un servidor interno

Envío de Eventos desde un Proveedor de Ingresos

Envío de eventos desde Segment