Integração de streaming de eventos

Assistência de desenvolvedor necessária

Você precisará da ajuda da sua equipe de desenvolvimento para configurar a integração. Por favor, compartilhe este guia com eles.

Visão geral da integração

Tipo de integração

Fonte: os dados são enviados do Pushwoosh para o seu sistema via HTTP ou gRPC com base nos gatilhos de eventos configurados.

Como a integração funciona?

O Pushwoosh transmite dados de eventos de comunicação (por exemplo, atividade de push/e-mail) para um endpoint definido pelo cliente. Os dados são enviados em fluxos de lote em intervalos programados ou ao atingir um tamanho mínimo de lote.

Os dados só são enviados se corresponderem aos eventos, plataformas e filtros opcionais selecionados (códigos de campanha/mensagem, atividade ao vivo). O endpoint do cliente deve estar pronto para receber e, opcionalmente, responder com um status.

Glossário

URL do endpoint: Endpoint do lado do servidor que permite receber solicitações. O cliente pode especificar uma porta, se necessário.

Exemplos:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

Lista de entidades sincronizadas

• Eventos de estatísticas de comunicação (por exemplo, Push Enviado, E-mail Entregue)
• Post events: eventos que seu aplicativo envia para o Pushwoosh via postEvent, transmitidos separadamente dos eventos de estatísticas de comunicação

Casos de uso

• Rastreamento de engajamento em tempo real

Monitore as interações do usuário, como push enviado, e-mail aberto ou mensagem entregue, à medida que acontecem, permitindo visibilidade imediata do desempenho da campanha.

• Integração com análises externas

Transmita eventos para plataformas de análise de terceiros para relatórios e análises centralizados.

• Fluxos de trabalho de usuário automatizados

Acione ações em sistemas externos (como CRMs ou ferramentas de automação de marketing) com base nos comportamentos do usuário, por exemplo, envie uma mensagem de acompanhamento quando um usuário abrir um e-mail.

• Sincronização da lista de dispositivos

Remova dispositivos do seu próprio banco de dados quando eles não puderem mais receber mensagens. Consulte Sincronizar dispositivos com registro cancelado com o seu sistema.

Configurando a integração

Para configurar a integração:

1. Na sua conta Pushwoosh, vá para Configurações > Integrações de terceiros, encontre Integração de streaming de eventos e clique em Configurar.

2. Na janela que se abre, preencha os campos necessários.

Inserir URL do endpoint

No campo URL do endpoint, insira a URL completa para onde os eventos serão enviados, incluindo o protocolo e a porta, se aplicável.

Exemplo

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

Selecionar eventos

No menu suspenso Eventos, selecione pelo menos um evento. Se nenhum for selecionado, a validação falhará. A lista de eventos é gerenciada pelo backend e pode mudar com o tempo.

Fornecer credenciais de autorização

Se exigido pelo seu servidor, insira o valor completo para o cabeçalho Authorization no campo Autorização.

Exemplos:

• Bearer your_token_here

• Basic base64encoded_credentials

Nota

O valor é inserido como está no cabeçalho Authorization (HTTP) ou nos metadados gRPC. Certifique-se de que há um espaço entre o esquema de autenticação e o token.

Escolher tipo de transporte

No menu suspenso Tipo de transporte, escolha o protocolo de entrega para a transmissão de eventos: HTTP ou gRPC. Cada um tem comportamento e configuração específicos.

HTTP

Com o tipo de transporte HTTP, o Pushwoosh reúne os eventos em um lote e o envia quando qualquer uma das seguintes condições é atendida:

• 10.000 eventos foram coletados, ou

• 5 minutos se passaram desde o início do lote.

Um lote é entregue em solicitações HTTP de até 100 eventos ou 768 KiB, o que for atingido primeiro.

Após o envio dos dados, a conexão é fechada assim que uma resposta bem-sucedida é recebida.

Se o servidor responder com um código de status 5xx, 408 ou 429, o Pushwoosh tenta novamente a solicitação de acordo com a política de nova tentativa definida.

Mecanismo de nova tentativa

Tentativa	Atraso
1ª	1 segundo
2ª	3 segundos após a 1ª tentativa
3ª	8 segundos após a 2ª tentativa

Se todas as novas tentativas falharem, o Pushwoosh mantém os eventos que não foram entregues e tenta enviá-los novamente um minuto depois. Os eventos que o seu endpoint já aceitou não são enviados de novo.

