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 construir sua Transformação de Dados a partir do código padrão ou usando nossa biblioteca de modelos dedicada para ajudar você a começar com certas plataformas externas.

Pré-requisitos

Etapa 1: Identifique uma plataforma de origem

Identifique uma plataforma externa que você queira conectar à Braze e confira 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 fazendo login na plataforma deles:

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.

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.

Nota

Quer additional templates or destinations? Considere deixar um feedback de produto.

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.

Etapa 3: Enviar um webhook de teste (recomendado)

Essa 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, encontre um recurso de “Enviar teste” para gerar um webhook de exemplo e enviá-lo para esse URL.
   • Se a sua plataforma de origem solicitar um tipo de solicitação, selecione POST.
   • Se a sua plataforma de origem oferecer opções de autenticação, selecione Sem autenticação.
   • Se a sua plataforma de origem pedir segredos, selecione Sem segredos.
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 do webhook em Webhook mais recente.

Veja como fica no Typeform:

Nota

O Braze Data Transformation talvez ainda não ofereça suporte a plataformas externas que exigem verificação ou autenticação especial para webhooks. Quer webhook authentication for external platforms? Considere deixar um feedback de produto.

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.

Dica

Para gerar código de transformação com IA, escolha Codificar com o Operator no editor de código de transformação. Para usar esse recurso, é necessário enviar um webhook para sua transformação. Se preferir começar com um modelo pronto, escolha Inserir modelo. Para ver exemplos de prompts, consulte Gerar código de transformação de dados.

Codificar com o Operator só está disponível se o Operator estiver ativado na sua conta. Se não encontrar essa opção, entre em contato com seu gerente de conta.

• beginner - track users
• beginner - update catalog items
• advanced - track users

Aqui, você escreve o código de transformação para definir como mapear os diversos valores do webhook para perfis de usuário na Braze.

1. Novas transformações têm este modelo padrão na seção Código de transformação:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// 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;

2. Para incluir atributos personalizados, eventos personalizados e compras nas chamadas da sua transformação, pule para a etapa 3. Caso contrário, exclua as seções de que você não precisa.
   
   
3. 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.
   
   
4. 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.
   
   
5. Para cada objeto de atributo, evento e compra, verifique o valor de _update_existing_only. Defina-o como false se quiser que a transformação crie um novo usuário que talvez ainda não exista. Deixe como true para atualizar apenas perfis existentes.
   
   
6. Clique em Validar para ver uma prévia da saída do seu código e verificar se ela é uma solicitação /users/track válida.
   
   
7. Ative sua transformação. Se precisar de ajuda adicional com seu código antes de ativá-lo, entre em contato com seu gerente de conta da Braze.
   
   
8. 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 os diversos valores do webhook para atualizações de itens de catálogo na Braze.

1. Novas transformações incluirão este modelo padrão na seção Código de transformação:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// 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;

2. Transformações para destinos /catalogs exigem um catalog_name para definir o catálogo específico a ser atualizado. Você pode definir esse campo diretamente no código 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.
   
   
3. Defina quais itens você quer atualizar no catálogo com os campos id no array de itens. Você pode definir esses campos diretamente no código 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.
   
   
4. Selecione Validar para ver uma prévia da saída do seu código e verificar se ela é uma solicitação válida para o endpoint de atualização de vários itens de catálogo.
   
   
5. Ative sua transformação. Se precisar de ajuda adicional com seu código antes de ativá-lo, entre em contato com seu gerente de conta da Braze.
   
   
6. 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 valor de retorno de objeto JavaScript. Esse valor de retorno deve 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 válida.

Nota

Solicitações de rede externas, bibliotecas de terceiros e webhooks que não sejam JSON não são compatíveis no momento.

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 da performance.

• Solicitações recebidas: É o número de webhooks recebidos no URL desta transformação. Se o número de solicitações recebidas for 0, sua 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 será maior que o número de solicitações recebidas.

Solução de problemas

Para um monitoramento e uma solução de problemas mais detalhados, consulte a página Registros para ver registros específicos. 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 há erros de sintaxe no seu código de transformação e confirme que o código é compilado. Depois, verifique se a saída é uma solicitação de destino válida.

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. É possível que seu código de transformação não esteja considerando todas as variações dos webhooks recebidos.