Google BigQuery

Visão geral

A integração OneSignal + BigQuery suporta dois pipelines de dados poderosos:

Exportação: Envie automaticamente dados de eventos de mensagens (push, email, SMS, in-app) do OneSignal para o BigQuery para análise e relatórios.
Importação: Sincronize eventos personalizados de usuários dos seus datasets BigQuery para o OneSignal para acionar Journeys automatizados e mensagens personalizadas.

Juntas, essas integrações dão a você controle completo sobre dados de engajamento do usuário—alimentando análises avançadas e mensagens em tempo real baseadas em comportamento.

Exportar eventos do OneSignal para o BigQuery

Envie eventos de desempenho e engajamento de mensagens (por exemplo, envios, aberturas, cliques) para o BigQuery para:

Construir dashboards e relatórios personalizados
Rastrear tendências de entrega e engajamento entre canais
Combinar dados do OneSignal com outros dados de negócios para análise

Requisitos

Acesso a Event Streams para eventos de mensagem de saída (Limitações de plano e excedentes se aplicam)
Acesso a Custom Events para sincronização de eventos de entrada (Limitações de plano e excedentes se aplicam)
Plano de Conta Atualizado (não disponível em apps gratuitos)

Projeto Google Cloud Platform com faturamento habilitado
BigQuery habilitado no seu projeto GCP
Conta de serviço com permissões de escrita no BigQuery

Etapas de configuração

1. Criar uma conta de serviço

Faça login na sua conta Google Cloud Platform

Após fazer login, certifique-se de que o projeto correto está selecionado.

Criar uma conta de serviço

Visite a página Criar conta de serviço e clique em Create Service Account.

Preencha os campos.

Dê a ela qualquer nome e ID de conta de serviço que você escolher.

Atribuir a função 'BigQuery User'

Dê à conta de serviço a função “BigQuery User”.

Criar uma chave JSON para esta conta

Vá para sua nova conta de serviço > Keys > Add Key > Create new key > selecione JSON. Salve o arquivo.

Você colará todo o conteúdo deste arquivo de chave JSON no OneSignal para ativar a integração.

2. Ativar a integração no OneSignal

Vá para OneSignal > Data > Integrations > BigQuery

Cole sua chave JSON da conta de serviço

Configurar definições

Sync Frequency: Com frequência de até a cada 15 minutos
Dataset/Table Names: Deve conter apenas letras minúsculas, números e sublinhados, e não pode começar com um número.
Event Types: Selecione eventos de mensagem específicos (por exemplo, enviado, aberto, clicado)
- Nota: Você pode selecionar vários tipos de eventos ou atualizar eventos selecionados posteriormente.

Clique em Save e aguarde a confirmação

A sincronização inicial de dados pode levar de 15 a 30 minutos para aparecer no BigQuery.Enquanto você espera, envie mensagens via push, email, in-app ou SMS para acionar os eventos selecionados.

3. Visualizar dados no BigQuery

Abra seu console BigQuery e localize o dataset (por exemplo, onesignal_events_<app-id>) para explorar eventos de mensagem sincronizados.

Dataset BigQuery contendo eventos de mensagem exportados

Eventos e propriedades de mensagem

Tipos de evento de mensagem

Propriedade: event_kind Tipo: String O tipo de mensagem e evento (por exemplo, message.push.received, message.push.sent).

