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

# Databricks

> Exporte eventos de mensagem do OneSignal para o Databricks e importe eventos comportamentais do Databricks para o OneSignal para acionar Jornadas e personalizar mensagens.

export const DATA_TYPE_0 = "colunas da tabela de eventos"

export const PLATFORM_0 = "Databricks"

export const COLUMN_HEADER_0 = "Coluna Databricks"

export const PROPERTIES_DESCRIPTION_0 = "Colunas adicionais como JSON"

## Visão geral

A integração OneSignal + Databricks suporta **dois fluxos**:

* **Exportar**: Envie eventos de mensagem do OneSignal para o Databricks para analytics e relatórios.
* **Importar**: Envie eventos personalizados do Databricks para o OneSignal para acionar Jornadas e personalizar campanhas.

<Info> Exportar e importar são configurados separadamente. Você pode configurar um sem o outro. </Info>

***

## Exportar eventos de mensagem do OneSignal para o Databricks

Sincronize todos os seus eventos de mensagem do OneSignal no seu lakehouse Databricks para analytics e visibilidade em tempo quase real.

**Requisitos**

* [Plano Professional ou superior](https://onesignal.com/pricing)
* Custom Events habilitados (para importações de eventos)
* Plataforma Databricks: AWS, Azure ou GCP
* Plano Databricks: Premium ou superior
* Databricks Unity Catalog (recomendado para governança)
* Databricks SQL Warehouse para consultas
* Tabelas de eventos Delta Lake (para importação de eventos personalizados)

**Etapas de configuração**

### 1. Coletar detalhes do SQL warehouse

<Steps>
  <Step title="Faça login no seu workspace Databricks">
    Vá para **SQL Warehouses** no seu workspace Databricks.
  </Step>

  <Step title="Selecione seu warehouse">
    Selecione seu warehouse e abra a aba **Connection details**.
  </Step>

  <Step title="Salve os seguintes detalhes">
    * Server Hostname
    * Port
    * HTTP Path

    <Frame caption="Detalhes de conexão SQL do Databricks para configuração do Fivetran">
      <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1ce7c549df4a383336633d9f258bec12107a895dc9467134d672c12c2c85923f-cluster-databricks.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=1f03dbaa1a6cc6c4bdf804e49755cbf7" alt="Databricks SQL connection details for Fivetran setup" width="1810" height="988" data-path="images/docs/1ce7c549df4a383336633d9f258bec12107a895dc9467134d672c12c2c85923f-cluster-databricks.png" />
    </Frame>
  </Step>
</Steps>

### 2. Criar um service principal

<Steps>
  <Step title="Vá para a página Service Principals">
    Vá para **Workspace Settings > Identity and Access > Service Principals**.
  </Step>

  <Step title="Adicionar um novo service principal">
    Clique em **Add Service Principal**, depois em **Add New**.
  </Step>

  <Step title="Nomeie o service principal">
    Nomeie-o (por exemplo, `onesignal-sync`).

    <Frame caption="Modal para adicionar um service principal, com a opção 'Add new' destacada">
      <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b8eeb211ceb77247f711eb312d3d68d1cb0da10788fd81fd37ae27e929e35cde-Screenshot_2025-04-01_at_9.16.12_PM.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=3bda750f12db717d630220bed24cdb2e" alt="Modal for adding a service principal, with the 'Add new' option highlighted" width="932" height="392" data-path="images/docs/b8eeb211ceb77247f711eb312d3d68d1cb0da10788fd81fd37ae27e929e35cde-Screenshot_2025-04-01_at_9.16.12_PM.png" />
    </Frame>
  </Step>
</Steps>

### 3. Gerar um segredo

<Steps>
  <Step title="Clique no principal criado" />

  <Step title="Vá para a aba Secrets" />

  <Step title="Gere um segredo">
    Clique em **Generate Secret** e salve-o com segurança.

    <Warning>
      O segredo é visível apenas uma vez—armazene-o com segurança.
    </Warning>

    <Frame caption="Modal 'Generate secret' do Databricks mostrando OAuth secret e client ID para autenticação de API">
      <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/ff24d4d5bf9b21e0cadf67055f1e1a5a4b517b82e9c006520a02b4fd404d259e-Screenshot_2025-03-28_at_4.14.17_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=54eaae1d695bfad59b726ba005ff6f1f" alt="Databricks 'Generate secret' modal showing OAuth secret and client ID for API authentication" width="746" height="368" data-path="images/docs/ff24d4d5bf9b21e0cadf67055f1e1a5a4b517b82e9c006520a02b4fd404d259e-Screenshot_2025-03-28_at_4.14.17_PM.png" />
    </Frame>
  </Step>
</Steps>

### 4. Atribuir permissões

<Steps>
  <Step title="Navegue até seu Catalog e abra a aba Permissions" />

  <Step title="Clique em Grant" />

  <Step title="Atribua as seguintes permissões ao service principal">
    * USE CATALOG
    * USE SCHEMA
    * SELECT
    * MODIFY
    * CREATE SCHEMA
    * CREATE TABLE

    <Frame caption="Tela de atribuição de privilégios para um principal do Databricks com permissões de catálogo personalizadas selecionadas.">
      <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5755c8739fd66a0f35fec57b817d54d202c64ae95bf8219645ba76abdc8fbe0b-Screenshot_2025-04-01_at_9.19.14_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=0964053615467ebd7372edd7beaf33fe" alt="Privilege assignment screen for a Databricks principal with custom catalog permissions selected" width="1034" height="812" data-path="images/docs/5755c8739fd66a0f35fec57b817d54d202c64ae95bf8219645ba76abdc8fbe0b-Screenshot_2025-04-01_at_9.19.14_PM.png" />
    </Frame>
  </Step>
</Steps>

### 5. Conectar o OneSignal

<Steps>
  <Step title="Ativar a integração">
    No OneSignal, navegue até **Data > Integrations > Databricks**.
  </Step>

  <Step title="Insira os detalhes">
    * Server Hostname
    * Port
    * HTTP Path
    * Catalog Name
    * Schema Name
    * Credenciais do Service Principal (ID + Secret)

    <Frame caption="Formulário de configuração do Databricks do OneSignal com campos para catalog, hostname, HTTP path e credenciais OAuth.">
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/816a07ed459d3d19910630da0cb52b2075c06d6eaf85af98e969703edab88ad5-Screenshot_2025-03-28_at_4.12.07_PM.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=cd7ba1d76deff9922dc44b25a7528eb2" alt="OneSignal Databricks Configuration form with fields for catalog, hostname, HTTP path, and OAuth credentials" width="718" height="796" data-path="images/docs/816a07ed459d3d19910630da0cb52b2075c06d6eaf85af98e969703edab88ad5-Screenshot_2025-03-28_at_4.12.07_PM.png" />
    </Frame>
  </Step>

  <Step title="Configure a integração">
    * **Sync Frequency:** tão frequentemente quanto a cada 15 minutos
    * **Dataset/Table Names:** pré-definidos como `onesignal_events_<app-id>` e `message_events` (editável)
    * **Event Types:** escolha quais sincronizar—selecione todos ou apenas o que você precisa
  </Step>

  <Step title="Selecione eventos">
    Selecione os eventos que você deseja receber no seu catálogo Databricks.

    <Frame caption="Tela de configurações de exportação de eventos do OneSignal mostrando status de sincronização, configuração de dataset e tipos de eventos de mensagem selecionados.">
      <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1a5ff2af7dc8fc42a91ce70583a03b361fd8a343bc57fd3123f26a5d21dabbf8-Screenshot_2025-04-09_at_11.56.58_AM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=ce7eee0983e2026b1847a4d2a45cbe96" alt="OneSignal event export settings screen showing sync status, dataset configuration, and selected message event types" width="2738" height="1254" data-path="images/docs/1a5ff2af7dc8fc42a91ce70583a03b361fd8a343bc57fd3123f26a5d21dabbf8-Screenshot_2025-04-09_at_11.56.58_AM.png" />
    </Frame>
  </Step>

  <Step title="Complete a configuração">
    Clique em **Save** e aguarde a confirmação de sucesso
  </Step>
</Steps>

<Note>
  A sincronização inicial de dados pode levar 15–30 minutos para aparecer no BigQuery.

  Enquanto espera, envie mensagens via push, email, in-app ou SMS para acionar os eventos selecionados.
</Note>

### 6. Visualizar dados no Databricks

1. Abra seu **Catalog** no Databricks.

2. Assim que a sincronização for concluída, seu esquema configurado aparecerá.

3. Acesse e consulte a tabela `message_events`.

   <Frame caption="Visualização do Catalog do Databricks mostrando tabela de eventos de mensagem do OneSignal sob um esquema de produção.">
     <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1b59f6eff2070490f194df8a7496fab6cf17f8fc9355cfb7b77c7c076799632e-Screenshot_2025-04-01_at_9.22.01_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=c5908557481f292b1a659b4f0ef210ed" alt="Databricks Catalog view showing OneSignal message events table under a production schema" width="854" height="618" data-path="images/docs/1b59f6eff2070490f194df8a7496fab6cf17f8fc9355cfb7b77c7c076799632e-Screenshot_2025-04-01_at_9.22.01_PM.png" />
   </Frame>

4. Clique em tabelas para pré-visualização de dados de amostra.

   <Frame caption="Dados de amostra da tabela message_events_1 com campos de evento do OneSignal sincronizados.">
     <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/112f17e471b8e29173429bfbbd4b34fb68923c9f76faa55b06161114249fcaab-Screenshot_2025-04-01_at_9.22.08_PM.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=a853fe144d238a24d86b5f989261f2be" alt="Sample data from the message_events_1 table with synced OneSignal event fields" width="1196" height="374" data-path="images/docs/112f17e471b8e29173429bfbbd4b34fb68923c9f76faa55b06161114249fcaab-Screenshot_2025-04-01_at_9.22.08_PM.png" />
   </Frame>

<Info>
  Se você encontrar problemas como esquemas ausentes, erros de permissão ou eventos malformados, entre em contato com `support@onesignal.com`.
</Info>

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

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

* Acionar Jornadas 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)