Se o seu endpoint responder com 400, 413 ou 422, o Pushwoosh divide a solicitação em solicitações menores até que o evento recusado seja enviado sozinho e, em seguida, descarta esse evento. Qualquer outra resposta 4xx interrompe a entrega do lote: o Pushwoosh tenta novamente por até 2 horas e depois o descarta.

Se o seu endpoint continuar falhando por 24 horas sem aceitar nenhum evento, o Pushwoosh pausa a integração. Consulte Integração pausada.

Tempo limite

O tempo limite padrão para uma solicitação é de 60 segundos. Isso pode ser personalizado mediante solicitação via suporte.

Ver exemplo

gRPC

O tipo de transporte gRPC usa streaming bidirecional para a transmissão de dados. Saiba mais na documentação do gRPC.

Um fluxo é aberto quando uma das seguintes condições é atendida:

• Pelo menos 1.000 eventos estão prontos para entrega
• Uma hora se passou desde que o último fluxo foi aberto

O fluxo é fechado após o envio dos eventos. Isso garante que um novo fluxo não seja aberto para cada evento individual em um curto período de tempo.

Ver especificação protobuf

Mecanismo de nova tentativa
Cada evento inclui um uuid único. Se um evento falhar:

1. A resposta deve incluir um status diferente de "Success"
2. O uuid original da solicitação deve ser incluído

O Pushwoosh tentará novamente a entrega com base nesta resposta.

Configurações de conexão

Opções avançadas como TLS, keep-alive ou políticas de nova tentativa são configuradas manualmente via suporte e podem exigir envolvimento de desenvolvimento.

Habilitar post events

Este botão está desativado por padrão, então apenas os eventos de estatísticas de comunicação são transmitidos. Para também transmitir eventos que seu aplicativo envia para o Pushwoosh via postEvent, ative o botão Permitir post events.

No campo Post events que aparece, selecione quais dos eventos da sua conta devem ser transmitidos. Pelo menos um evento é necessário enquanto o botão estiver ativado. Se sua conta ainda não enviou nenhum evento, esta lista estará vazia até que você chame postEvent pelo menos uma vez.

Nota

Os post events são enviados para a mesma URL do endpoint inserida acima e chegam a ela independentemente da plataforma: as seções Plataformas e Filtros avançados abaixo se aplicam apenas aos eventos de estatísticas de comunicação, não aos post events.

Impressões e cliques de in-app também passam por esse fluxo de post events, como PW_InAppShow e PW_InAppClicked. Cada um aparece na lista Post events somente depois de ter sido disparado pelo menos uma vez para a conta, assim como qualquer outro post event.

Selecionar plataformas

Na seção Plataformas, selecione pelo menos uma plataforma para ativar o streaming de eventos.

As plataformas suportadas incluem:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Configurar filtros avançados

Na seção Filtros avançados, refine os critérios de entrega de eventos usando filtros:

• Eventos de atividade ao vivo: Habilite para receber eventos de atividade ao vivo. Estes eventos contêm apenas metadados, incluindo live_activity_id.

• Filtros de campanha: Filtre por código de campanha. Apenas eventos vinculados a essas campanhas serão entregues.

• Filtros de mensagem: Filtre por código de mensagem. Apenas eventos vinculados a essas mensagens serão entregues.

Após preencher todos os campos obrigatórios, clique no botão Aplicar para salvar e ativar sua integração.

Nota

As alterações de configuração entrarão em vigor em até 15 minutos após o envio.

Dica

Para configurações avançadas, como tempos limite personalizados ou configurações de gRPC, por favor, entre em contato com o suporte.

Detalhes da solicitação e exemplo

Endpoint	https://exampleclientendpoint.com/webhook_endpoint
Requisição HTTP	POST
Autenticação	Não
Tipo de requisição	Fonte
Significado da requisição	Enviar requisições para o endpoint do webhook
Cabeçalhos	Content-Type: application/json

Exemplo de corpo da requisição

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Atributos

Entre os eventos de estatísticas de comunicação, attributes é preenchido apenas para eventos de push, com conteúdo específico do canal (Android, iOS, etc.) para a plataforma para a qual o push foi enviado. Eventos de e-mail e SMS carregam apenas os campos de nível superior (event_name, platform, payload, etc.). attributes é null para esses eventos. Dentro de um objeto attributes preenchido, os campos fora da plataforma do próprio evento são omitidos em vez de serem enviados como valores vazios. Consulte webhook.proto para a lista completa de campos.

