SDK do Android - Rastreamento de eventos in-app

Seguir
Avatar
Jared Ornstead
Updated

Rastreamento de eventos in-app

Rastreie eventos in-app para analisar o desempenho das campanhas e medir indicadores-chave de desempenho (KPIs) como logins de usuários, cadastros, conclusões de tutoriais ou marcos de progressão.

Eventos e atributos padrão

Usando eventos padrão

O Singular oferece suporte a eventos padrão que são reconhecidos pelas redes de anúncios para geração de relatórios e otimização. Use nomes de eventos padrão sempre que possível para reconhecimento automático e configuração simplificada.

Sua equipe de UA, marketing ou negócios deve compilar a lista de eventos com base nos KPIs de marketing da sua organização. Consulte o guia Como rastrear eventos in-app: Guia para clientes de atribuição do Singular para o planejamento.

Cada evento oferece suporte a vários atributos. Consulte os atributos padrão recomendados por evento para obter detalhes de implementação.

Enviando eventos

Diretrizes de implementação de eventos

Envie eventos ao Singular usando os métodos eventJSON ou event (recomendamos eventJSON para melhor legibilidade).

  • Eventos padrão: Use o nome Android do evento da lista de eventos padrão, por exemplo, sngTutorialComplete
  • Eventos personalizados: Para eventos exclusivos do seu app que não correspondam aos eventos padrão, use qualquer string descritiva que esteja em conformidade com as limitações de caracteres

Limitações de eventos personalizados:

  • Idioma: Passe os nomes e atributos dos eventos em inglês para garantir a compatibilidade com parceiros terceiros e soluções de análise
  • Nomes de eventos: Limitados a 32 caracteres ASCII. Strings não ASCII devem ter menos de 32 bytes quando convertidas para UTF-8
  • Atributos e valores: Limitados a 500 caracteres ASCII

Método eventJSON

Reporte eventos de usuário com informações adicionais usando o formato JSONObject para dados estruturados.

Assinatura do método: 

Singular.eventJSON(String name, JSONObject args)

Observação: O parâmetro args é um JSONObject contendo um ou mais pares de chave-valor. As chaves devem ser strings e os valores podem ser de qualquer tipo permitido como valor de JSONObject.

Exemplos 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

Reporte eventos de usuário com ou sem informações adicionais usando argumentos variáveis.

Assinaturas do método: 

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

Observação: O parâmetro args aceita um ou mais pares de chave-valor. As chaves devem ser strings e os valores podem ser de qualquer tipo permitido como valor de JSONObject (JSONObject, JSONArray, String, Boolean, Integer, Long, Double ou NULL). A lista args deve conter um número par de elementos, ou o evento será rejeitado.

Exemplos 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)

Rastreamento de receita in-app

Rastreie a receita de compras in-app (IAP), assinaturas e fontes de receita personalizadas para medir o desempenho das campanhas e o retorno sobre o investimento em anúncios (ROAS).

Os dados de receita fluem por três canais:

  • Relatórios interativos: Visualize as métricas de receita no painel do Singular
  • Export Logs: Acesse dados ETL detalhados para análise personalizada
  • Postbacks em tempo real: Envie eventos de receita para plataformas externas

Limitações de eventos de receita:

  • Nomes de eventos: Os nomes de eventos de receita personalizados são limitados a 32 caracteres ASCII (ou 32 bytes para não ASCII quando convertidos para UTF-8)
  • Atributos: Os nomes e valores de atributos de eventos são limitados a 500 caracteres ASCII
  • Códigos de moeda: Devem estar em MAIÚSCULAS e seguir o padrão de três letras ISO 4217 (por exemplo, USD, EUR, INR)

Práticas recomendadas

  • Nomenclatura padrão: Use a convenção de nomenclatura de eventos e atributos padrão do Singular
  • Idioma: Envie os nomes de eventos de receita personalizados em inglês para melhor compatibilidade com postbacks de redes de anúncios
  • Valores diferentes de zero: Envie eventos de receita apenas quando o valor for maior ou menor que 0

Compra in-app sem assinatura

Integração do objeto Purchase

Passe o objeto Purchase da Google Billing Library para os métodos revenue ou customRevenue para relatórios enriquecidos e validação de transações.

