Pular para o conteúdo principal

​
Visão Geral

A integração OneSignal + Google Pub/Sub permite a sincronização em tempo real de eventos personalizados dos seus tópicos Pub/Sub para o OneSignal para acionar campanhas de mensagens automatizadas e Jornadas baseadas no comportamento do usuário. O Pub/Sub é o serviço de mensagens escalável do Google que permite que aplicativos enviem e recebam mensagens entre componentes independentes. O OneSignal atua como um assinante dos seus tópicos Pub/Sub, permitindo que você sincronize mensagens de eventos do Pub/Sub para acionar experiências personalizadas de usuário.

​
Requisitos

​
Google Pub/Sub

  • Projeto Google Cloud com Pub/Sub habilitado
  • Tópicos Pub/Sub contendo mensagens de eventos
  • Permissões IAM para conceder acesso à conta de serviço
  • Mensagens formatadas em JSON nos seus tópicos

​
Configuração

1

Criar conexão Pub/Sub

In OneSignal, go to Data > Integrations and click Add Integration.
  1. Selecione Google Pub/Sub da lista
  2. Insira o GCP Project ID onde seus tópicos Pub/Sub estão localizados
  3. Escolha o método de autenticação:
    • Conta de Serviço Auto-gerada (recomendado): O OneSignal cria e gerencia a conta de serviço
    • Conta de Serviço Existente: Forneça seu próprio arquivo JSON de chave de conta de serviço
  4. Clique em Connect
2

Conceder permissões à conta de serviço

O OneSignal criará uma nova conta de serviço e fornecerá o endereço de email da conta de serviço.Conceda a função roles/pubsub.editor a esta conta de serviço no seu projeto GCP:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
  --role roles/pubsub.editor
O OneSignal usa esta função para:
  • Criar assinaturas para seus tópicos de eventos
  • Consumir mensagens de eventos dos tópicos
  • Criar tópicos de erro (Dead Letter Queue) para processamento com falha
3

Testar conexão

Depois de conceder as permissões necessárias, clique em Save no OneSignal para verificar a conexão.O OneSignal validará que pode acessar seus tópicos Pub/Sub e está pronto para processar mensagens de eventos.

​
Esquema de Dados de Eventos

Antes de usar um tópico Pub/Sub para eventos personalizados, você deve definir o esquema das mensagens de eventos.
1

Navegar até a definição de esquema de eventos

No OneSignal, vá para Data > Integrations e selecione sua conexão Pub/Sub.O OneSignal puxa automaticamente a lista de tópicos do seu projeto. Clique em Refresh topics para atualizar manualmente a lista.
2

Definir esquema de mensagem de evento

  1. Clique no nome do tópico contendo seus dados de evento
  2. Selecione JSON como formato de mensagem (único formato suportado)
  3. Clique em Import sample message e forneça uma mensagem de evento de exemplo
  4. Revise o esquema detectado para garantir o mapeamento adequado de campos
  5. Clique em Save Dataset

​
Formato de Mensagem de Evento

Suas mensagens Pub/Sub devem seguir esta estrutura JSON para eventos personalizados do OneSignal: 
{
  "event_name": "purchase_completed",
  "user_id": "user_12345",
  "timestamp": "2023-12-01T10:30:00Z",
  "properties": {
    "product_id": "prod_abc123",
    "price": 29.99,
    "category": "electronics",
    "payment_method": "credit_card"
  },
  "session_id": "session_789"
}

​
Event data mapping

Map your to OneSignal’s custom events format:
OneSignal FieldDescriptionRequired
nameevent_nameEvent identifierYes
external_iduser_idUser identifierYes
timestampevent_timestampWhen event occurredNo
propertiesevent_dataNo
Não inclua PII de clientes ou dados sensíveis em mensagens de exemplo. O OneSignal armazena amostras de mensagens como parte da definição do dataset.

​
Processamento de Eventos em Tempo Real

Ao contrário das integrações em lote, o Pub/Sub permite processamento de eventos quase em tempo real:
  • Baixa Latência: Eventos são processados em segundos após serem publicados nos tópicos
  • Assinaturas Automáticas: O OneSignal cria assinaturas dedicadas para cada tópico
  • Tratamento de Erros: Eventos com falha são enviados para tópicos de Dead Letter Queue para investigação
  • Processamento Escalável: Lida com fluxos de eventos de alto volume automaticamente

​
Configuração Avançada

​
Dead Letter Queue

O OneSignal cria automaticamente tópicos de erro para eventos que falham no processamento:
  • Criação Automática: Tópicos de erro são criados por assinatura
  • Armazenamento de Eventos com Falha: Eventos que não podem ser processados são armazenados para depuração
  • Revisão Manual: Acesse eventos com falha através do Console do Google Cloud para solução de problemas

​
Confirmação de Mensagem

O OneSignal lida com a confirmação de mensagens Pub/Sub automaticamente:
  • Processamento bem-sucedido: Mensagens são confirmadas após a criação bem-sucedida do evento
  • Processamento com Falha: Mensagens são confirmadas negativamente e enviadas para a Dead Letter Queue
  • Lógica de Repetição: Tratamento de repetição integrado para falhas transitórias

​
Limitações

  • Apenas o formato de mensagem JSON é suportado
  • Amostras de mensagens são armazenadas como parte das definições de dataset (evite PII)
  • Requer permissões roles/pubsub.editor no nível do projeto
  • O tamanho máximo da mensagem segue os limites do Google Pub/Sub (10MB)

​
Perguntas Frequentes

​
Com que rapidez os eventos são processados?

Os eventos são normalmente processados em segundos após serem publicados no seu tópico Pub/Sub, permitindo o acionamento de Jornadas quase em tempo real.

​
O que acontece se o OneSignal não conseguir processar um evento?

Eventos com falha são automaticamente enviados para um tópico de Dead Letter Queue que o OneSignal cria. Você pode revisar esses eventos no Console do Google Cloud para depuração.

​
Posso usar múltiplos tópicos para diferentes tipos de eventos?

Sim, você pode definir esquemas para múltiplos tópicos dentro do mesmo projeto GCP. Cada tópico pode conter diferentes tipos de eventos com suas próprias definições de esquema.