Integração com o Google Analytics

Assistência de desenvolvedor necessária

Você precisará da ajuda da sua equipe de desenvolvimento para configurar a integração. Por favor, compartilhe este guia com eles.

Envie o mesmo ID de usuário para o Google Analytics 4 e o Pushwoosh, e as duas ferramentas tratarão uma pessoa que visita seu site ou aplicativo como um único usuário. Assim, você pode enviar mensagens para os usuários que analisa no Google Analytics e criar segmentos do Pushwoosh a partir de dados do Google Analytics.

Visão geral da integração

Tipo de integração

Destino: os públicos do Google Analytics e a exportação do Google Analytics para o BigQuery se tornam segmentos do Pushwoosh. O ID de usuário vai do seu site ou aplicativo para cada ferramenta separadamente. O Pushwoosh não envia dados para o Google Analytics.

Pré-requisitos

• Uma conta do Pushwoosh e o SDK do Pushwoosh (Web, Android ou iOS) no site ou no aplicativo de onde você envia o ID de usuário.
• Uma propriedade do Google Analytics 4 que coleta dados do mesmo site ou aplicativo.

Para importar públicos do Google Analytics, você também precisa de:

• Uma conta de serviço do Google Cloud e a chave JSON dela. Consulte Create and delete service account keys.
• A Google Analytics Data API e a Admin API ativadas no projeto dessa conta de serviço.
• O papel Viewer para a conta de serviço na propriedade do Google Analytics. Consulte Add, edit, and delete users and user groups.

Para consultar a exportação do BigQuery, você também precisa de:

• A propriedade do Google Analytics 4 vinculada ao BigQuery. Consulte Set up BigQuery Export.
• Uma chave de conta de serviço com os papéis BigQuery Data Viewer e BigQuery Job User. Consulte BigQuery roles and permissions.

Como funciona a integração?

O Pushwoosh relaciona os usuários pelo ID:

1. Seu site ou aplicativo envia o mesmo ID de usuário para o Google Analytics e para o Pushwoosh.
2. O Pushwoosh lê os IDs de usuário de um público do Google Analytics ou da sua exportação do BigQuery.
3. Um usuário entra no segmento quando o ID dele corresponde a um User ID do Pushwoosh.

O segmento é atualizado de forma diferente para cada fonte:

• Um segmento criado a partir de um público é atualizado cerca de uma vez por dia enquanto você o usa.
• Um segmento criado a partir do BigQuery reflete a atividade até o dia anterior.

Configurando a integração

A configuração tem duas partes. Primeiro, seus desenvolvedores enviam o ID de usuário do seu site ou aplicativo. Depois, você cria um segmento a partir de dados do Google Analytics no Control Panel.

1. Junto com seus desenvolvedores, escolha o ID de usuário.
2. Seus desenvolvedores o enviam para o Google Analytics e para o Pushwoosh a partir do seu site ou do seu aplicativo móvel.
3. Opcionalmente, crie um segmento do Pushwoosh a partir de dados do Google Analytics. Depois, você pode usá-lo como qualquer outro segmento.

Envie o ID de usuário para o Google Analytics e o Pushwoosh

Esta parte é feita pelos seus desenvolvedores. Compartilhe as seções abaixo com eles.

Escolha o ID de usuário

Use um identificador que seu próprio sistema já tenha para cada usuário, como o ID da conta no seu banco de dados. O mesmo valor vai para o Google Analytics como o ID de usuário dele e para o Pushwoosh como o User ID.

Não use informações pessoais no ID de usuário

As políticas do Google Analytics não permitem informações pessoais no ID de usuário. Não use endereço de e-mail, número de telefone ou outras informações pessoais.

Defina o ID no momento em que o usuário faz login ou é identificado de outra forma.

Envie o ID de usuário do seu site

Passe o ID para o Google Analytics no parâmetro user_id da sua tag do Google. Se você usa o Google Tag Manager, defina o campo user_id na configuração da sua tag do Google. Consulte Send user IDs na documentação do Google.

JavaScript

gtag('config', 'G-XXXXXXXXXX', {
  'user_id': 'USER_ID'
});

Passe o mesmo ID para o Pushwoosh com o Web Push SDK:

JavaScript

Pushwoosh.push((api) => {
  api.registerUser('USER_ID');
});

Envie o ID de usuário do seu aplicativo móvel

Os aplicativos móveis enviam dados para o Google Analytics 4 por meio do Firebase. Defina o ID com o setUserId do Firebase Analytics (consulte Set a user ID na documentação do Firebase) e defina o mesmo valor com o SDK do Pushwoosh.

Android

Java

FirebaseAnalytics.getInstance(context).setUserId("USER_ID");
Pushwoosh.getInstance().setUserId("USER_ID");

iOS

Swift

Analytics.setUserID("USER_ID")
Pushwoosh.sharedInstance().setUserId("USER_ID")

Crie um segmento a partir de dados do Google Analytics

Você faz esta parte no Control Panel, depois que seus desenvolvedores enviam o ID de usuário. O Pushwoosh pode transformar dados do Google Analytics em um segmento de duas formas, ambas por meio de segmentos externos:

• Importar um público do Google Analytics: escolha um público que você já criou no Google Analytics. Não é preciso SQL nem BigQuery.
• Consultar a exportação do BigQuery: escreva seu próprio SQL sobre os eventos brutos que o Google Analytics exporta para o BigQuery, para condições que um público não consegue expressar.

Importar um público do Google Analytics

Peça ao seu desenvolvedor ou administrador do Google Cloud que faça estas etapas no Google Cloud e no Google Analytics:

