> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google BigQuery

> Exporte dados de eventos de mensagens para o BigQuery e importe eventos personalizados do BigQuery para acionar campanhas personalizadas.

export const DATA_TYPE_0 = "event table columns"

export const PLATFORM_0 = "BigQuery"

export const COLUMN_HEADER_0 = "BigQuery Column"

export const PROPERTIES_DESCRIPTION_0 = "Additional columns as JSON"

## 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](/docs/pt-BR/event-streams) para eventos de mensagem de saída (Limitações de plano e excedentes se aplicam)
* Acesso a [Custom Events](/docs/pt-BR/custom-events) para sincronização de eventos de entrada (Limitações de plano e excedentes se aplicam)
* [Plano de Conta Atualizado](https://onesignal.com/pricing) (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

<Steps>
  <Step title="Faça login na sua conta Google Cloud Platform">
    Após fazer login, certifique-se de que o projeto correto está selecionado.

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="Criar uma conta de serviço">
    Visite a [página Criar conta de serviço](https://console.cloud.google.com/iam-admin/serviceaccounts/create) e clique em **Create Service Account.**

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="Preencha os campos.">
    Dê a ela qualquer nome e ID de conta de serviço que você escolher.

    <Frame>
      <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=37236688a79f1c16c0d6fdad15b03245" width="1344" height="870" data-path="images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png" />
    </Frame>
  </Step>

  <Step title="Atribuir a função 'BigQuery User'">
    Dê à conta de serviço a função "BigQuery User".

    <Frame>
      <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=1df75028d3632a3ed413c10c1de9b94a" width="549" height="395" data-path="images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png" />
    </Frame>
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

### 2. Ativar a integração no OneSignal

<Steps>
  <Step title="Vá para OneSignal > Data > Integrations > BigQuery" />

  <Step title="Cole sua chave JSON da conta de serviço" />

  <Step title="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.
  </Step>

  <Step title="Clique em Save e aguarde a confirmação" />
</Steps>

<Note>
  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.
</Note>

### 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.

<Frame caption="Dataset BigQuery contendo eventos de mensagem exportados">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=08cf57a8bd91f9447909ad619077935f" width="1552" height="1052" data-path="images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png" />
</Frame>

## 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](/docs/pt-BR/confirmed-delivery)).           |
|          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](/docs/pt-BR/email-message-reports).         |
|       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](/docs/pt-BR/email-deliverability). |
|          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](#tipos-de-evento-de-mensagem)                           |
|            `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](/docs/pt-BR/event-streams) para eventos de mensagem de saída (Limitações de plano e excedentes se aplicam)
* Acesso a [Custom Events](/docs/pt-BR/custom-events) para sincronização de eventos de entrada (Limitações de plano e excedentes se aplicam)
* [Plano de Conta Atualizado](https://onesignal.com/pricing) (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**

<Steps>
  <Step title="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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Adicionar integração no OneSignal">
    No OneSignal, vá para **Data > Integrations** e clique em **Add Integration**.

    <Frame caption="Adicionar integração BigQuery">
      <img src="https://mintcdn.com/onesignal/IHzVtEbivOs2EktQ/images/integrations/bigquery-add-integration.png?fit=max&auto=format&n=IHzVtEbivOs2EktQ&q=85&s=6877dc14cfe8f9c1677404353927e4f8" width="1944" height="1764" data-path="images/integrations/bigquery-add-integration.png" />
    </Frame>

    * **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
  </Step>

  <Step title="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
  </Step>

  <Step title="Testar a conexão">
    Clique em **Test Connection** para verificar se o OneSignal pode acessar seu projeto BigQuery e ler dados de eventos.
  </Step>
</Steps>

***

### Mapeamento de dados de evento

Mapeie seu {DATA_TYPE_0} {PLATFORM_0} para o formato de eventos personalizados do OneSignal:

| Campo OneSignal | {COLUMN_HEADER_0} | 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`      | {PROPERTIES_DESCRIPTION_0} | Não         |

### Configuração avançada

#### Consultas SQL personalizadas

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

```sql theme={null}
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.

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

***

## 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.

***

## Recursos relacionados

* [Criando chaves de conta de serviço no GCP](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating)
* [Documentação de Journeys do OneSignal](./journeys-overview)
* [Documentação de exportação de dados do OneSignal](./exporting-data)

***