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

Documento

Seguimiento de eventos en la aplicación

Nota: Para obtener más información sobre la planificación de eventos de usuario, consulte ¿Seguirá la aplicación los eventos de usuario? en la guía Planificación y requisitos previos del SDK.

Nota: Recomendamos enviar todos los eventos de la aplicación al servidor de Singular utilizando los métodos del SDK de Singular en su aplicación. Si planea enviar eventos a Singular desde otro proveedor o un servidor interno, consulte la sección Seguimiento de eventos híbridos a continuación.

Seguimiento de eventos (sin ingresos)

Singular puede recopilar datos sobre eventos dentro de la aplicación para ayudar a analizar el rendimiento de sus campañas y medir los KPI. Por ejemplo, es posible que su organización desee recopilar datos sobre inicios de sesión de usuarios, registros, finalización de tutoriales o subidas de nivel en una aplicación de juegos.

La lista de eventos enviados a Singular (con los atributos que los acompañan) debe ser recopilada por el equipo de UA/marketing/negocio basándose en sus KPI de marketing.

Para obtener más información sobre la planificación de eventos de usuario, consulte ¿Seguirá la aplicación los eventos de usuario? en la guía Planificación y requisitos previos del SDK.

En su código, envíe eventos estándar a Singular utilizando los métodos event o eventWithArgs.

Nota: para los eventos estándar, utilice el nombre iOS del evento tal y como aparece en la lista de eventos y atributos estándar del SDK de iOS, por ejemplo, EVENT_SNG_LOGIN.

Para los eventos personalizados, eventos que su organización desea medir y que no coinciden con ninguno de los eventos estándar de Singular, utilice cualquier nombre personalizado (con un máximo de 32 caracteres). Recomendamos utilizar nombres en inglés para que sean compatibles con cualquier red publicitaria asociada que pueda recibir el evento de Singular con fines de optimización.

evento Método
Descripción Envía un evento de usuario a Singular para su seguimiento.
Firma (void)evento:(NSString *)nombre
Ejemplo de uso
SwiftObjective-C
// Using Standard Event


Singular.event(EVENT_SNG_LOGIN)

// Using Custom Event


