SDK de Android - Seguimiento de eventos in-app

Seguir
Avatar
Jared Ornstead
Updated

Seguimiento de eventos in-app

Realiza el seguimiento de los eventos in-app para analizar el rendimiento de las campañas y medir indicadores clave de rendimiento (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 la generación de reportes 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 debe elaborar la lista de eventos según los KPI de marketing de tu organización. Consulta la guía Cómo realizar el seguimiento de eventos in-app: Guía para clientes de atribución de Singular para la planificación.

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

Envío de eventos

Pautas de implementación de eventos

Envía eventos a Singular usando los métodos eventJSON o event (recomendamos eventJSON para mejorar la legibilidad).

  • Eventos estándar: Usa el nombre de Android del evento de la lista de eventos estándar, p. ej., sngTutorialComplete
  • Eventos personalizados: Para eventos exclusivos de tu app que no coincidan con los 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 socios externos y soluciones de análisis
  • Nombres de eventos: Limitados a 32 caracteres ASCII. Las cadenas que no sean ASCII deben tener menos de 32 bytes al convertirse a UTF-8
  • Atributos y valores: Limitados a 500 caracteres ASCII

Método eventJSON

Reporta eventos de usuario con información adicional usando el formato JSONObject para datos estructurados.

Firma del método: 

Singular.eventJSON(String name, JSONObject args)

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

Ejemplos de uso

Kotlin Java 
// Example 1: Standard event with recommended attributes
val att = JSONObject().apply {
    put(Attributes.sngAttrContent.toString(), "Telugu")
    put(Attributes.sngAttrContentId.toString(), 32)
    put(Attributes.sngAttrContentType.toString(), "video")
    put(Attributes.sngAttrSuccess.toString(), 75)
}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Example 2: Custom event with custom attributes
val att = JSONObject().apply {
    put("Points", 500)
    put("score", 650)
}
Singular.eventJSON("Bonus Points Earned", att)

Método event

Reporta eventos de usuario con o sin información adicional usando argumentos variables.

Firmas del método: 

Singular.event(String eventName)
Singular.event(String eventName, Object... args)

Nota: El parámetro args acepta uno o más pares clave-valor. Las claves deben ser cadenas y los valores pueden ser de cualquier tipo permitido como valor de JSONObject (JSONObject, JSONArray, String, Boolean, Integer, Long, Double o NULL). La lista args debe contener un número par de elementos o el evento será rechazado.

Ejemplos de uso

Kotlin Java 
// Example 1: Standard event without attributes
Singular.event(Events.sngSubscribe.toString())

// Example 2: Standard event with recommended attributes
Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Telugu",
    Attributes.sngAttrContentId.toString(), "32",
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), "yes"
)

// Example 3: Custom event without attributes
Singular.event("SignUp")

// Example 4: Custom event with custom attribute
Singular.event("Bonus Points Earned", "Points", 500)

Seguimiento de ingresos in-app

Realiza el seguimiento de los ingresos 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:

  • Reportes interactivos: Visualiza las métricas de ingresos en el panel 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 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 (p. ej., USD, EUR, INR)

Prácticas recomendadas

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

Compra in-app sin suscripción

Integración del objeto Purchase

Pasa el objeto Purchase de Google Billing Library a los métodos revenue o customRevenue para obtener reportes enriquecidos y validación de transacciones.

Beneficios:

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

Notas:

  • Nombres de eventos personalizados: El método customRevenue acepta nombres de eventos personalizados para desglosar los ingresos por tipo de evento en los reportes
  • Conversión de moneda: Los ingresos en diferentes monedas se convierten automáticamente a la moneda preferida de tu organización

Método revenue con Purchase

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

Firma del método: 

Singular.revenue(String currency, double amount, Object purchase)

Ejemplo de uso

Kotlin Java 
Singular.revenue("USD", 5.50, purchase)

Método customRevenue con Purchase

Envía un evento de ingresos con un nombre personalizado y el objeto Purchase para un seguimiento de ingresos categorizado.

Firma del método: 

Singular.customRevenue(String eventName, String currency, double amount, Object purchase)

Ejemplo de uso

Kotlin Java 
Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)

Ingresos por suscripción

Implementación de eventos de suscripción

Realiza el 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 Guía técnica de implementación de eventos de suscripción para obtener instrucciones detalladas sobre el seguimiento de suscripciones con el SDK de Singular.

Ingresos personalizados sin validación de Purchase

Seguimiento manual de ingresos

Realiza el seguimiento de los ingresos pasando la moneda, el monto y los detalles opcionales del producto sin el objeto Purchase. 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 del objeto Purchase descritos anteriormente siempre que sea posible.

Método revenue sin Purchase

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

Firmas del método: 

Singular.revenue(String currency, double amount)
Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.revenue(String currency, double amount, Map<String, Object> attributes)

Ejemplos de uso

Kotlin Java 
// Without product details
Singular.revenue("USD", 5.50)

// With product details
Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee", 1, 5.00)

// With product details in an attribute map
val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}
Singular.revenue("USD", 9.99, attributes)

Método customRevenue sin Purchase

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

Firmas del método: 

Singular.customRevenue(String eventName, String currency, double amount)
Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.customRevenue(String eventName, String currency, double amount, Map<String, Object> attributes)

Ejemplos de uso

Kotlin Java 
// Without product details
Singular.customRevenue("MyCustomRevenue", "USD", 5.50)

// With product details
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee", 1, 5.00)

// With product details in an attribute map
val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}
Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes)

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 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 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á incorrectamente

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:

  • Captura de 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 eventos del lado del servidor con el identificador de dispositivo correspondiente a la plataforma (p. ej., 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 las preguntas frecuentes sobre el postback de Internal BI
  • 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 de ingresos externos como RevenueCat o adapty para enviar ingresos de compras y suscripciones a Singular.

Proveedores compatibles:

Envío de eventos desde Segment

Habilita Segment para enviar eventos a Singular en paralelo con el SDK de Singular agregando una destinación de "Cloud-Mode" en Segment.

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