Evento de Mensagem (OneSignal)	`event_kind`	Descrição
Push Sent	`message.push.sent`	Notificação push enviada com sucesso.
Push Received	`message.push.received`	Push entregue (veja Entrega Confirmada).
Push Clicked	`message.push.clicked`	Usuário clicou no push.
Push Failed	`message.push.failed`	Falha de entrega. Veja relatórios de mensagens.
Push Unsubscribed	`message.push.unsubscribed`	Usuário cancelou inscrição de push.
In-App Impression	`message.iam.impression`	Mensagem in-app mostrada.
In-App Clicked	`message.iam.clicked`	Mensagem in-app clicada.
In-App Page Viewed	`message.iam.page_displayed`	Página in-app mostrada.
Email Sent	`message.email.sent`	Email entregue.
Email Received	`message.email.received`	Email aceito pelo servidor de email do destinatário.
Email Opened	`message.email.opened`	Email aberto. Veja Relatórios de Email.
Email Link Clicked	`message.email.clicked`	Link no email clicado.
Email Unsubscribed	`message.email.unsubscribed`	Destinatário cancelou inscrição.
Email Reported As Spam	`message.email.reported_as_spam`	Marcado como spam. Veja Deliverability de Email.
Email Bounced	`message.email.bounced`	Bounce devido a falha permanente de entrega.
Email Failed	`message.email.failed`	Entrega falhou.
Email Suppressed	`message.email.suppressed`	Suprimido devido a lista de supressão.
SMS Sent	`message.sms.sent`	SMS enviado.
SMS Delivered	`message.sms.delivered`	SMS entregue com sucesso.
SMS Failed	`message.sms.failed`	SMS falhou ao entregar.
SMS Undelivered	`message.sms.undelivered`	SMS rejeitado ou inalcançável.

Schema de dados de evento

Para cada evento de mensagem gerado por um usuário, os seguintes metadados serão anexados ao registro.

Nome da Coluna	Tipo	Descrição
`event_id`	UUID	Identificador único para o evento
`event_timestamp`	Timestamp	Horário de ocorrência do evento
`event_kind`	String	O Tipo de Evento
`subscription_device_type`	String	Tipo de dispositivo (por exemplo, iOS, Android, Web, Email, SMS)
`language`	String	Código de idioma da inscrição
`version`	String	Versão da integração
`device_os`	String	Versão do sistema operacional do dispositivo
`device_type`	Number	Tipo de dispositivo numérico
`token`	String	Token push, número de telefone ou email
`subscription_id`	UUID	ID da inscrição
`subscribed`	Boolean	Status da inscrição
`onesignal_id`	UUID	ID de usuário OneSignal
`last_active`	String	Timestamp da última atividade
`sdk`	String	Versão do SDK OneSignal
`external_id`	String	ID de usuário externo que deve corresponder ao ID de usuário da integração
`app_id`	UUID	App ID do OneSignal
`template_id`	UUID	Template ID (se aplicável)
`message_id`	UUID	ID de lote/requisição de mensagem
`message_name`	String	Nome da mensagem
`message_title`	String	Título da mensagem (apenas em inglês)
`message_contents`	String	Corpo da mensagem truncado (apenas em inglês)
`failure_reason`	String	Motivo da falha (para eventos de falha de push e email)
`_created`, `_id`, `_index`, `_fivetran_synced`	Uso interno	Metadados de sincronização Fivetran

Notas

Sincronizações após salvar/ativar podem levar 15-30 minutos adicionais para completar.
Desativar ainda pode resultar em uma sincronização final após desativação.
Para garantir sincronização eficiente de dados, nosso sistema cria e gerencia automaticamente datasets de staging. Estes datasets, nomeados com um padrão como fivetran_{duas palavras aleatórias}_staging, armazenam temporariamente dados durante o processamento antes de serem integrados ao seu schema principal. Estes datasets de staging são essenciais para manter um fluxo de trabalho otimizado e não devem ser deletados, pois serão automaticamente recriados.

Importar eventos do BigQuery

Envie dados de eventos comportamentais do BigQuery para o OneSignal para:

Acionar Journeys com base na atividade do usuário
Personalizar mensagens com base em dados comportamentais

Requisitos

Acesso a Event Streams para eventos de mensagem de saída (Limitações de plano e excedentes se aplicam)
Acesso a Custom Events para sincronização de eventos de entrada (Limitações de plano e excedentes se aplicam)
Plano de Conta Atualizado (não disponível em apps gratuitos)

Projeto GCP com BigQuery e tabelas de dados de eventos
Conta de serviço com permissões de leitura
Tabelas de dados de eventos contendo dados comportamentais em datasets BigQuery

Etapas de configuração

Criar conta de serviço BigQuery

O OneSignal gerará uma conta de serviço automaticamente quando você criar a conexão. Alternativamente, você pode fornecer seu próprio arquivo JSON de chave de conta de serviço.Se estiver criando sua própria conta de serviço, certifique-se de que ela tenha as permissões necessárias listadas abaixo.

