> ## 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.
# Snowflake
> Sincronize eventos personalizados do Snowflake para o OneSignal para acionar Jornadas automatizadas e campanhas de mensagens personalizadas com base no comportamento do usuário.
export const DATA_TYPE_0 = "dados de eventos"
export const PLATFORM_0 = "Snowflake"
export const COLUMN_HEADER_0 = "Coluna Snowflake"
export const PROPERTIES_DESCRIPTION_0 = "Metadados de eventos como VARIANT/JSON"
Se você estiver usando o Snowflake com a integração legada do OneSignal, consulte o guia [Integração Legada do Snowflake](./snowflake-legacy). Veja [Migração do legado](#migrating-from-legacy) para etapas de migração.
***
## Visão geral
A integração OneSignal + Snowflake suporta dois pipelines de dados poderosos:
* **Saída**: Envie automaticamente dados de eventos de mensagens (push, e-mail, SMS, in-app) do OneSignal para o Snowflake para análise e relatórios.
* **Entrada**: Sincronize eventos personalizados de usuários dos seus conjuntos de dados do Snowflake para o OneSignal para acionar Jornadas automatizadas e mensagens personalizadas.
Juntas, essas integrações oferecem controle completo sobre os dados de engajamento do usuário—alimentando análises avançadas e mensagens em tempo real baseadas em comportamento.
***
## Configuração de saída
Isto está atualmente em acesso antecipado.
Para solicitar acesso, entre em contato com `support@onesignal.com` com:
* Nome da sua empresa
* ID da sua organização OneSignal
* O(s) ID(s) do app que você deseja habilitar
Exporte eventos de desempenho e engajamento de mensagens (por exemplo, envios, aberturas, cliques) para o Snowflake para:
* Criar dashboards e relatórios personalizados
* Rastrear tendências de entrega e engajamento em todos os canais
* Combinar dados do OneSignal com outros dados de negócios para análise
**Requisitos**
* OneSignal **Plano Professional** (não disponível em aplicativos gratuitos)
* [Conta Snowflake](https://docs.snowflake.com/en/user-guide/getting-started-tutorial)
* Função SECURITYADMIN ou ACCOUNTADMIN no Snowflake (para configuração)
### 1. Reúna os detalhes da sua conta Snowflake
Antes de configurar a integração, colete as seguintes informações da sua conta Snowflake:
* **Snowflake Host**: A URL da sua conta no formato `.snowflakecomputing.com`
* **Nome do banco de dados**: O banco de dados onde o OneSignal gravará os dados de eventos
* **Nome do schema**: O schema dentro do banco de dados para as tabelas do OneSignal (será criado automaticamente pelo OneSignal)
* **Nome do warehouse**: O warehouse a ser usado para operações de carregamento de dados
### 2. Execute o script de configuração no Snowflake
Execute o seguinte script SQL no seu warehouse Snowflake para criar a função, o usuário, o warehouse e o banco de dados necessários para o OneSignal:
```sql theme={null}
begin;
-- create variables for user / role / warehouse / database (needs to be uppercase for objects)
set role_name = 'ONESIGNAL_ROLE';
set user_name = 'ONESIGNAL_USER';
set warehouse_name = 'ONESIGNAL_WAREHOUSE';
set database_name = 'ONESIGNAL';
-- change role to securityadmin for user / role steps
use role securityadmin;
-- create role for onesignal
create role if not exists identifier($role_name);
grant role identifier($role_name) to role SYSADMIN;
-- create a user for onesignal
create user if not exists identifier($user_name)
default_role = $role_name
default_warehouse = $warehouse_name;
grant role identifier($role_name) to user identifier($user_name);
-- set binary_input_format to BASE64
ALTER USER identifier($user_name) SET BINARY_INPUT_FORMAT = 'BASE64';
-- set timestamp_input_format to AUTO for the user
ALTER USER identifier($user_name) SET TIMESTAMP_INPUT_FORMAT = 'AUTO';
-- change role to sysadmin for warehouse / database steps
use role sysadmin;
-- create a warehouse for onesignal
create warehouse if not exists identifier($warehouse_name)
warehouse_size = xsmall
warehouse_type = standard
auto_suspend = 60
auto_resume = true
initially_suspended = true;
-- create database for onesignal
create database if not exists identifier($database_name);
-- grant onesignal role access to warehouse
grant USAGE
on warehouse identifier($warehouse_name)
to role identifier($role_name);
-- grant onesignal access to database
grant CREATE SCHEMA, MONITOR, USAGE
on database identifier($database_name)
to role identifier($role_name);
commit;
```
Você pode personalizar os valores das variáveis no topo do script para corresponder às suas convenções de nomenclatura. Se você estiver usando um warehouse ou banco de dados existente, modifique o script de acordo.
### 3. Gere o par de chaves para autenticação
O OneSignal requer autenticação por par de chaves para acesso seguro à sua conta Snowflake. Siga estas etapas para gerar e configurar as chaves:
Execute um dos seguintes comandos para gerar uma chave privada:
**Chave privada não criptografada** (mais simples, mas menos segura):
```bash theme={null}
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```
**Chave privada criptografada** (recomendado para produção):
```bash theme={null}
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes256 -inform PEM -out rsa_key.p8
```
Se usar uma chave criptografada, você será solicitado a criar uma frase secreta. Salve esta frase secreta com segurança—você precisará dela ao configurar o OneSignal.
Gere a chave pública a partir da sua chave privada:
```bash theme={null}
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```
Copie o conteúdo do arquivo de chave pública (excluindo as linhas de cabeçalho e rodapé) e execute este comando SQL no Snowflake:
```sql theme={null}
ALTER USER ONESIGNAL_USER SET RSA_PUBLIC_KEY='';
```
Substitua `` pelo conteúdo da chave (sem as linhas `-----BEGIN PUBLIC KEY-----` e `-----END PUBLIC KEY-----`).
Armazene seu arquivo de chave privada com segurança. Você precisará fornecê-lo ao OneSignal na próxima etapa. Nunca compartilhe sua chave privada publicamente ou a envie para controle de versão.
### 4. Conecte o OneSignal
No OneSignal, navegue até **Data > Integrations > Snowflake**.
* Host: `.snowflakecomputing.com`
* Port: Opcional, padrão é `443`
* Database: por exemplo, `ONESIGNAL`
* Role: Opcional, usa a função padrão do usuário se omitida
* User: por exemplo, `ONESIGNAL_USER`
* Private Key: Cole o conteúdo do seu arquivo de chave privada (`rsa_key.p8`)
* Private Key Passphrase: Opcional, somente se sua chave privada estiver criptografada
* Data processing location: Onde os dados são processados antes de enviá-los para o Snowflake
* **Sync Frequency:** com frequência de até a cada 15 minutos
* **Schema/Table Names:** pré-definidos como `onesignal_events_` e `message_events` (editável)
* **Event Types:** escolha quais sincronizar—selecione todos ou apenas o que você precisa
Selecione os eventos que você deseja receber no seu warehouse Snowflake.
Clique em **Save** e aguarde a confirmação de sucesso
A sincronização inicial de dados pode levar de 15 a 30 minutos para aparecer no Snowflake.
Enquanto espera, envie mensagens por push, e-mail, in-app ou SMS para acionar os eventos selecionados.
### 5. Visualize dados no Snowflake
Depois que a sincronização inicial for concluída, consulte seus dados de eventos do OneSignal:
```sql theme={null}
-- View recent message events
SELECT *
FROM ..message_events
ORDER BY _CREATED DESC
LIMIT 100;
```
Se você encontrar problemas como schemas 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](/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.
***
## Migração do legado
Se você está usando atualmente a [integração legada do Snowflake](./snowflake-legacy), esta seção aborda as principais diferenças e como migrar suas consultas.
### Principais diferenças
| Recurso | Legado | Novo |
| ------------------------------- | --------------------------------------------- | ------------------------------------------ |
| **Frequência de sincronização** | 24 horas | Até a cada 15 minutos |
| **Propriedade dos dados** | Acesso somente leitura a dados compartilhados | Gravado diretamente na sua conta Snowflake |
| **Retenção de dados** | 30 dias | Você controla a retenção |
| **Seleção de eventos** | Todos os eventos | Escolha tipos de eventos específicos |
### Alterações no schema
A nova integração cria colunas sob demanda. Se nenhum evento contém dados para um campo específico, essa coluna não existirá na sua tabela. Quando dados aparecem para esse campo, a coluna é criada automaticamente.
#### Renomeações de colunas
| Coluna legada | Nova coluna |
| ---------------------------- | ------------------ |
| `EVENT_IMPRESSION_TIMESTAMP` | `EVENT_TIMESTAMP` |
| `SUBSCRIPTION_LANGUAGE` | `LANGUAGE` |
| `MESSAGE_BODY` | `MESSAGE_CONTENTS` |
### Inferência de tipos
A nova integração usa inferência automática de tipos. Se todos os valores em uma coluna são numéricos (por exemplo, todos os seus valores `EXTERNAL_ID` são números), a coluna pode ser tipada como `NUMBER`. Se um valor não numérico aparecer depois, o tipo da coluna é promovido para `VARCHAR`.
Use conversão explícita se necessário:
```sql theme={null}
WHERE EXTERNAL_ID = '12345'::VARCHAR
```
### Migração de consultas
Para migrar consultas existentes:
1. Atualize referências ao banco de dados legado para apontar para seu novo banco de dados Snowflake
2. Considere as renomeações de colunas listadas acima
3. Adicione conversão explícita de tipos onde necessário
Opcionalmente, crie uma view de compatibilidade que cria aliases dos novos nomes de colunas para nomes legados:
```sql theme={null}
CREATE VIEW your_schema.message_events_compat AS
SELECT
*,
EVENT_TIMESTAMP AS EVENT_IMPRESSION_TIMESTAMP,
LANGUAGE AS SUBSCRIPTION_LANGUAGE,
MESSAGE_CONTENTS AS MESSAGE_BODY
FROM ONESIGNAL_DB.ONESIGNAL_EVENTS_XXXXX.MESSAGE_EVENTS;
```
Substitua `ONESIGNAL_DB.ONESIGNAL_EVENTS_XXXXX.MESSAGE_EVENTS` pelos nomes reais do seu banco de dados, schema e tabela.
Para desconectar seu compartilhamento de dados legado, entre em contato com [snowflake-data-sharing@onesignal.com](mailto:snowflake-data-sharing@onesignal.com).
***
## Configuração de entrada
Importe dados de eventos comportamentais do Snowflake 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)
- **Conta Snowflake** com acesso ao warehouse
- **Dados de eventos** armazenados em tabelas ou visualizações do Snowflake
- **Conectividade de rede** do OneSignal para sua instância Snowflake
- **Credenciais de usuário** com permissões apropriadas
Crie uma hierarquia de funções seguindo as melhores práticas do Snowflake:
```sql theme={null}
-- Create a role for the census user
CREATE ROLE CENSUS_ROLE;
-- Ensure the sysadmin role inherits any privileges the census role is granted
GRANT ROLE CENSUS_ROLE TO ROLE SYSADMIN;
```
Crie um warehouse com custo otimizado para operações do OneSignal:
```sql theme={null}
-- Create a warehouse for the census role, optimizing for cost over performance
CREATE WAREHOUSE CENSUS_WAREHOUSE WITH
WAREHOUSE_SIZE = XSMALL
AUTO_SUSPEND = 60
AUTO_RESUME = TRUE
INITIALLY_SUSPENDED = FALSE;
GRANT USAGE ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
GRANT OPERATE ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
GRANT MONITOR ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
```
Crie o usuário do OneSignal e conceda acesso aos seus dados de eventos:
```sql theme={null}
-- Create the census user
CREATE USER CENSUS WITH
DEFAULT_ROLE = CENSUS_ROLE
DEFAULT_WAREHOUSE = CENSUS_WAREHOUSE
PASSWORD = '';
GRANT ROLE CENSUS_ROLE TO USER CENSUS;
-- Grant access to your event data (replace with your actual database/schema)
GRANT USAGE ON DATABASE "" TO ROLE CENSUS_ROLE;
GRANT USAGE ON SCHEMA ""."" TO ROLE CENSUS_ROLE;
GRANT SELECT ON ALL TABLES IN SCHEMA ""."" TO ROLE CENSUS_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA ""."" TO ROLE CENSUS_ROLE;
GRANT SELECT ON ALL VIEWS IN SCHEMA ""."" TO ROLE CENSUS_ROLE;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA ""."" TO ROLE CENSUS_ROLE;
```
Crie um banco de dados privado para gerenciamento de estado de sincronização do OneSignal:
```sql theme={null}
-- Create a private bookkeeping database
CREATE DATABASE "CENSUS";
GRANT ALL PRIVILEGES ON DATABASE "CENSUS" TO ROLE CENSUS_ROLE;
CREATE SCHEMA "CENSUS"."CENSUS";
GRANT ALL PRIVILEGES ON SCHEMA "CENSUS"."CENSUS" TO ROLE CENSUS_ROLE;
GRANT CREATE STAGE ON SCHEMA "CENSUS"."CENSUS" TO ROLE CENSUS_ROLE;
```
Pule esta etapa se estiver usando o Basic Sync Engine ou modo somente leitura.
Configure a autenticação por par de chaves (recomendado) para maior segurança:
1. Gere um par de chaves pública/privada seguindo a [documentação do Snowflake](https://docs.snowflake.com/en/user-guide/key-pair-auth)
2. Configure a chave pública no seu usuário Snowflake
3. Use a chave privada nas configurações de conexão do OneSignal
Como alternativa, você pode usar autenticação por senha (obsoleto - será bloqueado em novembro de 2025).
No OneSignal, vá para **Data > Integrations** e clique em **Add Integration**.
Selecione **Snowflake** e forneça os seguintes detalhes de conexão:
* **Account Name:** Seu identificador de conta Snowflake (por exemplo, `abc123.us-east-1`)
* **Warehouse:** `CENSUS_WAREHOUSE`
* **User:** `CENSUS`
* **Database:** Nome do banco de dados dos seus dados de eventos
* **Schema:** Nome do schema dos seus dados de eventos
* **Authentication:** Key-pair (forneça a chave privada e frase secreta opcional)
***
### 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 |
#### Esquema de tabela de eventos de exemplo
```sql theme={null}
-- Example Snowflake event table
CREATE TABLE analytics.user_events (
event_id STRING,
event_name STRING NOT NULL,
user_id STRING NOT NULL,
event_timestamp TIMESTAMP_TZ DEFAULT CURRENT_TIMESTAMP(),
event_properties VARIANT,
session_id STRING,
device_type STRING
);
```
#### Modo de consulta SQL
Escreva consultas SQL personalizadas para transformar seus dados de eventos:
```sql theme={null}
-- Example: Recent high-value events
SELECT
event_name,
user_id,
event_timestamp,
event_properties
FROM analytics.user_events
WHERE event_timestamp >= DATEADD(day, -7, CURRENT_TIMESTAMP())
AND event_properties:value::NUMBER > 100
ORDER BY event_timestamp DESC;
```
### Configuração avançada
#### Gerenciamento de custos do warehouse
* Use o tamanho de warehouse X-Small para otimização de custos
* Configure auto-suspend (60 segundos) e auto-resume
* Agende sincronizações durante horários de baixo uso
* Considere compartilhar o warehouse com outros sistemas de processamento em lote
#### Suporte a sincronizações ao vivo
Para processamento de eventos em tempo real, habilite o rastreamento de alterações nas suas tabelas de eventos:
```sql theme={null}
ALTER TABLE "analytics"."user_events" SET CHANGE_TRACKING = TRUE;
```
#### Segurança de rede
Se estiver usando a política de rede Allowed IPs do Snowflake, adicione os endereços IP do OneSignal à sua lista de permissões. Entre em contato com o suporte do OneSignal para obter os intervalos de IP atuais.
***
## Limitações
* Consultas analíticas complexas podem impactar o desempenho e os custos do warehouse
* A autenticação por usuário/senha será descontinuada em novembro de 2025
* O banco de dados CENSUS é reservado apenas para operações do OneSignal
***
## FAQ
### Qual método de autenticação devo usar?
Use **autenticação por par de chaves** (recomendado). A autenticação por usuário/senha será bloqueada pelo Snowflake a partir de novembro de 2025.
### Posso usar um warehouse existente?
Sim, você pode compartilhar um warehouse com outros sistemas de processamento em lote como dbt ou Fivetran para otimizar custos. Certifique-se de que o warehouse tenha capacidade suficiente para suas necessidades de processamento de eventos.
### Como posso otimizar custos?
* Use o tamanho de warehouse X-Small
* Configure auto-suspend agressivo (60 segundos)
* Agende sincronizações durante horários de baixo uso
* Use sincronizações horárias/diárias em vez de sincronização contínua
***