Integração com o Google BigQuery

É necessária a assistência de um desenvolvedor

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

A integração com o Google BigQuery transmite eventos de mensagens selecionados do Pushwoosh para o seu conjunto de dados do BigQuery. Use-a para analisar eventos do ciclo de vida de push, e-mail e SMS no BigQuery, criar relatórios personalizados ou conectar os dados aos seus fluxos de trabalho de análise downstream.

Visão geral da integração

Pré-requisitos

Prepare o seguinte antes de abrir a configuração da integração.

1. Use um projeto do Google Cloud com o faturamento ativado. Créditos do Teste Gratuito são suportados. O Sandbox do BigQuery não é suficiente porque a API de Escrita de Armazenamento (Storage Write API) requer faturamento.

2. Certifique-se de que você tem uma conta paga do Pushwoosh.

Preços

Você paga diretamente ao Google pelo uso do BigQuery. O Pushwoosh não cobra pela integração em si.

Para taxas atuais, níveis gratuitos e detalhes regionais, consulte os preços do BigQuery.

Os custos podem incluir:

• Ingestão de dados: O Pushwoosh transmite eventos com a API de Escrita de Armazenamento do BigQuery (BigQuery Storage Write API).
• Armazenamento: O BigQuery armazena as linhas escritas na sua tabela de destino.
• Consultas: O BigQuery cobra por consultas com base no modelo de preços selecionado.

Tipo de integração

Fonte: Os dados são enviados do Pushwoosh para o seu conjunto de dados do BigQuery.

Plataformas suportadas

O Pushwoosh transmite eventos das plataformas iOS, Android, Huawei, Chrome, Safari, Firefox e Web.

Entidades sincronizadas

Eventos selecionados do ciclo de vida de push, e-mail e SMS são transmitidos para o BigQuery. O Pushwoosh escreve uma linha por evento selecionado na tabela de destino.

Casos de uso

• Análise de mensagens quase em tempo real: analise eventos do ciclo de vida de push, e-mail e SMS no BigQuery logo após serem processados no Pushwoosh.
• Relatórios personalizados: crie relatórios no BigQuery para tipos de eventos, aplicativos, campanhas e identificadores de mensagens selecionados.
• Fluxos de trabalho de dados downstream: conecte os dados de eventos do Pushwoosh aos seus fluxos de trabalho de análise, relatórios ou processamento de dados.

Como a integração funciona

Depois de salvar a configuração, o Pushwoosh começa a transmitir os eventos de mensagens selecionados para a sua tabela do BigQuery quase em tempo real. Para cada evento de mensagem que flui através do Pushwoosh, o sistema verifica se o tipo de evento está selecionado na sua configuração.

Se estiver, o Pushwoosh anexa uma nova linha à sua tabela de destino. Se a tabela ainda não existir, o Pushwoosh a cria automaticamente usando o esquema descrito abaixo. Os eventos geralmente aparecem no BigQuery em 30 segundos após serem processados no Pushwoosh.

Configure a integração no Google Cloud

Escolha um projeto do Google Cloud

Faça login no Google Cloud Console e, em seguida, escolha ou crie o projeto que será o proprietário do conjunto de dados do BigQuery.

Dica

Anote o ID do Projeto. Use o identificador curto, por exemplo my-company-12345, e não o nome do projeto legível por humanos.

Habilite as APIs necessárias

No Google Cloud Console, vá para APIs e Serviços → Biblioteca e habilite estas APIs:

• API do BigQuery
• API de Armazenamento do BigQuery

O Pushwoosh usa essas APIs para criar a tabela de destino e transmitir eventos para o BigQuery.

Crie uma Conta de Serviço

O Pushwoosh usa a Conta de Serviço para escrever eventos no seu conjunto de dados do BigQuery.

1. Vá para IAM e Admin → Contas de Serviço.

2. Clique em Criar conta de serviço.