Conceder permissões necessárias

A conta de serviço do OneSignal precisa dessas funções IAM do BigQuery:

bigquery.dataViewer - Acesso de leitura a datasets e tabelas contendo dados de eventos
bigquery.jobUser - Permissão para criar jobs para consultas de dados
bigquery.metadataViewer - Acesso a metadados no nível do projeto (recomendado)

Conceda permissões usando o Console Google Cloud ou CLI:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
  --role roles/bigquery.dataViewer

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
  --role roles/bigquery.jobUser

Adicionar integração no OneSignal

No OneSignal, vá para Data > Integrations e clique em Add Integration.

Sync Engine: Sincronização avançada é recomendada para grandes datasets ou consultas complexas de dados de eventos. Você pode começar com sincronização básica e mudar para sincronização avançada mais tarde, se necessário.
Google Cloud Project ID: Seu projeto GCP contendo datasets BigQuery
Dataset Region: Localização onde seus datasets BigQuery estão armazenados
Service Account Key (opcional): Arquivo de chave JSON se estiver usando sua própria conta de serviço

Configurar fonte de dados de eventos

Especifique o dataset BigQuery e a tabela contendo seus dados de eventos:

Dataset: Nome do dataset BigQuery (por exemplo, analytics_events)
Table/View: Tabela ou visualização contendo registros de eventos
Event Query: Consulta SQL opcional para filtrar ou transformar dados de eventos

Sua tabela de eventos deve conter colunas para:

Nome/tipo do evento
Identificador do usuário
Timestamp do evento
Propriedades adicionais do evento

Testar a conexão

Clique em Test Connection para verificar se o OneSignal pode acessar seu projeto BigQuery e ler dados de eventos.

Mapeamento de dados de evento

Mapeie seu para o formato de eventos personalizados do OneSignal:

Campo OneSignal	Descrição	Obrigatório
`name`	`event_name`	Identificador de evento	Sim
`external_id`	`user_id`	Identificador de usuário	Sim
`timestamp`	`event_timestamp`	Quando o evento ocorreu	Não
`properties`	`event_data`	Não

A Sync Key é a coluna que você designa como o identificador exclusivo de cada linha durante a sincronização. O OneSignal a utiliza para detectar se uma linha já foi processada, de modo que ressincronizar seus dados não crie eventos duplicados. Escolha uma coluna com um valor de texto exclusivo por linha. Não use um booleano nem um valor que se repita entre as linhas.

Configuração avançada

Consultas SQL personalizadas

Use SQL personalizado para filtrar ou transformar dados de eventos antes de sincronizar com o OneSignal:

SELECT
  event_name,
  user_id,
  event_timestamp,
  STRUCT(
    product_id,
    purchase_amount,
    category
  ) as payload
FROM `project.dataset.events`
WHERE event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)

Acesso entre projetos

Se seus dados de eventos abrangem vários projetos BigQuery, conceda à conta de serviço do OneSignal acesso a cada projeto contendo tabelas ou visualizações referenciadas.

A região de conexão do seu BigQuery deve corresponder à região específica da tabela para desempenho ideal.

FAQ

Por que minha sincronização está falhando?

Existem algumas razões comuns pelas quais sua sincronização pode estar falhando:

A conta de serviço não tem as permissões necessárias
O dataset de origem é muito grande para uma sincronização básica e você precisa usar sincronização avançada

Revise as etapas de configuração acima e certifique-se de tê-las seguido corretamente. Se você ainda tiver problemas, entre em contato com support@onesignal.com.

Por que vejo vários IDs de mensagem para o mesmo conteúdo?

Isso normalmente ocorre quando um template de mensagem é reutilizado em vários envios ou fluxos acionados.

Com que frequência o OneSignal sincroniza dados?

Ambas as integrações de exportação e importação podem sincronizar com frequência de até a cada 15 minutos.

Posso usar visualizações BigQuery?

Sim. Apenas certifique-se de que a conta de serviço tenha acesso a todas as tabelas referenciadas na visualização.

Primeiros passos & configurações

Canais de mensagem

Jornadas

Público & eventos personalizados

Análises & Integrações

Privacidade & Segurança

Visão geral