Databricks

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.

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

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

Faça login no seu workspace Databricks

Vá para SQL Warehouses no seu workspace Databricks.

Selecione seu warehouse

Selecione seu warehouse e abra a aba Connection details.

Salve os seguintes detalhes

Server Hostname
Port
HTTP Path

Databricks SQL connection details for Fivetran setup — Detalhes de conexão SQL do Databricks para configuração do Fivetran

2. Criar um service principal

Vá para a página Service Principals

Vá para Workspace Settings > Identity and Access > Service Principals.

Adicionar um novo service principal

Clique em Add Service Principal, depois em Add New.

Nomeie o service principal

Nomeie-o (por exemplo, onesignal-sync).

Modal for adding a service principal, with the 'Add new' option highlighted — Modal para adicionar um service principal, com a opção 'Add new' destacada

3. Gerar um segredo

Clique no principal criado

Vá para a aba Secrets

Gere um segredo

Clique em Generate Secret e salve-o com segurança.

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

Databricks 'Generate secret' modal showing OAuth secret and client ID for API authentication — Modal 'Generate secret' do Databricks mostrando OAuth secret e client ID para autenticação de API

4. Atribuir permissões

Navegue até seu Catalog e abra a aba Permissions

Clique em Grant

Atribua as seguintes permissões ao service principal

USE CATALOG
USE SCHEMA
SELECT
MODIFY
CREATE SCHEMA
CREATE TABLE

Privilege assignment screen for a Databricks principal with custom catalog permissions selected — Tela de atribuição de privilégios para um principal do Databricks com permissões de catálogo personalizadas selecionadas.

5. Conectar o OneSignal

Ativar a integração

No OneSignal, navegue até Data > Integrations > Databricks.

Insira os detalhes

Server Hostname
Port
HTTP Path
Catalog Name
Schema Name
Credenciais do Service Principal (ID + Secret)

OneSignal Databricks Configuration form with fields for catalog, hostname, HTTP path, and OAuth credentials — Formulário de configuração do Databricks do OneSignal com campos para catalog, hostname, HTTP path e credenciais OAuth.

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

Selecione eventos

Selecione os eventos que você deseja receber no seu catálogo Databricks.

OneSignal event export settings screen showing sync status, dataset configuration, and selected message event types — 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.

Complete a configuração

Clique em Save e aguarde a confirmação de sucesso

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.

6. Visualizar dados no Databricks

Abra seu Catalog no Databricks.
Assim que a sincronização for concluída, seu esquema configurado aparecerá.
Acesse e consulte a tabela message_events.
Visualização do Catalog do Databricks mostrando tabela de eventos de mensagem do OneSignal sob um esquema de produção.
Clique em tabelas para pré-visualização de dados de amostra.
Dados de amostra da tabela message_events_1 com campos de evento do OneSignal sincronizados.

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

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 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 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)

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

Criar Databricks Personal Access Token

Gere um Personal Access Token para o OneSignal acessar seu workspace Databricks:

Navegue até User Settings no seu workspace Databricks
Clique na aba Developer e depois em Access tokens
Clique em Generate new token
Insira um comentário como “OneSignal Integration” e defina a expiração (recomendamos 90 dias)
Salve o token gerado (você precisará disso para o OneSignal)

Configurar acesso ao SQL Warehouse

Certifique-se de que o OneSignal possa consultar seus dados de eventos via SQL Warehouse:

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

Conceder permissões de tabela

Conceda ao OneSignal acesso de leitura às tabelas contendo dados de eventos:

-- 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`;

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

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

Testar a conexão

Clique em Test Connection para verificar se o OneSignal pode acessar seu workspace Databricks 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

Configuração avançada

Integração Unity Catalog

Aproveite o Unity Catalog para acesso governado a dados:

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

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.

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.

Primeiros passos & configurações

Canais de mensagem

Jornadas

Público & eventos personalizados

Análises & Integrações

Privacidade & Segurança

Visão geral