3. Em Nome da conta de serviço, insira um nome, por exemplo, pushwoosh-bigquery.

   O Google Cloud gera automaticamente o ID da conta de serviço a partir do nome.

   

4. Clique em Criar e continuar.

Conceda papéis do IAM

1. Conceda à Conta de Serviço estes papéis do IAM:

   • Editor de Dados do BigQuery: permite que o Pushwoosh crie a tabela e anexe linhas.
   • Usuário do BigQuery: permite que o Pushwoosh use a API de Escrita de Armazenamento.
   

Nota

Você pode anexar os papéis no nível do projeto ou no nível do conjunto de dados. O acesso no nível do projeto é o mais fácil de configurar. O acesso no nível do conjunto de dados é mais restritivo e recomendado para produção.

2. Clique em Continuar.

3. Clique em Concluído.

Crie uma chave JSON

O Pushwoosh usa a chave JSON para se autenticar como a conta de serviço.

1. Abra a conta de serviço que você criou.

2. Vá para Chaves → Adicionar chave → Criar nova chave.

3. Selecione JSON.

O Google Cloud baixa o arquivo de chave JSON para o seu computador.

Cuidado

Mantenha o arquivo de chave JSON seguro. Qualquer pessoa com este arquivo pode escrever no seu projeto do BigQuery. Não o envie para o git nem o compartilhe por chat. O Pushwoosh armazena a chave criptografada em repouso e não a expõe através da interface do usuário após o upload.

Crie um conjunto de dados

O conjunto de dados é onde o Pushwoosh armazena a tabela de eventos transmitidos.

1. No Google Cloud Console, abra o BigQuery.

2. No Explorador, selecione o projeto que você preparou para a integração.

3. Clique em Criar conjunto de dados.

4. Em ID do conjunto de dados, insira um ID de conjunto de dados, por exemplo pushwoosh_data.

5. Em Localização dos dados, selecione a região do conjunto de dados.

6. Clique em Criar conjunto de dados.

Configure a integração no Pushwoosh

1. Na sua conta do Pushwoosh, vá para Configurações → Integrações de Terceiros para o aplicativo que você deseja conectar.

2. Encontre o Google BigQuery na lista de serviços disponíveis e clique em Configurar.

3. Preencha os campos de configuração.

• ID do Projeto GCP: insira o ID do projeto do Google Cloud, por exemplo my-company-12345.
• JSON da Conta de Serviço: cole o conteúdo completo do arquivo de chave JSON que você baixou do Google Cloud.
• ID do Conjunto de Dados: uma vez que o ID do Projeto GCP e o JSON da Conta de Serviço estejam preenchidos, o Pushwoosh busca os conjuntos de dados que sua Conta de Serviço pode acessar. Selecione o conjunto de dados de destino. Se a lista suspensa estiver vazia, verifique se a Conta de Serviço tem acesso e se o conjunto de dados existe no projeto que você especificou.
• Região do conjunto de dados: selecione a região do seu conjunto de dados do BigQuery.
• Nome da tabela: deixe em branco para usar a tabela padrão pushwoosh_events. O Pushwoosh cria a tabela com o esquema descrito abaixo.
• Eventos: selecione os eventos que você deseja transmitir. Você pode alterar esta lista mais tarde.
• Transmitir eventos para o BigQuery: habilite este botão. Desligue-o para pausar a transmissão sem excluir a configuração.

4. Clique em Testar conexão.

O Pushwoosh valida as credenciais com o BigQuery sem escrever dados.

Você pode ver um destes status de conexão:

• Conexão bem-sucedida: as credenciais funcionam e a Conta de Serviço pode acessar o conjunto de dados.
• auth_failed: a chave JSON é inválida ou foi revogada.
• dataset_not_found: o ID do conjunto de dados está incorreto ou a Conta de Serviço não pode acessá-lo.
• missing_permission: a Conta de Serviço não possui um dos papéis necessários.

