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

Seguir
Avatar
Jared Ornstead
Updated
Documento SDK de Android - Seguimiento de eventos e ingresos

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 usuario, 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 eventJSON o event (recomendamos eventJSON para mejorar la legibilidad).

  • Eventos estándar: Utilice el nombre Android del eventode la lista de eventos estándar, por ejemplo, sngTutorialComplete.
  • 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 los 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 eventJSON

Notificar eventos de usuario con información adicional utilizando 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 JSONObject.

Ejemplos de uso

KotlinJava 
// 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)

event Método

Notifica eventos de usuario con o sin información adicional utilizando argumentos variables.

Firmasdel 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 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

KotlinJava 
// 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 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 del objeto de compra

Pase el objeto de comprade la biblioteca de facturación de Google a los métodos revenue o customRevenue 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 transacción permiten la validación para combatir el fraude dentro de la aplicación.

Notas:

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

Método de ingresos con compra

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

Firma del método: 

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

Ejemplo de uso

KotlinJava 
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

KotlinJava 
Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)

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 de compra. Tenga en cuenta que este método no proporciona recibos de transacción para su validación.

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

Método de ingresos sin compra

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

Firmas de métodos: 

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

KotlinJava 
// 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)

customRevenue Método sin compra

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

Firmas de métodos: 

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

KotlinJava 
// 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 de Eventos Híbrido (Avanzado)

Envíe todos los eventos e ingresos a través del SDK de Singular integrado en su aplicación 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 servidorde 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 de postback de BI internode Singular para enviar eventos en tiempo real a su endpoint. Consulte las preguntas frecuentes sobre postback de BI interno
  • 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:

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-Segmentpara obtener instrucciones detalladas de configuración.