Singular.event("signup")
Método eventWithArgs
Descripción Envía un evento de usuario a Singular para su seguimiento, con información adicional.
Firma (void)eventWithArgs:(NSString *)nombre, ...
Ejemplo de uso
SwiftObjective-C
//Using Standard Event
var dic: [AnyHashable : Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "PrivacyController"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "0"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "GDPR and CCPA Opt-Out Options"
Singular.event(EVENT_SNG_CONTENT_VIEW, withArgs: dic)

//Using Custom Event
var bonusdata: [AnyHashable: Any] = [ "level": 10, "points": 500 ]
Singular.event("Bonus Points Earned", withArgs: bonusdata)

Seguimiento de ingresos dentro de la aplicación

Singular captura eventos de ingresos de compras dentro de la aplicación (IAP), suscripciones e ingresos personalizados para medir el rendimiento de la campaña y el retorno de la inversión publicitaria (ROAS). Los datos de ingresos están disponibles a través de tres canales clave:

  • Informes interactivos en el panel de control de Singular
  • Registros de exportación detallados y destinos de datos ETL para análisis personalizados
  • Postbacks en tiempo real a plataformas externas

Este seguimiento exhaustivo de los ingresos permite tomar decisiones basadas en datos sobre el gasto en marketing y la optimización de campañas, al tiempo que proporciona flexibilidad en la forma de consumir y analizar los datos.

Requisitos

  • Si se utilizan nombres de eventos de ingresos personalizados, éstos 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.
  • Pase la divisa como un código de divisa ISO 4217 de tres letras:

    USD, EUR, INR

Práctica recomendada

  • Singular recomienda pasar eventos utilizando la convención de nomenclatura de eventos y atributos estándar de Singular.
  • Si se utilizan nombres de eventos de ingresos personalizados, deben enviarse en inglés para mejorar la compatibilidad con las devoluciones de la red publicitaria.
  • Los eventos de ingresos sólo deben enviarse a Singular cuando el importe de ingresos sea mayor o menor que 0.

Compras dentro de la aplicación sin suscripción

Importante: ¡este método no admite el seguimiento de suscripciones! Utilice este método para el seguimiento de compras In-App sin suscripción.

Si su aplicación utiliza el seguimiento IAP de App Store, la recomendación es utilizar el método iapComplete.

Este método envía un evento de ingresos IAP(Apple's In-App Purchase) a Singular con:

  • Todos los detalles de la transacción, que Singular utilizará para enriquecer los informes.
  • El recibo de la transacción, se utilizará para validar la transacción y analizar o prevenir intentos de fraude.

Notas:

  • Cuando utilice el iapComplete, debe incluir el objetoSKPaymentTransaction en el evento.
  • Cualquier ingreso reportado en una moneda diferente será auto-convertido a la moneda preferida de su organización, según lo establecido en su cuenta Singular.

Método iapComplete

Envía un evento de ingresos a Singular con el recibo de la transacción.

Firmas

(void)iapComplete:(id)transaction

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

Ejemplos de uso

SwiftObjective-C
// *** Get the SKPaymentTransaction* transaction object ***

let transaction:SKPaymentTransaction = ...

// Send a transaction event to Singular without a custom event name

Singular.iapComplete(transaction)

// Send a transaction event to Singular with a custom event name

Singular.iapComplete(transaction, withName:"MyCustomRevenue")

Ingresos por suscripción

Seguimiento de suscripciones:

Singular le permite realizar un seguimiento de sus suscripciones y renovaciones dentro de su aplicación, proporcionando información sobre el comportamiento del usuario y la generación de ingresos. Consulte nuestra completa guía sobre cómo implementar eventos de suscripción utilizando el SDK de Singular. [Guía técnica de implementación de eventos de suscripción]

Ingresos personalizados sin validación de compra

Si su aplicación no admite el seguimiento de compras dentro de la aplicación en la App Store, se recomiendan los métodos revenue o customRevenue. Estos métodos no realizan la validación de la compra y no deben incluir el objeto de compra ni el recibo.

Los métodos revenue y customRevenue le permiten especificar manualmente el importe y la divisa de la transacción, así como detalles adicionales opcionales, como el número de serie y la cantidad del producto, etc. El método customRevenue también le permite pasar un nombre de evento personalizado.

Nota: si utiliza estos métodos, Singular no valida la transacción de compra.


Método revenue

Envía un evento de ingresos a Singular con el importe de los ingresos, la moneda y detalles opcionales.

Firmas

(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

SwiftObjective-C
// Revenue with no product details

Singular.revenue("USD", amount:1.99)

// Revenue with product details

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

// Send a Revenue Event with attributes 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)

Método customRevenue

Envía eventos de ingresos personalizados a Singular especificando el nombre del evento, el importe de los ingresos, el código de moneda y cualquier atributo de transacción adicional. Singular procesa estos eventos para realizar un seguimiento de los ingresos dentro de la aplicación.

Firmas

(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

SwiftObjective-C
// Revenue with a custom name and no product details

Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)

// Revenue with a custom name and product details

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

// Send a Custom Revenue Event with attributes 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)

Compatibilidad con StoreKit2

Si su aplicación utiliza el marco StoreKit2 para el seguimiento de las compras dentro de la aplicación, se recomienda el método customRevenue. El método customRevenue requiere que proporcione la transacción y el objeto de producto en jsonRepresentation.

La validación de compras no es compatible con StoreKit2.


Método customRevenue

Firmas

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

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

Ejemplos de uso

SwiftObjective-C
// Fetch transaction and product from StoreKit2

let transaction = ... // Assume this is a valid StoreKit2 transaction

let product = ... // Assume this is a valid StoreKit2 product


// Custom Revenue using __iap__ event name with transaction and product JSON representations

Singular.customRevenue(
            transactionJsonRepresentation: transaction.jsonRepresentation, 
            productJsonRepresentation: product.jsonRepresentation )

// Custom Revenue with custom event name using transaction and product JSON representations

Singular.customRevenue(
            "PaymentSuccess", 
            transactionJsonRepresentation: transaction.jsonRepresentation, 
            productJsonRepresentation: product.jsonRepresentation )
}

Seguimiento de eventos híbrido (avanzado)

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

Cualquier evento NO enviado desde el SDK de Singular debe cumplir con los requisitos de documentación de eventos de servidor a servidor de Singular y proporcionar el identificador de dispositivo correspondiente para atribuir correctamente un evento.

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:

  • Si se recibe una solicitud de evento "antes" de que Singular SDK haya registrado el identificador de dispositivo, desde una App Session, entonces 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.
  • Si Singular SDK registró un identificador de dispositivo, pero el identificador de Singular SDK difiere del identificador de dispositivo especificado en la solicitud de evento de servidor a servidor, entonces el evento se atribuirá incorrectamente.

Guías de seguimiento de eventos híbridos

Envío de Eventos desde un Servidor Interno

Singular puede recopilar datos sobre los ingresos de su Servidor para ayudar a analizar el rendimiento y el ROI de sus campañas.

Requisitos:

  • Desde un Evento de Registro o Inicio de Sesión in-app, 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, asegúrese de actualizar 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.
  • 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).
  • Puede utilizar el mecanismo de postback de Singular Internal BI para enviar 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.
  • Revise la sección "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

Los proveedores de terceros como RevenueCat o adapty pueden proporcionar Ingresos por Compras y Suscripciones a Singular.

Siga los siguientes enlaces para obtener más información sobre cómo habilitar a estos socios.


Envío de eventos desde Segment

Para habilitar Segment para enviar eventos a Singular, en paralelo con el SDK de Singular, debe añadir un Destino "Cloud-Mode " en Segment. Siga nuestra guía AQUÍ.