5. Clique em Aplicar.

O Pushwoosh salva a configuração e começa a usá-la em cerca de 30 segundos. Depois disso, os eventos selecionados começam a ser transmitidos para o BigQuery.

Verifique a integração

1. Envie um push de teste ou acione outra mensagem que produza um dos tipos de evento que você selecionou.

2. Aguarde cerca de 30 segundos.

3. Abra o BigQuery Studio.

4. Vá para o seu projeto, depois abra o conjunto de dados e a tabela de destino que você configurou. Se você deixou o Nome da tabela em branco, abra pushwoosh_events.

5. Clique em Visualizar.

Você deve ver a linha do evento na tabela.

Esquema da tabela

O Pushwoosh escreve cada evento selecionado como uma linha separada na tabela de destino. Para tornar as consultas mais rápidas e fáceis de filtrar, a tabela é particionada por dia usando timestamp e clusterizada por app_id e event_kind.

Nome do campo	Tipo	Descrição
event_kind	STRING	Tipo de evento do Pushwoosh, por exemplo Push Sent ou Email Opened.
message_id	STRING	Código da mensagem do Pushwoosh, como o identificador da campanha ou da mensagem.
device_id	STRING	ID de hardware (HWID) do Pushwoosh do dispositivo que produziu o evento.
user_id	STRING	Seu ID de usuário externo, se conhecido. Vazio para dispositivos anônimos.
timestamp	TIMESTAMP	Hora do evento em UTC.
app_id	STRING	Código do aplicativo Pushwoosh.
platform	STRING	Plataforma de origem, por exemplo ios, android ou web.
properties	JSON	Campos de evento adicionais. Use JSON_VALUE para consultar campos, como mostrado abaixo.

Propriedades de consulta

A coluna properties armazena campos de evento adicionais como JSON. Use JSON_VALUE para extrair campos individuais em suas consultas.

Por exemplo, para ver quais campanhas geraram mais aberturas nos últimos 7 dias, clique em + para criar uma nova consulta, cole o SQL abaixo e clique em Executar.

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

Para revisar a contagem de eventos da última hora, execute esta consulta:

SELECT
  event_kind,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

Atualize a integração

Rotacione a chave da Conta de Serviço

1. No Google Cloud Console, vá para IAM e Admin → Contas de Serviço.

2. Abra sua Conta de Serviço.

3. Vá para Chaves e crie uma nova chave JSON.

4. Mantenha a chave antiga ativa até confirmar que a nova chave funciona.

5. No Pushwoosh, abra o modal de configuração do Google BigQuery.

6. Cole o novo JSON em JSON da Conta de Serviço.

7. Clique em Aplicar.

O Pushwoosh valida a nova chave, substitui a credencial armazenada e começa a usá-la após o próximo recarregamento da configuração, o que leva cerca de 30 segundos.

Depois de confirmar que os eventos ainda estão fluindo, exclua a chave antiga no Google Cloud Console.

Altere o conjunto de dados ou a tabela de destino

1. No Pushwoosh, vá para Configurações → Integrações de Terceiros.

2. Abra as configurações do Google BigQuery.

3. Selecione um conjunto de dados diferente ou insira um novo nome de tabela.

4. Clique em Aplicar.

O Pushwoosh reabre o fluxo com o novo destino em cerca de 30 segundos. As linhas já escritas permanecem na tabela antiga. O Pushwoosh não preenche dados históricos.

Para manter a chave da Conta de Serviço armazenada inalterada ao atualizar outras configurações, deixe o campo JSON da Conta de Serviço vazio antes de clicar em Aplicar.

Solução de problemas

