Ir para o conteúdo

Criar uma transformação

A Transformação de Dados da Braze permite que você crie e gerencie integrações de webhook para automatizar o fluxo de dados de plataformas externas para a Braze. Essas integrações de webhook podem então alimentar casos de uso de marketing ainda mais sofisticados. Você pode criar sua Transformação de Dados a partir do código padrão ou usar nossa biblioteca de modelos dedicada para começar com determinadas plataformas externas.

Pré-requisitos

Requisito Descrição
Autenticação de dois fatores ou SSO Você precisa ter a autenticação de dois fatores (2FA) ou o logon único (SSO) ativado na sua conta.
Permissões corretas Você precisa ser administrador da conta ou administrador do espaço de trabalho, ou ter a permissão de usuário “Manage Transformations”.

Etapa 1: Identifique uma plataforma de origem

Identifique uma plataforma externa que você deseja conectar à Braze e verifique se ela oferece suporte a webhooks. Essas configurações às vezes são chamadas de “notificações de API” ou “solicitações de serviço web”.

Veja a seguir um exemplo de webhook do Typeform, que pode ser configurado ao fazer login na plataforma:

Um exemplo de carga útil de webhook do Typeform nas configurações da plataforma Typeform.

Etapa 2: Criar uma transformação

No dashboard da Braze, acesse Configurações de dados > Transformação de dados.

Selecione Criar Transformação para nomear sua transformação e, em seguida, escolha sua experiência de edição.

Detalhes da transformação com a opção de escolher "Usar um modelo" ou "Começar do zero" para sua experiência de edição.

Selecione Usar um modelo para navegar por uma biblioteca de modelos, incluindo casos de uso de Transformação de dados. Ou selecione Começar do zero para carregar um modelo de código padrão.

Se você está começando do zero, escolha um destino para sua transformação. Você ainda pode inserir um modelo de código da biblioteca de modelos.

Mais sobre destinos
  • POST: Rastrear usuários: Transforma webhooks de uma plataforma de origem em atualizações de perfil de usuário, como atributos, eventos ou compras.
  • PUT: Atualizar vários itens do catálogo: Transforma webhooks de uma plataforma de origem em atualizações de itens do catálogo.
  • DELETE: Excluir vários itens do catálogo: Transforma webhooks de uma plataforma de origem em exclusões de itens do catálogo.
  • PATCH: Editar vários itens do catálogo: Transforma webhooks de uma plataforma de origem em edições de itens do catálogo.
  • POST: Enviar mensagens imediatamente via API Only: Transforma webhooks de uma plataforma de origem para enviar mensagens imediatas a usuários designados.

Após criar sua transformação, você verá a visão detalhada da transformação. Aqui, você pode visualizar o webhook mais recente recebido para esta transformação em Detalhes do webhook e um espaço para escrever seu código de transformação em Código de transformação.

Capture sua URL do webhook para uso na próxima etapa.

Esta etapa é opcional, mas recomendamos enviar um webhook de teste da sua plataforma de origem para a transformação que você acabou de criar.

  1. Copie o URL da sua transformação.
  2. Na sua plataforma de origem, procure um recurso de “Send Test” (enviar teste) para gerar um exemplo de webhook e enviá-lo para esse URL.
    • Se a sua plataforma de origem pedir um tipo de solicitação, selecione POST.
    • Se a sua plataforma de origem oferecer opções de autenticação, selecione No authentication.
    • Se a sua plataforma de origem pedir segredos, selecione No secrets.
  3. Atualize a página no dashboard da Braze para ver se o webhook foi recebido. Se ele tiver sido recebido, você verá uma carga útil de webhook em Most recent webhook.

Veja como fica no Typeform:

Exemplo de código de Data Transformation que mapeia o webhook para perfis de usuário da Braze.

Etapa 4: Escrever o código de transformação

Se você tem pouca ou nenhuma experiência com código JavaScript ou prefere instruções mais detalhadas, siga a guia Beginner - POST: Track users ou Beginner - PUT: Update multiple catalog items para escrever seu código de transformação.

Se você é desenvolvedor ou tem bastante experiência com código JavaScript, siga a guia Advanced - POST: Track users para ver instruções gerais sobre como escrever seu código de transformação.

Aqui, escreva o código de transformação para definir como mapear vários valores do webhook para perfis de usuário da Braze.

  1. Novas transformações têm este modelo padrão na seção Código de transformação:
// Here, we will define a variable, "brazecall", to build up a `/users/track` request
// Everything from the incoming webhook is accessible via the special variable "payload"
// So you can template in desired values in your `/users/track` request with dot notation, such as payload.x.y.z

let brazecall = {
  "attributes": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "attribute_1": payload.attribute_1
    }
  ],
  "events": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "name": payload.event_1,
      "time": new Date(),
      "properties": {
        "property_1": payload.event_1.property_1
      }
    }
  ],
  "purchases": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "product_id": payload.product_id,
      "currency": payload.currency,
      "price": payload.price,
      "quantity": payload.quantity,
      "time": payload.timestamp,
      "properties": {
        "property_1": payload.purchase_1.property_1
      }
    }
  ]
};

// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
  1. Para incluir atributos personalizados, eventos personalizados e compras nas suas chamadas de transformação, pule para a etapa 3. Caso contrário, exclua as seções de que você não precisa.

  2. Cada objeto de atributo, evento e compra exige um identificador de usuário: external_id, user_alias, braze_id, email ou phone. Encontre o identificador de usuário na carga útil do webhook recebido e insira esse valor no seu código de transformação por meio de uma linha de carga útil. Use a notação de ponto para acessar as propriedades do objeto da carga útil.

  3. Encontre os valores do webhook que você quer representar como atributos, eventos ou compras e insira esses valores no seu código de transformação por meio de uma linha de carga útil. Use a notação de ponto para acessar as propriedades do objeto da carga útil.

  4. Para cada objeto de atributo, evento e compra, verifique o valor de _update_existing_only. O modelo padrão define esse valor como true, o que significa que apenas perfis de usuário existentes serão atualizados. Para criar novos usuários quando eles não existirem, defina esse valor como false. Se você omitir totalmente esse campo de um objeto, o comportamento será o mesmo de false (novos usuários serão criados).

  5. Clique em Validar para ver uma prévia da saída do seu código e verificar se ela é uma solicitação /users/track aceitável.

  6. Ative sua transformação. Se precisar de ajuda com seu código antes de ativá-lo, entre em contato com seu gerente de conta da Braze.

  7. Faça com que sua plataforma de origem comece a enviar webhooks. Seu código de transformação será executado para cada webhook recebido, e os perfis de usuário começarão a ser atualizados.

Sua integração de webhook está concluída!

Aqui, você pode escrever o código de transformação para definir como quer mapear vários valores do webhook para atualizações de itens de catálogo da Braze.

  1. Novas transformações incluirão este modelo padrão na seção Código de transformação:
// This is a default template that you can use as a starting point
// Feel free to delete this entirely and create a new transformation, or edit specific components

// First, this code defines a variable, "brazecall", to build a PUT /catalogs/{catalog_name}/items request
// Everything from the incoming webhook is accessible via the special variable "payload"
// As such, you can template in desired values in your request with JS dot notation, such as payload.x.y.z

let brazecall = {
  // For Braze Data Transformation to update Catalog items, the special variable "catalog_name" is required
  // This variable is used to specify the catalog name which would otherwise go in the request URL
  "catalog_name": "catalog_name",

  // After defining "catalog name", construct the Update Multiple Catalog Items request as usual below
  // Documentation for the destination endpoint: /docs/pt-br/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/
  "items": [
    {
      "id": payload.item_id_1,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_2,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_3,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    }
  ]
};

// After the request body is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
  1. Transformações para destinos /catalogs exigem um catalog_name para definir o catálogo específico a ser atualizado. Você pode codificar esse campo diretamente ou preenchê-lo com um campo do webhook por meio de uma linha de carga útil. Use a notação de ponto para acessar as propriedades do objeto da carga útil.

  2. Defina quais itens você quer atualizar no catálogo com os campos id na matriz de itens. Você pode codificar esses campos diretamente ou preenchê-los com um campo do webhook por meio de uma linha de carga útil.

    Lembre-se de que catalog_column é um valor de espaço reservado. Confira se os objetos de item contêm apenas campos que existem no catálogo.

  3. Selecione Validar para ver uma prévia da saída do seu código e verificar se ela é uma solicitação aceitável para o endpoint de atualização de vários itens de catálogo.

  4. Ative sua transformação. Se precisar de ajuda com seu código antes de ativá-lo, entre em contato com seu gerente de conta da Braze.

  5. Verifique se sua plataforma de origem tem uma configuração para começar a enviar webhooks. Seu código de transformação será executado para cada webhook recebido, e os itens do catálogo começarão a ser atualizados.

Sua integração de webhook está concluída!

Nesta etapa, você vai transformar a carga útil do webhook da plataforma de origem em um objeto JavaScript como valor de retorno. Esse valor de retorno precisa seguir o formato do corpo da solicitação do endpoint /users/track:

  • O código de transformação é aceito na linguagem de programação JavaScript. Qualquer fluxo de controle JavaScript padrão, como lógica if/else, é compatível.
  • O código de transformação acessa o corpo da solicitação do webhook por meio da variável payload. Essa variável é um objeto preenchido pela análise do JSON do corpo da solicitação.
  • Qualquer recurso compatível com nosso endpoint /users/track é compatível, incluindo:
    • Objetos de atributos de usuário, objetos de evento e objetos de compra
    • Atributos aninhados e propriedades de eventos personalizados aninhados
    • Atualizações de grupo de inscrições
    • Endereço de e-mail como identificador

Selecione Validar para ver uma prévia da saída do seu código e verificar se ela é uma solicitação /users/track aceitável.

Etapa 5: Monitore sua transformação

Depois de ativar sua transformação, consulte a análise de dados na página principal de Transformações para ver um resumo do desempenho.

  • Solicitações recebidas: Esse é o número de webhooks recebidos no URL desta transformação. Se não houver solicitações recebidas, a plataforma de origem não enviou nenhum webhook ou não foi possível estabelecer a conexão.
  • Entregas: Depois de receber as solicitações, a Transformação de Dados aplica seu código de transformação para enviar ao destino da Braze selecionado.

O ideal é que 100% das solicitações recebidas resultem em entregas. O número de entregas nunca vai ultrapassar o número de solicitações recebidas.

Solução de problemas

Para monitorar e solucionar problemas com mais detalhes, consulte a página Registros. Lá ficam registradas as últimas 1.000 solicitações recebidas por todas as transformações em seus espaços de trabalho. Você pode selecionar cada registro para ver o corpo da solicitação recebida, a saída da transformação e o corpo da resposta do destino da transformação.

Se não houver entregas, verifique se o código de transformação tem erros de sintaxe e confirme que ele compila. Depois, verifique se a saída é uma solicitação válida para o destino.

Se o número de entregas for menor que o de solicitações recebidas, pelo menos alguns webhooks estão sendo entregues com sucesso. Consulte os registros da transformação para ver exemplos de erros e confira se a saída da transformação é a esperada. Pode ser que seu código de transformação não esteja considerando todas as variações dos webhooks recebidos.

New Stuff!