1. Prepare uma conta de serviço e a chave JSON dela. Consulte Create and delete service account keys na documentação do Google Cloud.
2. No projeto do Google Cloud da conta de serviço, ative a Google Analytics Data API e a Google Analytics Admin API.
3. No Google Analytics, acesse Admin → Property access management e adicione o e-mail da conta de serviço com o papel Viewer. Um papel concedido no Google Cloud IAM não dá acesso ao Google Analytics.

Depois, faça estas etapas no Control Panel:

1. Crie um segmento externo com o Tipo de banco de dados definido como Google Analytics 4 audience.

2. Insira o ID da propriedade do GA4. Você pode encontrá-lo no Google Analytics em Admin → Property details.

3. Cole a chave JSON da primeira lista em Service account JSON.

4. Clique em Carregar públicos-alvo e escolha o Público-alvo.

   

5. Clique em Verificar conexão.

6. Clique em Criar.

O Pushwoosh atualiza o segmento quando lê o segmento inteiro, por exemplo, quando você envia uma campanha ou uma Journey para ele ou calcula o tamanho dele:

• Se os dados tiverem menos de 24 horas, o Pushwoosh os usa como estão, porque o Google Analytics atualiza a associação ao público cerca de uma vez por dia.
• Se tiverem mais de 24 horas, o Pushwoosh usa os dados atuais e atualiza o segmento em segundo plano.
• Se tiverem mais de 72 horas, o Pushwoosh aguarda a conclusão da atualização.

Não é possível atualizar o segmento mais de uma vez por dia. Se ele não for atualizado há mais de um dia, calcule o tamanho do segmento algum tempo antes do envio. Isso inicia a atualização em segundo plano, para que o envio use dados mais recentes.

Consultar a exportação do BigQuery

Se você exporta seus dados do Google Analytics 4 para o BigQuery, pode selecionar usuários com qualquer condição SQL sobre os eventos deles, por exemplo, todos que fizeram uma compra nos últimos 30 dias.

Peça ao seu desenvolvedor ou administrador do Google Cloud que faça estas etapas no Google Cloud e no Google Analytics:

1. Vincule sua propriedade do Google Analytics 4 a um projeto do BigQuery e ative a exportação diária. Siga Set up BigQuery Export na documentação do Google.

   O Google Analytics passa então a gravar os eventos de cada dia em uma tabela chamada events_YYYYMMDD em um conjunto de dados chamado analytics_<property ID>. O ID de usuário que você enviou nas seções anteriores fica na coluna user_id.

2. Crie uma chave de conta de serviço com os papéis BigQuery Data Viewer e BigQuery Job User. Verificar conexão e Verificar consulta executam um job de consulta de teste no seu projeto, então falham sem BigQuery Job User.

Depois, no Control Panel, crie um segmento externo com o Tipo de banco de dados definido como Google BigQuery. Insira a chave da conta de serviço para a conexão e uma consulta que retorne os IDs de usuário dos usuários desejados.

Por exemplo, esta consulta retorna os usuários que fizeram uma compra nos últimos 30 dias. Substitua my-project pelo ID do seu projeto do Google Cloud e analytics_123456789 pelo nome do seu conjunto de dados:

SQL

SELECT DISTINCT user_id
FROM `my-project.analytics_123456789.events_*`
WHERE event_name = 'purchase'
  AND user_id IS NOT NULL
  AND _TABLE_SUFFIX >= FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))

O segmento reflete a atividade até o dia anterior, porque o Google Analytics exporta os dados uma vez por dia.

Como você sabe que a integração está funcionando?

• ID de usuário: no Pushwoosh, acesse Público → Explorador de usuários e pesquise por User ID um ID que você enviou para o Google Analytics. Se o usuário for encontrado, as duas ferramentas têm o mesmo ID.
• Segmentos: em Público → Segmentos externos, o status do segmento é válido. Para ver quantos usuários corresponderam, verifique o tamanho do segmento.

Solução de problemas

Carregar públicos-alvo ou Verificar conexão mostra um erro

Os dois botões fazem login com a chave da conta de serviço e leem a lista de públicos da propriedade, e o formulário mostra o erro retornado pelo Google Analytics. Verifique se:

• Service account JSON é uma chave de conta de serviço. Outros arquivos de credenciais do Google são rejeitados.
• ID da propriedade do GA4 é o número em Admin → Property details.
• A conta de serviço tem o papel Viewer no Google Analytics, em Admin → Property access management. Um papel concedido no Google Cloud IAM não conta.
• A Google Analytics Admin API está ativada no projeto do Google Cloud da conta de serviço.

A lista de públicos está vazia

A propriedade ainda não tem públicos. Crie um no Google Analytics em Admin → Audiences e clique em Carregar públicos-alvo novamente.

Ninguém entra no segmento

• Verifique se a Google Analytics Data API está ativada. Verificar conexão não a testa, mas o Pushwoosh precisa dela para ler os membros do público.
• Verifique se seu site ou aplicativo envia o mesmo ID de usuário para o Google Analytics e para o Pushwoosh. Só entram no segmento os usuários cujo ID de usuário no Google Analytics corresponde a um User ID do Pushwoosh. Usuários que o Google Analytics conhece apenas pelo ID de cliente anônimo não entram.

Verificar conexão ou Verificar consulta falha para o BigQuery

As duas verificações executam um job de consulta de teste no seu projeto do Google Cloud sem ler nenhum dado. Verifique se:

• A conta de serviço tem os dois papéis, BigQuery Data Viewer e BigQuery Job User. Sem BigQuery Job User, nenhuma das verificações consegue ser executada.
• A consulta usa o ID do seu projeto e o nome do conjunto de dados analytics_<property ID>, e a exportação já gravou pelo menos uma tabela diária events_YYYYMMDD.
• A consulta retorna exatamente uma coluna, chamada user_id.