Ir para o conteúdo

Esta página foi traduzida automaticamente e pode conter imprecisões. Para relatar um erro de tradução, use o componente de feedback na parte inferior do sumário, à direita da página.

Vincular solicitações de Canvas disparadas por API a eventos de envio de mensagens do Currents

Rastreie uma solicitação de Canvas disparada por API até os resultados das mensagens. Para isso, passe um ID de correlação como propriedade de entrada do Canvas, registre-o no evento de envio com message_extras e relacione os eventos de engajamento por dispatch_id e user_id.

Sobre este exemplo

A Pyrite Financial, uma marca fictícia de serviços financeiros, dispara um Canvas a partir dos próprios sistemas sempre que uma transação de um consumidor precisa de um alerta. Ela chama /canvas/trigger/send para cada evento. A equipe de análise de dados quer saber qual solicitação de disparo gerou cada envio, entrega e clique no Currents ou no Snowflake Data Sharing. Ambos incluem os mesmos dados de eventos de envio de mensagens.

Os eventos de envio de mensagens no Currents e no Snowflake Data Sharing não trazem, por si só, o identificador da sua solicitação de disparo. Este exemplo mostra como:

Gerar um ID de correlação no seu sistema de envio e passá-lo como propriedade de entrada do Canvas na solicitação de disparo.
Referenciar essa propriedade no corpo da mensagem com a Liquid tag message_extras, que grava o valor no campo message_extras do evento de envio.
Relacionar o evento de envio aos eventos de entrega e clique por dispatch_id e user_id.

Use essa abordagem quando um sistema externo for responsável pelo disparo e você precisar gerar relatórios sobre o engajamento posterior de cada solicitação. Se uma Campaign atender melhor ao seu caso de uso do que um Canvas, use um identificador de envio. O campo send_id é compatível com os endpoints de envio de mensagens de Campaign, mas não com /canvas/trigger/send.

Considerações

O dispatch_id sozinho não é uma chave única para Canvas. A Braze trata as etapas do Canvas como eventos disparados, então uma etapa pode gerar um dispatch_id único por usuário em cada envio ou um dispatch_id compartilhado entre os usuários do mesmo envio. Sempre combine-o com user_id. Para saber mais, consulte Comportamento do ID de despacho.
O campo message_extras aparece apenas nos eventos de envio. Os eventos de entrega, abertura e clique não o incluem. Por isso, o ID de correlação passa pelo evento de envio e, a partir dele, é relacionado aos outros eventos.
Os message extras são anexados no momento do envio de cada mensagem. Então, um Canvas com várias etapas de Mensagem precisa da tag em cada etapa sobre a qual você quer gerar relatórios.
Todas as chaves e valores de message_extras, somados, precisam ficar abaixo de 1.000 bytes (1 KB), e a Braze trunca valores maiores. Espaços em branco contam para o limite.
O JSON resultante contém apenas valores de string. Use uma variável Liquid como chave ou valor. Não aninhe outras Liquid tags dentro de message_extras.
Os eventos do Currents armazenam o ID de usuário da Braze em user_id e o seu próprio identificador em external_user_id. Faça a junção por user_id e selecione external_user_id quando precisar associar as linhas aos seus sistemas.
Use o Currents ou o Snowflake Data Sharing para esse padrão. Ambos expõem os mesmos campos de eventos de envio de mensagens, incluindo message_extras nos eventos de envio.
Os esquemas do Currents e do Snowflake marcam message_extras como IPI. Use um ID de solicitação opaco em vez de dados do consumidor.
O objeto context em uma solicitação de disparo de Canvas pode ter até 50 KB, compartilhados entre todas as propriedades que você passar.

Configuração

Etapa 1: Gerar um ID de correlação por solicitação

No seu sistema de envio, crie um identificador para cada solicitação de disparo (por exemplo, um UUID) e armazene-o no seu próprio registro de solicitações. Mantenha-o opaco e curto o suficiente para caber no limite de tamanho de message_extras.

Etapa 2: Passar o ID como propriedade de entrada do Canvas

Inclua o ID no objeto context da sua solicitação para /canvas/trigger/send. Defina-o por destinatário quando cada usuário tiver um ID distinto, ou no nível superior quando um único ID abranger todos os destinatários da solicitação.

{
  "canvas_id": "canvas_identifier",
  "recipients": [
    {
      "external_user_id": "user_identifier",
      "context": {
        "request_id": "8f14e45f-ceea-467a-9e30-6b1b1c4a7d20"
      }
    }
  ]
}

As propriedades de entrada do Canvas ficam disponíveis como variáveis de contexto em todo o Canvas.

Etapa 3: Registrar o ID no evento de envio

Em cada etapa de Mensagem sobre a qual você quer gerar relatórios, atribua a variável de contexto e passe-a para message_extras.

{% assign request_id = context.${request_id} %}
{% message_extras :key request_id :value {{request_id}} %}

A Braze anexa o par chave-valor ao campo message_extras do evento de envio no momento do envio.

Etapa 4: Verificar com um envio de teste

Envie uma entrada de teste pelo Canvas e confirme se o evento de envio no Currents ou no Snowflake Data Sharing contém message_extras com a sua chave request_id. Se o campo estiver vazio, verifique a sintaxe da tag. Delimitadores digitados incorretamente e chaves e valores fora de ordem são as causas mais comuns.

Etapa 5: Relacionar os envios aos eventos de entrega e clique

Com o ID no evento de envio, faça a junção com os outros eventos por dispatch_id e user_id. O exemplo do Query Builder a seguir mostra os resultados de entrega e clique por solicitação para e-mail:

WITH sends AS (
  SELECT
    USER_ID,
    EXTERNAL_USER_ID,
    DISPATCH_ID,
    PARSE_JSON(MESSAGE_EXTRAS):request_id::STRING AS request_id,
    TIME AS send_time
  FROM USERS_MESSAGES_EMAIL_SEND_SHARED
  WHERE MESSAGE_EXTRAS IS NOT NULL
    AND PARSE_JSON(MESSAGE_EXTRAS):request_id IS NOT NULL
)
SELECT
  s.request_id AS "Request ID",
  s.EXTERNAL_USER_ID AS "External User ID",
  MIN(s.send_time) AS "Sent",
  MIN(d.TIME) AS "Delivered",
  MIN(c.TIME) AS "First Click"
FROM sends AS s
LEFT JOIN USERS_MESSAGES_EMAIL_DELIVERY_SHARED AS d
  ON d.USER_ID = s.USER_ID
  AND d.DISPATCH_ID = s.DISPATCH_ID
LEFT JOIN USERS_MESSAGES_EMAIL_CLICK_SHARED AS c
  ON c.USER_ID = s.USER_ID
  AND c.DISPATCH_ID = s.DISPATCH_ID
GROUP BY 1, 2
ORDER BY 3 DESC;

Substitua pelas tabelas do canal que você usa para enviar. Por exemplo, use USERS_MESSAGES_PUSHNOTIFICATION_SEND_SHARED e USERS_MESSAGES_PUSHNOTIFICATION_OPEN_SHARED para push. Para ver a lista completa de colunas de cada tabela, consulte a referência de tabelas SQL.

O exemplo do Query Builder é apenas uma opção. Aplique as mesmas junções no Snowflake Data Sharing ou nas exportações do Currents para o seu próprio data warehouse: analise message_extras no evento de envio e, em seguida, relacione os eventos de engajamento por dispatch_id e user_id.

New Stuff!