- **Workspace Databricks** com SQL Warehouse ou cluster de computação
- **Personal Access Token** com permissões apropriadas
- **Tabelas de dados de eventos** contendo dados comportamentais em formato Delta Lake
- **Unity Catalog** (recomendado para governança de dados)

**Etapas de configuração**

<Steps>
  <Step title="Criar Databricks Personal Access Token">
    Gere um Personal Access Token para o OneSignal acessar seu workspace Databricks:

    1. Navegue até **User Settings** no seu workspace Databricks
    2. Clique na aba **Developer** e depois em **Access tokens**
    3. Clique em **Generate new token**
    4. Insira um comentário como "OneSignal Integration" e defina a expiração (recomendamos 90 dias)
    5. Salve o token gerado (você precisará disso para o OneSignal)
  </Step>

  <Step title="Configurar acesso ao SQL Warehouse">
    Certifique-se de que o OneSignal possa consultar seus dados de eventos via SQL Warehouse:

    1. Navegue até **SQL Warehouses** no seu workspace Databricks
    2. Selecione ou crie um SQL Warehouse para acesso do OneSignal
    3. Anote o **Server Hostname** e **HTTP Path** dos detalhes de conexão
    4. Certifique-se de que o warehouse tenha acesso às suas tabelas de dados de eventos
  </Step>

  <Step title="Conceder permissões de tabela">
    Conceda ao OneSignal acesso de leitura às tabelas contendo dados de eventos:

    ```sql theme={null}
    -- Para workspaces com Unity Catalog habilitado
    GRANT SELECT ON TABLE catalog.schema.event_table TO `onesignal@yourdomain.com`;

    -- Para tabelas Hive metastore
    GRANT SELECT ON TABLE database.event_table TO `onesignal@yourdomain.com`;
    ```
  </Step>

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

    Selecione **Databricks** e forneça:

    * **Server Hostname**: Nome do host do SQL Warehouse do Databricks
    * **HTTP Path**: Caminho HTTP do SQL Warehouse
    * **Personal Access Token**: Token criado na etapa 1
    * **Catalog** (opcional): Nome do Unity Catalog se estiver usando Unity Catalog
  </Step>

  <Step title="Configurar fonte de dados de eventos">
    Especifique a tabela Databricks contendo seus dados de eventos:

    * **Database/Schema**: Nome do banco de dados ou esquema contendo tabelas de eventos
    * **Table**: Nome da tabela com registros de eventos (por exemplo, `user_events`)
    * **Event Query**: Consulta SQL opcional para filtrar ou transformar dados de eventos

    Sua tabela de eventos deve conter colunas para:

    * Nome/tipo do evento (String)
    * Identificador do usuário (String)
    * Timestamp do evento (Timestamp)
    * Propriedades adicionais do evento
  </Step>

  <Step title="Testar a conexão">
    Clique em **Test Connection** para verificar se o OneSignal pode acessar seu workspace Databricks 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

