Seguimiento de eventos in-app

Haz seguimiento de los eventos in-app para analizar el rendimiento de las campañas y medir los indicadores clave de rendimiento (KPI), como inicios de sesión de usuarios, registros, finalizaciones de tutoriales o hitos de progresión.

Eventos y atributos estándar

Uso de eventos estándar

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

Tu equipo de UA, marketing o negocio debería compilar la lista de eventos según los KPI de marketing de tu organización. Consulta la guía How to Track In-App Events: Guide For Singular Attribution Customers para la planificación.

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

Envío de eventos

Directrices de implementación de eventos

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

Eventos estándar: Usa el nombre de 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 los eventos personalizados:

Idioma: Pasa los nombres de eventos y atributos en inglés para garantizar la compatibilidad con los partners externos y las 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 seguimiento simples.

Firma del método:

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

+event: devuelve void — no hay señal de éxito o fallo en el punto de la llamada. El SDK descarta silenciosamente el evento cuando el nombre es nil o está vacío, o cuando aún no se ha llamado a +start: . Revisa los registros en busca de 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 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 ingresos in-app

Haz seguimiento de los ingresos provenientes de compras in-app (IAP), suscripciones y fuentes de ingresos personalizadas para medir el rendimiento de las campañas 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 Singular
Registros de exportación: Accede a datos ETL detallados para análisis personalizados
Postbacks en tiempo real: Envía eventos de ingresos a plataformas externas

Limitaciones de los eventos de ingresos:

Nombres de eventos: Los nombres de eventos de ingresos personalizados están limitados a 32 caracteres ASCII (o 32 bytes para caracteres no ASCII al convertirse a UTF-8)
Atributos: Los nombres y valores de los atributos de eventos 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)

Prácticas recomendadas

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 de los postbacks a las ad networks
Montos distintos de cero: Envía eventos de ingresos únicamente cuando el monto sea mayor o menor que 0

Compra in-app sin suscripción

Integración de SKPaymentTransaction

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

Beneficios:

Datos enriquecidos: Singular recibe los detalles completos de la transacción para obtener informes integrales
Prevención de fraude: Los recibos de 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 diferentes 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 informes

Método iapComplete

Envía un evento de ingresos con el objeto SKPaymentTransaction para lograr una 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 de eventos de suscripción

Haz 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: Revisa la completa Subscription Event Technical Implementation Guide para obtener instrucciones detalladas sobre el seguimiento de suscripciones con el SDK de Singular.

Ingresos personalizados sin validación de compra

Seguimiento manual de ingresos

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

Importante: Al usar estos métodos, Singular no puede validar las transacciones. Recomendamos encarecidamente usar los métodos de SKPaymentTransaction descritos anteriormente siempre que sea posible.

Método revenue

Envía eventos de ingresos con la moneda, el monto y los detalles opcionales 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 específico, la moneda, el monto y atributos de transacción opcionales.

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

Compatibilidad con StoreKit2

Seguimiento 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.

La validación de StoreKit2 ya es compatible a partir de la versión 12.13+ del SDK. 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];

Seguimiento híbrido de eventos (avanzado)

Envía todos los eventos e ingresos a través del SDK de Singular integrado en tu app para lograr 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 Server-to-Server 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 server-to-server 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 server-to-server, el evento se atribuirá de forma incorrecta

Guías de seguimiento híbrido de eventos

Envío de eventos desde un servidor interno

Recopila datos de ingresos desde tu servidor interno para analizar el rendimiento de las campañas y el ROI.

Requisitos:

Capturar identificadores de dispositivo: Durante los eventos de registro o inicio de sesión in-app, captura y pasa los identificadores de dispositivo, 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 garantizar una atribución correcta
Identificadores específicos de la plataforma: Envía los eventos del lado del servidor con el identificador de dispositivo que corresponda a la plataforma (por ejemplo, IDFA o IDFV para dispositivos iOS)
Actualizaciones en tiempo real: Usa el mecanismo de postback de Internal BI de Singular para enviar eventos en tiempo real a tu endpoint. Consulta las Internal BI Postback FAQ
Detalles de implementación: Revisa la sección "Tracking Revenue" en la guía de integración Server-to-Server

Envío de eventos desde un proveedor de ingresos

Integra proveedores de ingresos externos 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 Singular-Segment Integration para obtener instrucciones detalladas de configuración.