API de personalización de Hightouch

La API de personalización de Hightouch es un servicio gestionado que te permite alojar una API de datos de baja latencia basada en cualquier conjunto de datos de tu almacén de datos en la nube.

La integración de Braze y Hightouch te permite utilizar la API con Contenido conectado de Braze para extraer datos actualizados de clientes u objetos en tus Campaigns o Canvas en el momento del envío.

La API de personalización de Hightouch proporciona un punto de conexión REST para utilizar en tu configuración de Braze. En concreto, puedes utilizar la oferta de Contenido conectado de Braze para realizar una solicitud GET a la API de personalización y recuperar toda la información relacionada con un identificador concreto. Los datos expuestos por esta API pueden representar datos de clientes, productos o cualquier otro objeto.

Requisitos previos

• use cases
• datasets

Integración

Paso 1: Conectar el origen de datos a Hightouch

Las fuentes de Hightouch son el lugar donde residen los datos empresariales de tu organización. En este caso, es dondequiera que se almacenen los datos de tus usuarios.

1. En Hightouch, ve a Sources Overview > Add Source. Selecciona tu almacén de datos como fuente.
   
   
2. Introduce las credenciales pertinentes; estas variarán en función de la fuente.

Para más detalles, consulta la documentación de la fuente correspondiente.

Paso 2: Modelar los datos

Los modelos de Hightouch definen qué datos extraer de tu fuente. Para configurar un nuevo modelo, sigue estos pasos:

1. En Hightouch, ve a Models overview > Add model y selecciona la fuente que acabas de conectar.
   
   
2. A continuación, elige un método de modelado. Como toda tu información debe estar unida en una sola tabla, puedes utilizar el selector visual de tablas para definirla. Como alternativa, puedes escribir SQL para incluir solo las columnas que desees o basarte en tus modelos dbt, Looker Looks o libros de trabajo Sigma existentes.
   
   
3. Antes de continuar, previsualiza tu modelo para asegurarte de que consulta los datos que te interesan. Por defecto, Braze limita la vista previa a los 100 primeros registros. Una vez validados los datos, haz clic en Continue.
   
   
4. Nombra tu modelo, por ejemplo, “Recomendaciones de usuarios”.
   
   
5. Por último, selecciona una clave primaria y haz clic en Finish. Una clave primaria debe ser una columna con identificadores únicos. Este es también el campo que utilizarás para llamar a la API de personalización y recuperar las recomendaciones de un usuario en particular.

Paso 3: Configurar la API de personalización

Preparar la API para recibir solicitudes tiene dos pasos:

• Habilitar la API de personalización en las regiones más cercanas a tu infraestructura
• Crear sincronizaciones para definir qué modelos deben materializarse en la caché gestionada por Hightouch

Sigue estas instrucciones para completar ambos:

1. En Hightouch, ve a Destinations y selecciona la API de personalización de Hightouch creada para ti. Si no tienes habilitado este destino, ponte en contacto con el soporte de Hightouch.
   
   
2. A continuación, selecciona la región adecuada. Seleccionar la región más cercana a tu infraestructura reducirá tus tiempos de respuesta. Si no ves una región cercana a tu infraestructura, ponte en contacto con el soporte de Hightouch.
   
   
3. Ve a la página de resumen de Syncs y haz clic en el botón Add sync. A continuación, selecciona el modelo correspondiente y el destino que hayas configurado previamente.
   
   
4. Introduce un nombre alfanumérico para la colección. Las colecciones son conceptualmente similares a las tablas de las bases de datos. Cada una debe representar un tipo de datos concreto, como clientes o facturas. Los nombres de las colecciones deben ser alfanuméricos y formarán parte de tu punto de conexión de la API de personalización.
   
   
5. A continuación, especifica qué columna de tu modelo debe servir como índice primario para las búsquedas de registros. Este campo debe identificar de forma exclusiva cada registro de la colección y suele coincidir con la clave primaria de tu modelo. La API de personalización admite búsquedas en varios índices. Por ejemplo, puede que quieras recuperar perfiles de clientes utilizando user_id, anonymous_id o email_address. Para activar varios índices, ponte en contacto con el soporte de Hightouch.
   
   
6. Utiliza el mapeador de campos para especificar qué columnas de tu modelo deben incluirse en la carga útil de la respuesta de la API. Puedes cambiar el nombre de estos campos y utilizar el mapeador avanzado para aplicar transformaciones utilizando el lenguaje de plantillas Liquid.
   
   
7. Selecciona el comportamiento de eliminación adecuado para tu caso de uso.
   
   
8. Por último, haz clic en Continue y selecciona un calendario de sincronización.

Hightouch sincronizará ahora los datos de tu almacén con una base de datos gestionada y los expondrá a través de la API de personalización.

Paso 4: Llamar a la API de personalización a través del Contenido conectado de Braze

Una vez que hayas configurado tu instancia de la API de personalización, puedes utilizarla como un punto de conexión de Contenido conectado de Braze.

Se puede acceder a la API en https://personalization.{region}.hightouch.com, por ejemplo, https://personalization.us-west-2.hightouch.com.

La información está disponible utilizando este punto de conexión /v1/collections/:collection_name/records/:index_key/:index_value.

Por ejemplo, puedes incluir este fragmento en una Campaign o 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
%}

Puedes utilizar plantillas Liquid para hacer referencia a las propiedades devueltas en la carga útil JSON y utilizarlas en tu mensajería.

Para el siguiente ejemplo de carga útil:

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"
        }
    }
}

Las siguientes referencias de Liquid devolverían estos datos de ejemplo:

Solución de problemas

Si tienes alguna pregunta, ponte en contacto con el soporte de Hightouch para obtener ayuda.