Tracking de eventos in-app

Realiza el tracking de eventos in-app para analizar el desempeño de las campañas y medir indicadores clave de desempeño (KPI) como inicios de sesión de usuarios, registros, finalización de tutoriales o hitos de progresión.

Eventos y atributos estándar

Uso de eventos estándar

Singular admite eventos estándar que las redes publicitarias reconocen para reporting y optimización. Usa nombres de eventos estándar siempre que sea posible para lograr reconocimiento automático y una configuración simplificada.

Tu equipo de UA, marketing o negocio debe elaborar la lista de eventos basándose en los KPI de marketing de tu organización. Consulta la guía Cómo hacer tracking de eventos in-app: Guía para clientes de Singular Attribution para planificar.

Cada evento admite varios atributos. Consulta los atributos estándar recomendados por evento para conocer los detalles de implementación.

Envío de eventos

Lineamientos de implementación de eventos

Envía eventos a Singular usando los métodos event o eventWithArgs para hacer tracking de acciones y comportamientos de los usuarios.

Eventos estándar: Usa el nombre iOS del evento de la lista de eventos estándar, por ejemplo, EVENT_SNG_LOGIN
Eventos personalizados: Para eventos exclusivos de tu app que no coincidan con eventos estándar, usa cualquier cadena descriptiva que cumpla con las limitaciones de caracteres

Limitaciones de eventos personalizados:

Idioma: Envía los nombres y atributos de eventos en inglés para garantizar la compatibilidad con partners externos y soluciones de analítica
Nombres de eventos: Limitados a 32 caracteres ASCII. Las cadenas no ASCII deben tener menos de 32 bytes al convertirse a UTF-8
Atributos y valores: Limitados a 500 caracteres ASCII

Método event

Reporta eventos de usuario sin información adicional para escenarios de tracking sencillos.

Firma del método:

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

+event: devuelve void — no hay señal de éxito/fallo en el punto de llamada. El SDK descarta el evento de forma silenciosa cuando el nombre es nil o está vacío, o cuando aún no se ha llamado a +start: . Revisa los logs para detectar problemas.

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 usando 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 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];

Tracking de ingresos in-app

Realiza tracking de ingresos provenientes de compras in-app (IAP), suscripciones y fuentes de ingresos personalizadas para medir el desempeño de las campañas y el retorno sobre la inversión publicitaria (ROAS).

Los datos de ingresos fluyen por tres canales:

Reportes interactivos: Visualiza métricas de ingresos en el dashboard de Singular
Export Logs: Accede a datos ETL detallados para análisis personalizados
Postbacks en tiempo real: Envía eventos de ingresos a plataformas externas

Limitaciones de 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 al convertirse a UTF-8)
Atributos: Los nombres y valores de atributos del evento están limitados a 500 caracteres ASCII
Códigos de moneda: Deben estar en MAYÚSCULAS y seguir el estándar de tres letras ISO 4217 (por ejemplo, USD, EUR, INR)

Mejores prácticas

Nomenclatura estándar: Usa la convención de nomenclatura estándar de eventos y atributos de Singular
Idioma: Envía los nombres de eventos de ingresos personalizados en inglés para mejorar la compatibilidad con postbacks de redes publicitarias
Montos distintos de cero: Envía eventos de ingresos solo cuando el monto sea mayor o menor que 0

Compras in-app sin suscripción

Integración con SKPaymentTransaction

Pasa el objeto SKPaymentTransaction de StoreKit al método iapComplete para obtener reporting enriquecido y validación de transacciones.

Beneficios:

Datos enriquecidos: Singular recibe los detalles completos de la transacción para reportes integrales
Prevención de fraude: Los recibos de las transacciones permiten la validación para combatir el fraude in-app

Notas:

Objeto requerido: El método iapComplete requiere el objeto SKPaymentTransaction
Conversión de moneda: Los ingresos en distintas monedas se convierten automáticamente a la moneda preferida de tu organización
Nombres de eventos personalizados: Usa el parámetro withName para categorizar los ingresos por tipo de evento en los reportes

Método iapComplete

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

Firmas del método:

