API de Personalização Hightouch

A API de Personalização da Hightouch é um serviço gerenciado que permite hospedar uma API de dados de baixa latência baseada em qualquer conjunto de dados no seu data warehouse na nuvem.

A integração da Braze com a Hightouch permite que você use a API com o Conteúdo conectado da Braze para obter dados atualizados de clientes ou objetos em suas Campaigns ou Canvas no momento do envio.

A API de Personalização da Hightouch fornece um endpoint REST para usar na sua configuração da Braze. Especificamente, você pode usar a oferta de Conteúdo conectado da Braze para fazer uma solicitação GET à API de Personalização e recuperar todas as informações relacionadas a um identificador específico. Os dados expostos por essa API podem representar dados de clientes, produtos ou qualquer outro objeto.

Pré-requisitos

• use cases
• datasets

Integração

Etapa 1: Conectar a fonte de dados à Hightouch

As fontes da Hightouch são onde os dados comerciais da sua organização residem. Neste caso, é onde seus dados de usuários são armazenados.

1. Na Hightouch, acesse Sources Overview > Add Source. Selecione seu data warehouse como a fonte.
   
   
2. Insira as credenciais relevantes; elas variarão dependendo da fonte.

Para mais detalhes, consulte a documentação relevante.

Etapa 2: Modelar os dados

Os modelos da Hightouch definem quais dados extrair da sua fonte. Para configurar um novo modelo, siga estas etapas:

1. Na Hightouch, acesse Models overview > Add model e selecione a fonte que você acabou de conectar.
   
   
2. Em seguida, escolha um método de modelagem. Como todas as suas informações devem ser reunidas em uma única tabela, você pode usar o seletor de tabela visual para defini-la. Alternativamente, você pode escrever SQL para incluir apenas as colunas que deseja ou utilizar seus modelos dbt existentes, Looker Looks ou workbooks da Sigma.
   
   
3. Antes de continuar, visualize seu modelo para confirmar se ele está consultando os dados de seu interesse. Por padrão, a Braze limita a pré-visualização aos primeiros 100 registros. Depois de validar seus dados, clique em Continue.
   
   
4. Dê um nome ao seu modelo, por exemplo, “Recomendações do usuário”.
   
   
5. Por fim, selecione uma chave primária e clique em Finish. Uma chave primária deve ser uma coluna com identificadores únicos. Este é também o campo que você usará para chamar a API de Personalização e recuperar as recomendações de um usuário específico.

Etapa 3: Configurar a API de Personalização

A preparação da API para receber solicitações tem duas etapas:

• Ativar a API de Personalização nas regiões mais próximas da sua infraestrutura
• Criar sincronizações para definir quais modelos devem ser materializados no cache gerenciado pela Hightouch

Siga estas instruções para completar ambas:

1. Na Hightouch, acesse Destinations e selecione a API de Personalização da Hightouch criada para você. Se você não tiver esse destino ativado, entre em contato com o suporte da Hightouch.
   
   
2. Em seguida, selecione a região apropriada. Selecionar a região mais próxima da sua infraestrutura reduzirá seus tempos de resposta. Se você não vir uma região próxima à sua infraestrutura, entre em contato com o suporte da Hightouch.
   
   
3. Acesse a página de visão geral de Syncs e clique no botão Add sync. Em seguida, selecione o modelo relevante e o destino que você configurou anteriormente.
   
   
4. Digite um nome de coleção alfanumérico. Coleções são conceitualmente semelhantes a tabelas de banco de dados. Cada uma deve representar um tipo de dado específico, como clientes ou faturas. Os nomes das coleções devem ser alfanuméricos e farão parte do seu endpoint da API de Personalização.
   
   
5. Em seguida, especifique qual coluna do seu modelo deve servir como índice principal para consultas de registros. Esse campo deve identificar exclusivamente cada registro na coleção e muitas vezes é o mesmo que a chave primária do seu modelo. A API de Personalização suporta pesquisas em vários índices. Por exemplo, pode ser do seu interesse recuperar perfis de clientes usando user_id, anonymous_id ou email_address. Para ativar vários índices, entre em contato com o suporte da Hightouch.
   
   
6. Use o mapeador de campos para especificar quais colunas do seu modelo devem ser incluídas na carga útil da resposta da API. Você pode renomear esses campos e usar o mapeador avançado para aplicar transformações usando a linguagem de modelo Liquid.
   
   
7. Selecione o comportamento de exclusão apropriado para o seu caso de uso.
   
   
8. Por fim, clique em Continue e depois selecione um cronograma de sincronização.

A Hightouch agora sincronizará os dados do seu warehouse para um banco de dados gerenciado e os exporá por meio da API de Personalização.

Etapa 4: Chamar a API de Personalização por meio do Conteúdo conectado da Braze

Depois de configurar sua instância da API de Personalização, você pode usá-la como um endpoint de Conteúdo conectado da Braze.

A API está acessível em https://personalization.{region}.hightouch.com, por exemplo, https://personalization.us-west-2.hightouch.com.

As informações estão disponíveis usando este endpoint /v1/collections/:collection_name/records/:index_key/:index_value.

Por exemplo, você poderia incluir este trecho em uma Campaign ou Canvas:

1
2
3
4
5
6
7
8
9
{% connected_content
     https://personalization.us-west-2.hightouch.com/v1/collections/customer/records/id/12345
     :method get
     :headers {
       "Authorization": "Bearer {{YOUR-API-KEY}}"
  }
     :content_type application/json
     :save customer
%}

Você pode usar a modelagem Liquid para referenciar as propriedades retornadas na carga útil JSON e usá-las no seu envio de mensagens.

Para a carga útil de exemplo abaixo:

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
{
    "user_id": 12345,
    "full_name": "Jane Doe",
    "lifetime_value": 1492.18,
    "churn_risk": 0.04,
    "90_day_summary": {
        "num_songs_listened": 813,
        "top_genres": [
            "house",
            "techno",
            "ambient"
        ],
        "top_artists": [
            "deadmau5",
            "Marsh",
            "Enamour"
        ]
    },
    "recommendations": {
        "concerts": [
            {
                "artist": "Aphex Twin",
                "location": "San Francisco, CA",
                "event_date": "2023-01-31"
            },
            {
                "artist": "Sultan + Shepard",
                "location": "San Francisco, CA",
                "event_date": "2023-02-25"
            }
        ],
        "upcoming_album_release": {
            "title": "Universal Language",
            "artist": "Simon Doty",
            "label": "Anjunadeep",
            "release_date": "2023-04-28"
        }
    }
}

As seguintes referências Liquid retornariam estes dados de exemplo:

Solução de problemas

Se você tiver dúvidas, entre em contato com o suporte da Hightouch para obter assistência.