Um post event carrega seus pares de chave/valor de atributo em attributes.event_attributes. message_code e payload permanecem vazios, porque um post event não está vinculado a uma mensagem ou campanha.

Cuidado

attributes.geozone está obsoleto: a propriedade de origem é um objeto, não um número, então este campo nunca carregou um valor real. Leia a geozone real de attributes.geozone_data. O campo antigo permanece no contrato para clientes com stubs gRPC existentes.

Resposta
O corpo da resposta é ignorado. Com o transporte HTTP, o código de resposta determina se os eventos contam como entregues. Um código 2xx significa que o seu endpoint os aceitou.

Sincronizar dispositivos com registro cancelado com o seu sistema

Se você mantém sua própria cópia da lista de dispositivos, por exemplo em um CRM ou em uma plataforma de dados do cliente, transmita o post event PW_DeviceUnregistered para encontrar dispositivos que o Pushwoosh não consegue mais alcançar. O Pushwoosh envia esse evento quando um dispositivo perde sua inscrição push. Para conhecer os motivos, consulte PW_DeviceUnregistered.

Comece com uma integração que já esteja configurada, com uma URL do endpoint inserida e pelo menos uma plataforma selecionada. Depois:

1. Nas configurações da integração, ative Permitir post events. Consulte Habilitar post events.
2. No campo Post events, selecione PW_DeviceUnregistered.
3. Para também saber quais dispositivos recebem um token de push, selecione PW_DeviceRegistered.
4. Clique em Aplicar. A alteração entra em vigor em até 15 minutos.

Como qualquer post event, PW_DeviceUnregistered aparece na lista Post events somente depois de ter sido disparado pelo menos uma vez para a conta. Consulte Habilitar post events.

Tenha em mente estas limitações ao processar os eventos:

• Identifique os dispositivos por hwid ou user_id, não pelo token de push. O evento traz o hwid, o user_id e a plataforma do dispositivo, mas não traz o token de push nem o motivo do cancelamento do registro. Um token expirado e um cancelamento de registro pelo SDK têm a mesma aparência.
• Um novo token para o mesmo dispositivo não envia nenhum evento. PW_DeviceRegistered é disparado somente quando um dispositivo sem token de push recebe um. Uma lista que armazena dispositivos por token de push mantém tokens que não funcionam mais, porque, quando um dispositivo recebe um novo token, nenhum dos dois eventos é disparado.
• O cancelamento da inscrição em e-mails não exclui o dispositivo. No caso do e-mail, o endereço permanece no dispositivo e o Pushwoosh apenas o marca como com inscrição cancelada. Quando o usuário cancelou a inscrição por um link em um e-mail, attributes.event_attributes também traz o message_code e o campaign_id desse e-mail.

Alguns eventos podem nunca chegar ao seu endpoint: um evento que o seu endpoint recusa com 400, 413 ou 422 é descartado, assim como um lote que o seu endpoint continua recusando com outro código 4xx por 2 horas (consulte HTTP). Para identificar esses dispositivos, exporte periodicamente o segmento dos dispositivos que você segmenta para CSV e compare-o com sua lista de dispositivos. Exportar um segmento exige a permissão Personal data na sua função. Se o seu endpoint continuar falhando por 24 horas, a integração é pausada e os eventos param de chegar. Consulte Integração pausada.

Integração pausada

Se as entregas para o seu endpoint HTTP continuarem falhando por 24 horas e o endpoint não aceitar nenhum evento durante esse período, o Pushwoosh pausa a integração:

• O Pushwoosh para de enviar eventos para o endpoint.
• Os eventos aguardando envio são descartados. Os eventos do período de pausa não são enviados depois.
• O proprietário da conta recebe um e-mail sobre a pausa. As configurações da integração não mostram a pausa, portanto este e-mail é o único aviso.

Um evento conta como aceito quando o seu endpoint retorna um código de resposta 2xx. Falhas parciais não pausam a integração: qualquer evento aceito reinicia a contagem de 24 horas. Integrações com o transporte gRPC não são pausadas.

Para retomar o streaming:

1. Certifique-se de que o seu endpoint está acessível e retorna um código de resposta 2xx.
2. Vá para Configurações > Integrações de terceiros, encontre Integração de streaming de eventos e clique em Configurar.
3. Clique em Aplicar. Você não precisa alterar nenhuma configuração. O streaming é retomado em até 15 minutos.

Como você sabe que a integração está funcionando?

Você começará a receber solicitações do Pushwoosh no seu endpoint configurado.