Benefícios:

  • Dados ricos: O Singular recebe detalhes completos da transação para relatórios abrangentes
  • Prevenção de fraudes: Os recibos de transações permitem a validação para combater fraudes in-app

Observações:

  • Nomes de eventos personalizados: O método customRevenue aceita nomes de eventos personalizados para detalhar a receita por tipo de evento nos relatórios
  • Conversão de moeda: A receita em diferentes moedas é convertida automaticamente para a moeda preferencial da sua organização

Método revenue com Purchase

Envie um evento de receita com o objeto Purchase para validação automática e dados enriquecidos.

Assinatura do método: 

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

Exemplo de uso

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

Método customRevenue com Purchase

Envie um evento de receita com um nome personalizado e o objeto Purchase para rastreamento de receita categorizado.

Assinatura do método: 

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

Exemplo de uso

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

Receita de assinatura

Implementação de eventos de assinatura

Rastreie compras e renovações de assinaturas para obter insights sobre o comportamento dos usuários e a geração de receita recorrente.

Guia de implementação: Revise o abrangente Guia técnico de implementação de eventos de assinatura para obter instruções detalhadas sobre o rastreamento de assinaturas com o SDK do Singular.

Receita personalizada sem validação de Purchase

Rastreamento manual de receita

Rastreie a receita passando moeda, valor e detalhes opcionais do produto sem o objeto Purchase. Observe que este método não fornece recibos de transações para validação.

Importante: Ao usar esses métodos, o Singular não pode validar transações. Recomendamos fortemente usar os métodos do objeto Purchase descritos acima sempre que possível.

Método revenue sem Purchase

Envie eventos de receita com moeda, valor e detalhes opcionais do produto.

Assinaturas do 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)

Exemplos 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 sem Purchase

Envie eventos de receita personalizados com um nome de evento especificado, moeda, valor e atributos de transação opcionais.

Assinaturas do 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)

Exemplos 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)

Rastreamento híbrido de eventos (Avançado)

Envie todos os eventos e receitas por meio do SDK do Singular integrado ao seu app para uma atribuição ideal. No entanto, o Singular pode coletar eventos de outras fontes quando necessário.

Os eventos enviados fora do SDK do Singular devem estar em conformidade com a documentação de eventos servidor a servidor do Singular e fornecer identificadores de dispositivo correspondentes para uma atribuição correta.

Importante:

As discrepâncias ocorrem quando os identificadores de dispositivo nas solicitações servidor a servidor não correspondem aos identificadores registrados pelo SDK do Singular:

  • Eventos antecipados: Se um evento chegar antes de o SDK do Singular registrar o identificador de dispositivo, o evento se torna a "primeira sessão" de um dispositivo desconhecido, resultando em atribuição orgânica
  • Identificadores incompatíveis: Se o SDK do Singular registrou um identificador de dispositivo diferente daquele na solicitação servidor a servidor, o evento será atribuído incorretamente

Guias de rastreamento híbrido de eventos

Enviando eventos de um servidor interno

Colete dados de receita do seu servidor interno para analisar o desempenho das campanhas e o ROI.

Requisitos:

  • Captura de identificadores de dispositivo: Durante os eventos de cadastro ou login in-app, capture e passe os identificadores de dispositivo, depois armazene esses dados com o User ID no seu servidor. Atualize os identificadores quando os usuários gerarem novas sessões do app para garantir uma atribuição correta
  • Identificadores específicos da plataforma: Envie eventos do lado do servidor com o identificador de dispositivo correspondente à plataforma (por exemplo, IDFA ou IDFV para dispositivos iOS)
  • Atualizações em tempo real: Use o mecanismo de postback do Singular Internal BI para enviar eventos em tempo real ao seu endpoint. Consulte as perguntas frequentes sobre o postback do Internal BI
  • Detalhes de implementação: Revise a seção "Tracking Revenue" no guia de integração servidor a servidor

Enviando eventos de um provedor de receita

Integre provedores de receita terceiros como RevenueCat ou adapty para enviar receita de compras e assinaturas ao Singular.

Provedores compatíveis:

Enviando eventos do Segment

Habilite o Segment para enviar eventos ao Singular em paralelo com o SDK do Singular adicionando uma destinação "Cloud-Mode" no Segment.

Siga o guia de implementação Integração Singular-Segment para obter instruções detalhadas de configuração.