Problema	O que verificar
A conexão de teste falha com auth_failed	O JSON da Conta de Serviço está malformado ou a chave foi revogada no Google Cloud. Crie uma nova chave e cole o arquivo JSON completo novamente. O arquivo começa com {, termina com } e contém um bloco private_key.
A conexão de teste falha com dataset_not_found	O ID do Conjunto de Dados está escrito incorretamente ou não existe no projeto que você especificou. Os IDs de Conjunto de Dados diferenciam maiúsculas de minúsculas. Selecione o conjunto de dados na lista suspensa para evitar erros de digitação.
A conexão de teste falha com missing_permission	A Conta de Serviço não possui as funções Editor de Dados do BigQuery ou Usuário do BigQuery. Conceda ambas as funções no nível do projeto ou conceda-as no nível do conjunto de dados para um acesso mais restritivo.
A conexão de teste é bem-sucedida, mas nenhuma linha aparece no BigQuery	Aguarde pelo menos 30 segundos. Verifique se o tipo de evento que você está enviando está selecionado em Eventos. Por exemplo, se apenas Push Aberto estiver selecionado e ninguém abrir o push, nenhuma linha aparecerá.
A configuração parece correta, mas o modal mostra campos vazios	Recarregue a página. A configuração é buscada a cada abertura do modal e armazenada em cache por 30 segundos pelo serviço subjacente. Se você acabou de salvar as configurações, aguarde um momento e abra o modal novamente.

Nota

O Pushwoosh registra Push Sent, Email Sent e SMS Sent independentemente do status de entrega, para que as agregações do BigQuery correspondam às estatísticas canônicas do Pushwoosh. Para Delivered, Opened, Bounced e Unsubscribed, o Pushwoosh registra apenas eventos bem-sucedidos.

Perguntas Frequentes

Posso usar uma conta gratuita do Google Cloud?

Sim, desde que o faturamento esteja ativado no projeto. Os créditos do Teste Gratuito são suficientes para executar esta integração em volumes típicos durante todo o período de teste. O Sandbox do BigQuery sem faturamento não funcionará porque a API de Escrita de Armazenamento requer faturamento.

O Pushwoosh vê meus dados do BigQuery?

Não. A credencial da Conta de Serviço que você carrega autoriza o Pushwoosh a escrever no conjunto de dados que você seleciona. O Pushwoosh não lê do seu conjunto de dados e não tem acesso ao resto do seu projeto.

Posso exportar para vários conjuntos de dados do BigQuery?

Um destino é suportado por aplicativo. Se você precisar dos mesmos eventos em dois conjuntos de dados, configure uma consulta agendada do BigQuery em seu projeto para copiar dados de pushwoosh_events para outra tabela.

Posso alterar o esquema da tabela?

O esquema é fixo para todos os clientes. Se você precisar de colunas adicionais, extraia-as do JSON de properties em suas próprias visualizações ou consultas agendadas.

O que acontece se eu desativar a integração temporariamente?

Desligue a opção Transmitir eventos para o BigQuery e clique em Aplicar. O Pushwoosh para de anexar eventos para este aplicativo em cerca de 30 segundos.

Os eventos produzidos enquanto a integração está desativada não são armazenados em buffer ou preenchidos retroativamente quando você a ativa novamente. O Pushwoosh mantém a configuração, incluindo credenciais, conjunto de dados e seleção de eventos.

Como eu excluo a integração completamente?

Entre em contato com support@pushwoosh.com para excluir a configuração da integração. O conjunto de dados e as linhas já escritas no BigQuery permanecem em sua conta do Google Cloud.

Existem garantias de entrega?

A integração usa entrega pelo menos uma vez. Em operação normal, duplicatas são raras. Uma reinicialização do processo entre uma anexação e uma confirmação pode produzir um pequeno número de linhas duplicadas. Remova as duplicatas em SQL se seu pipeline downstream exigir resultados exatamente uma vez.

Por que não há um evento de Clique no Push?

Atualmente, o Pushwoosh expõe Push Sent, Push Delivered e Push Opened para notificações push nesta integração. Uma etapa dedicada de clique no push não está disponível. E-mail e SMS têm seus próprios eventos de ciclo de vida.