+ (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 del evento de suscripción

Realiza tracking de compras y renovaciones de suscripciones para obtener insights sobre el comportamiento de los usuarios y la generación de ingresos recurrentes.

Guía de implementación: Revisa la completa Guía técnica de implementación del evento de suscripción para obtener instrucciones detalladas sobre el tracking de suscripciones con el SDK de Singular.

Ingresos personalizados sin validación de compra

Tracking manual de ingresos

Realiza tracking de ingresos pasando la moneda, el monto y, opcionalmente, los detalles del producto sin el objeto SKPaymentTransaction. Ten en cuenta que este método no proporciona recibos de transacciones para validación.

Importante: Al usar estos métodos, Singular no puede validar las transacciones. Recomendamos enfáticamente usar los métodos con SKPaymentTransaction descritos arriba siempre que sea posible.

Método revenue

Envía eventos de ingresos con moneda, monto y, opcionalmente, los detalles del producto.

Firmas del método:

+ (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, moneda, monto y atributos de transacción opcionales especificados.

Firmas del método:

+ (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 para StoreKit2

Tracking de ingresos con StoreKit2

Para apps que usan el framework StoreKit2, usa el método customRevenue con las representaciones JSON de la transacción y del producto.

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

Firmas del método:

+ (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];

Tracking híbrido de eventos (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 recolectar eventos desde otras fuentes cuando sea necesario.

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

Importante:

Las discrepancias ocurren cuando los identificadores de dispositivo en las solicitudes servidor a servidor no coinciden con los identificadores registrados por el SDK de Singular:

Eventos tempranos: Si un evento llega antes de que el SDK de Singular registre el identificador de dispositivo, el evento se convierte en la "primera sesión" de un dispositivo desconocido, lo que resulta en una atribución orgánica
Identificadores no coincidentes: Si el SDK de Singular registró un identificador de dispositivo diferente al de la solicitud servidor a servidor, el evento se atribuirá de forma incorrecta

Guías de tracking híbrido de eventos

Envío de eventos desde un servidor interno

Recolecta datos de ingresos desde tu servidor interno para analizar el desempeño de las campañas y el ROI.

Requisitos:

Capturar identificadores de dispositivo: Durante los eventos in-app de registro o inicio de sesión, captura y envía los identificadores de dispositivo, y luego almacena estos datos junto con el User ID en tu servidor. Actualiza los identificadores cuando los usuarios generen nuevas sesiones de la app para asegurar una atribución correcta
Identificadores específicos de plataforma: Envía los eventos del lado del servidor con el identificador de dispositivo correspondiente a la plataforma (por ejemplo, IDFA o IDFV para dispositivos iOS)
Actualizaciones en tiempo real: Usa el mecanismo de postback de Singular Internal BI para enviar eventos en tiempo real a tu endpoint. Consulta Internal BI Postback FAQ
Detalles de implementación: Revisa la sección "Tracking Revenue" en la guía de integración servidor a servidor

Envío de eventos desde un proveedor de ingresos

Integra proveedores externos de ingresos como RevenueCat o adapty para enviar ingresos de compras y suscripciones a Singular.

Proveedores compatibles:

RevenueCat: Obtén más información en la documentación de RevenueCat
adapty: Obtén más información en la documentación de adapty

Envío de eventos desde Segment

Habilita Segment para enviar eventos a Singular en paralelo con el SDK de Singular agregando un destino "Cloud-Mode" en Segment.

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

SDK de iOS - Tracking de eventos in-app

Tracking de eventos in-app

Eventos y atributos estándar

Uso de eventos estándar

Envío de eventos

Lineamientos de implementación de eventos

Método event

Ejemplos de uso

Método eventWithArgs

Ejemplos de uso

Tracking de ingresos in-app

Mejores prácticas

Compras in-app sin suscripción

Integración con SKPaymentTransaction

Método iapComplete

Ejemplos de uso

Ingresos por suscripción

Implementación del evento de suscripción

Ingresos personalizados sin validación de compra

Tracking manual de ingresos

Método revenue

Ejemplos de uso

Método customRevenue

Ejemplos de uso

Soporte para StoreKit2

Tracking de ingresos con StoreKit2

Ejemplos de uso

Tracking híbrido de eventos (avanzado)

Guías de tracking híbrido de eventos

Envío de eventos desde un servidor interno

Envío de eventos desde un proveedor de ingresos

Envío de eventos desde Segment