#### Integração Unity Catalog

Aproveite o Unity Catalog para acesso governado a dados:

```sql theme={null}
SELECT
  event_name,
  user_id,
  event_timestamp,
  to_json(
    named_struct(
      'product_id', product_id,
      'purchase_amount', purchase_amount,
      'category', category
    )
  ) as payload
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp() - INTERVAL 7 DAYS
```

### Otimização Delta Lake

Otimize tabelas de eventos para melhor performance de consulta:

* **Particionamento**: Particione por data (`event_date`) para consultas baseadas em tempo mais rápidas
* **Z-Ordering**: Z-order por `user_id` e `event_name` para melhor filtragem
* **Recursos Delta Lake**: Use liquid clustering para otimização automática

#### Processamento de eventos streaming

Para processamento de eventos em tempo real, considere:

* **Structured Streaming**: Processe eventos conforme eles chegam
* **Delta Live Tables**: Construa pipelines robustos de processamento de eventos
* **Auto Loader**: Ingira continuamente novos arquivos de eventos

<Warning>
  Certifique-se de que seu SQL Warehouse tenha recursos de computação suficientes para lidar com as consultas do OneSignal sem afetar outras cargas de trabalho.
</Warning>

***

## FAQ

### Por que vejo IDs de mensagem diferentes com o mesmo conteúdo?

Isso acontece quando a mesma mensagem é enviada mais de uma vez, provavelmente através de um fluxo transacional ou template de mensagem reutilizado em vários envios.

### Com que frequência o OneSignal sincroniza eventos do Databricks?

O OneSignal sincroniza dados de eventos com base no seu cronograma configurado, com um intervalo mínimo de 15 minutos.

### Posso usar notebooks do Databricks para processamento de eventos?

Sim, você pode usar notebooks para processar e preparar dados de eventos, depois expô-los via tabelas que o OneSignal pode consultar.

### E quanto à otimização de custos para consultas de eventos?

Considere usar SQL Warehouses sem servidor para computação econômica e sob demanda que escala automaticamente com base na carga de consulta.

***