Configuração da integração de postback de atribuição do Google Analytics 4 (GA4)

Seguir
Avatar
Ghani Yusuf
Updated
Documento

Visão geral

A Singular oferece suporte à integração com o Google Analytics 4 (GA4) como parceiro de análise terceirizado.
Este guia explica como configurar a medição do GA4 para seu aplicativo móvel usando o Singular e garantir que os parâmetros necessários sejam passados corretamente.

O Singular encaminha os dados de atribuição da campanha automaticamente para o GA4, enquanto credenciais e identificadores específicos devem ser configurados na interface do usuário e no SDK do Singular.

Informação: O Singular encaminha os dados de atribuição para o GA4 para medição e relatórios. A análise de produtos, como funis e análise do comportamento do utilizador, deve continuar a ser tratada diretamente no GA4 ou no Firebase.

Parâmetros enviados do Singular para o GA4

O Singular encaminha automaticamente os seguintes parâmetros para o Google Analytics 4:

  • Nome da campanha

  • ID da campanha

  • Fonte

  • Meio

  • Carimbo de data/hora

Informação: Estes parâmetros são preenchidos automaticamente com base nos dados de atribuição do Singular. Não é necessária nenhuma configuração adicional do SDK.

Configuração necessária na interface de configuração do parceiro Singular

Os seguintes valores devem ser configurados diretamente no painel do Singular para habilitar a medição do GA4.

Screenshot of Singular GA4 partner configuration

1. Segredo da API (api_secret)

O segredo da API do protocolo de medição GA4.

Onde encontrá-lo:

GA4 Admin → Data Streams → Select your stream → Measurement Protocol → Create API Secret

Importante: o segredo da API é necessário para que o Singular envie eventos para o GA4 por meio do protocolo de medição. Sem esse valor, os eventos do GA4 não serão registrados.

2. ID do aplicativo Firebase (firebase_app_id)

O ID do aplicativo Firebase associado ao seu aplicativo móvel.

Onde encontrá-lo:

Firebase Console → Project Settings → General → Your Apps → App ID
Screenshot of Firebase App ID location

Observação: certifique-se de que o firebase_app_id configurado no Singular corresponda exatamente ao aplicativo Firebase usado em sua versão de produção. Uma incompatibilidade impedirá que o GA4 associe eventos ao seu aplicativo.

Configuração necessária no SDK Singular

3. ID da instância do aplicativo (app_instance_id)

O app_instance_id é um identificador exclusivo para uma instalação específica do seu aplicativo Firebase.

Requisitos:

  • Recupere o valor do SDK do Firebase

  • Passe-o para o SDK Singular usando GLOBAL_PROPERTIES, conforme mencionado neste guia

  • Use o nome exato da propriedade: app_instance_id

Observação: o app_instance_id deve ser definido antes de inicializar o SDK Singular. Definir esse valor após a inicialização pode resultar na perda ou atribuição incorreta de eventos GA4.

Exemplo de implementação do SDK (Android – Kotlin)

Use propriedades globais para rastrear identificadores específicos do usuário e do nível do aplicativo ao longo do ciclo de vida do aplicativo.

// Initialize the Singular SDK with app-level global properties val config = SingularConfig("SDK_KEY", "SDK_SECRET") .withGlobalProperty("app_instance_id", firebaseAppInstanceId, true) Singular.init(applicationContext, config)

// Set a third-party identifier on user login
fun onUserLogin(thirdPartyUserId: String) {
val success = Singular.setGlobalProperty(
"third_party_identifier",
thirdPartyUserId,
true
)
if (success) {
Log.d("Singular", "Third-party identifier set successfully")
}
}

// Clear the third-party identifier on user logout
fun onUserLogout() {
Singular.unsetGlobalProperty("third_party_identifier")
Log.d("Singular", "Third-party identifier cleared")
}

Dica: use setGlobalProperty para identificadores que devem persistir entre as sessões. Sempre chame unsetGlobalProperty quando o identificador não for mais válido, como no logout do usuário.

Validação e solução de problemas

Após concluir a configuração, valide sua integração:

  1. Confirme se api_secret e firebase_app_id estão salvos corretamente na interface do usuário do Singular

  2. Verifique se app_instance_id está definido antes da inicialização do SDK

  3. Use o GA4 DebugView ou os relatórios em tempo real para confirmar se os eventos são recebidos

  4. Revise os logs do aplicativo para erros de inicialização do SDK Singular

Informação: o GA4 pode demorar vários minutos a apresentar novos eventos. Utilize o DebugView para uma validação quase em tempo real durante os testes.

Comentários

Por favor, entre para comentar.