Utilizando Personalizaciones de Bucle

Si desea enviar confirmaciones de pedido o recordatorios de carritos abandonados, seguramente necesitará mostrar varios objetos en secuencia. ¡Aquí es donde las personalizaciones de bucle son muy útiles!

Los bucles son extremadamente útiles cuando necesita personalizar en base a varias líneas de datos.

En lugar de que la variable de una personalización sea reemplazada por un solo valor, es posible mostrar:

• Un conjunto de valores relacionados (por ejemplo, el nombre del artículo y el monto asociado)

• Varios de estos conjuntos uno tras otro (por ejemplo, las últimas 3 compras, cada una caracterizada por el nombre del artículo y el monto)

Consejo

Los bucles están disponibles tanto en correos electrónicos de marketing como en correos electrónicos transaccionales.

Formato del correo electrónico

La forma de insertar un bucle depende de si está creando su correo electrónico con el editor de plantillas o importando un HTML.

Bucles en el editor de plantillas

Las personalizaciones de bucle se pueden utilizar en una plantilla mediante bloques de bucle específicos.

Estos bloques compatibles se pueden identificar por el icono de "bucle" cuando los selecciona, junto al icono de las condiciones.

Hay dos formas de insertarlos:

• Desde una plantilla de diseño personalizado: si ha solicitado una plantilla creada por los equipos de Actito, es posible que haya solicitado un bloque de bucles directamente en la plantilla.

• Desde la biblioteca de módulos: en todas las demás plantillas, puede utilizar la biblioteca de módulos, donde hay una selección de bloques de bucles disponibles con diferentes diseños (con imágenes, botones...)

Los bloques de la biblioteca de módulos contienen un bucle predefinido llamado "item".

Al hacer clic en el ícono de bucle en el bloque, puedes declarar otro nombre para tu bucle.

El nombre del bucle es importante, ya que cada elemento del bucle debe seguir el formato ${nombre del bucle.nombre del elemento}.

Por ejemplo, en la captura de pantalla a continuación, el bucle se ha renombrado como "article", por lo tanto, también debes modificar los elementos del bucle a ${article.title} y ${article.description}, donde "title" y "description" son variables que se personalizarán cada vez que se repita el bucle.

Algunas personalizaciones ya están definidas en cada bloque, pero puedes modificarlas siguiendo el formato ${nombre del bucle.nombre del elemento}. Por ejemplo, ${article.prix}, ${article.quantite}...

Puedes cambiar el diseño y aplicar efectos de estilo a los elementos de tu bucle según tus necesidades.

info

Si proporcionas valores de personalización a través de una API (ver última sección), debes hacer referencia al nombre técnico de tu bucle en tu llamada, que es: el nombre declarado en el bloque de bucle seguido de un sufijo S.

Por ejemplo, en el bucle anterior llamado "article", el nombre técnico llamado en la API sería "articles".

Bucles en las importaciones HTML

Las personalizaciones de bucle también se pueden utilizar en tus archivos HTML importados insertando el fragmento de código dedicado.

Debes usar el parámetro "data-Actito-each" y establecerlo como "nombre del bucle: ${nombre del bucle en plural}". Por ejemplo: **data-Actito-each ="ejemplo:${ejemplos}"**

Cada elemento del bucle debe seguir el formato: ${nombre del bucle.nombre del elemento}. Por ejemplo: **${ejemplo.elemento}**

Tomemos un ejemplo concreto: Queremos mostrar un bucle que muestre las últimas compras de los perfiles contactados y muestre para cada una de ellas el nombre del artículo y su precio.

El código a insertar debe tener la siguiente forma:

data-Actito-each
<div data-Actito-each=``"achat:${achats}"``>
<span> Article : ${achat.article} </span>
<span> Prix : ${achat.prix} €</span>
</div>

Consejo

"Nombre del bucle en plural" es simplemente una sugerencia al declarar el segundo elemento del parámetro "data-Actito-each". Puedes declarar otro nombre técnico de tu elección, siempre y cuando sea diferente al primer elemento.

Por ejemplo, data-Actito-each= "compra:${ejemplo}".

Sin embargo, tenlo en cuenta si los valores de personalización son impulsados por API, ya que el nombre declarado en la sección entre ${ } se utilizará para hacer referencia al bucle en la llamada a la API.

Configurando la personalización

Una vez que el bucle se ha insertado en un bloque específico o en el HTML, es necesario configurar las diferentes variables llamadas por el bucle de personalización.

Para hacer esto, ve a la modalidad de gestión de personalizaciones.

Para acceder a los bucles, primero es necesario activar el "Modo experto" en la parte superior derecha de la pantalla. Aparecerá una nueva sección llamada "Personalizaciones de bucle".

Los valores de cada elemento del bucle pueden ser proporcionados por dos tipos de fuentes:

• Tablas del modelo de datos (tablas personalizadas): primero deberás seleccionar la tabla correspondiente en la sección "Fuente de datos".

• A través de la API: consulta el final de este capítulo para obtener más explicaciones sobre su funcionamiento a través de la API.

Consejo

Si la sección "Personalización de bucles" aparece en la interfaz pero no se muestra nada cuando haces clic en la flecha para expandir el cuadro, significa que el sistema reconoció tu intento de configurar un bucle, pero tu HTML no es correcto. Verifica tu código, el nombre del bucle y las variables.

Valores de bucles desde el modelo de datos

Definir los valores

Una vez seleccionada la fuente, puedes definir los valores que tomarán las variables del bucle a través de la sección "Personalización de bucle".

Selecciona la fuente de datos elegida en el paso preliminar y asígnala al nombre del bucle. Cada bucle solo puede utilizar una fuente de datos.

Luego, asocia los diferentes elementos del bucle a los campos de la tabla fuente.

info

Si el nombre de una variable de bucle es el mismo que el nombre técnico de un atributo de una tabla personalizada, la asignación se realizará automáticamente cuando seleccione la fuente de la tabla personalizada en la sección 'Personalizaciones de bucle'.

Definir el número de elementos a mostrar

Además de permitir la visualización de un conjunto de valores, los bucles también permiten mostrar varios de estos conjuntos uno tras otro.

Es necesario especificar el número de elementos a mostrar. De hecho, sin una configuración adicional, el bucle devolverá todos los eventos de la fuente de datos.

Para hacer esto, debes ir a la configuración de la fuente de datos, haciendo clic en el engranaje a la derecha de la línea de la fuente.

Podrás seleccionar:

• El número máximo de elementos a mostrar.

• Sobre qué atributo de la tabla fuente y en qué orden se deben ordenar los elementos.

También es posible agregar un filtro a la fuente. De esta manera, solo se tendrán en cuenta los elementos de la fuente que cumplan con los criterios que hayas seleccionado en función de los atributos de la tabla o de los agregados calculados en ellos.

Consejo

También puedes seleccionar el dato Proporcionado por el escenario: esta opción se elige para tus envíos escenificados cuando el bloque de inicio del escenario está relacionado con el valor de personalización (Por ejemplo, si el escenario es desencadenado por la creación de un ticket...). Entonces estarás seguro de que la información que desencadenó el escenario y la información utilizada para la personalización serán las mismas.
Esta opción solo está disponible en el marco de un envío escenificado (incluido el transaccional).

Luego, guarda tus ajustes en la parte superior derecha.

Un "V" verde en el engranaje te confirmará que la fuente ha sido configurada.

Formato de datos

Las funciones de transformación y formato de datos se pueden aplicar a valores de bucle cuando el origen es una tabla personalizada, que incluye:

• Definición del valor predeterminado
• Definición de un mapeo
• Formatear la fecha (para fechas y atributos de marca de tiempo)
• Formatear el número (para atributos de números reales)

Más información sobre las funciones de formato está disponible aquí

info

No es posible utilizar bucles con atributos de múltiples valores.

Bucles desencadenados por API

Además de las tablas personalizadas, las fuentes de datos también pueden ser proporcionadas a través de llamadas API cuando el correo electrónico es desencadenado por un sistema externo a Actito.

Para utilizar las APIs como fuente de datos, debes asociar la opción "Proporcionado por API" a tu personalización de bucle en el modal de gestión de personalizaciones.

En el último paso, asegúrate de "Activar el envío" para que sea desencadenable por API.

Probar las variables "proporcionadas por API"

Dado que el correo electrónico final es desencadenado mediante una llamada API, puede ser relevante realizar pruebas en colaboración con uno de tus desarrolladores.

Sin embargo, Actito te brinda la posibilidad de probar tus correos electrónicos directamente en la interfaz, sin necesidad de recursos técnicos.

En efecto, si utilizas una personalización "proporcionada por API", se mostrará automáticamente un botón adicional en la etapa de "Control y prueba".

Esto te permite simular valores de prueba para tus personalizaciones, de modo que tus correos electrónicos de prueba tengan datos para probar su renderizado final.

Estos datos se almacenan en la caché de tu navegador. Por lo tanto, no aparecerán si otro usuario modifica la campaña o si cambias de sesión.

Disparar un correo electrónico mediante API

Para disparar un correo electrónico y enviar personalizaciones de bucle mediante API, la llamada a utilizar depende del tipo de correo electrónico:

• Para correos electrónicos escenificados estándar (como recordatorios de carritos abandonados), utiliza la llamada POST /entity/{e}/mail/{m}/profile/{p}

• Para correos electrónicos transaccionales (como confirmaciones de pedido), utiliza la llamada POST /entity/{e}/transactionalmail/{m}/contact

Los parámetros que debes proporcionar para estas llamadas son:

• La entidad en la que se registra la campaña

• El identificador de la campaña (id auto-generado o nombre técnico)

• El identificador del perfil objetivo:

  • en la ruta de la llamada si se trata de un correo electrónico escenificado estándar

  • en el cuerpo de la llamada para un correo electrónico transaccional, ya que el perfil puede ser creado/actualizado al mismo tiempo en este caso

• Variables:

  • Para correos electrónicos escenificados, el cuerpo de la llamada es simplemente un conjunto que contiene los valores de personalización.

  • Para correos electrónicos transaccionales, el cuerpo de la llamada contiene tanto una sección "profile" donde se empujan los valores para crear/actualizar este perfil, como un conjunto "parameters" que contiene los valores de personalización.

Este llamado le permite enviar las variables relacionadas con las personalizaciones del bucle de su correo transaccional.
El conjunto "parameters" debe estar compuesto por:

• "key"" : Siempre debe indicar "externalData" para activar un bucle a través de la API.

• "structuredValue"" : El uso del parámetro "structuredValue" es obligatorio para utilizar un bucle, a diferencia de las personalizaciones estándar o los "values" simples que se envían. El "structuredValue" es un objeto que contiene el "nombre técnico" del bucle. Este nombre técnico depende de cómo haya declarado el bucle en su correo electrónico:

  • Si lo ha insertado en su código HTML, es el segundo elemento en la declaración del bucle: el valor entre llaves. En el siguiente fragmento, es "achats": data-Actito-each="achat:${achats}".

  • Si ha insertado su bucle en un bloque de plantilla, es el nombre del bucle tal como se define en el editor, con un sufijo S. Con su bucle siguiente, llamado "achat" en el editor, el valor utilizado en la API sería "achats".

Luego puede definir un conjunto de objetos que contengan los elementos del bucle como pares "nomElement":"valeur".

El bucle se repetirá para cada objeto enviado en el conjunto, con los valores correspondientes.

Ejemplo de código JSON

[
  {
    "key": "externalData",
    "structuredValue": {
      "items": [
        {
          "article": "Screwdriver",
          "price": "25"
        },
        {
          "article": "Hammer",
          "price": "32"
        }
      ]
    }
  }
]

Consejo

Las personalizaciones simples (que no forman parte de un bucle) se envían a través de pares "key" - "values", donde "key" es el nombre de la variable tal como se define en el correo electrónico.

Puede consultar el 'request sample' de la llamada para activar un correo electrónico transaccional para ver un buen ejemplo de cómo enviar tanto personalizaciones simples como bucles en la misma llamada (+ los atributos para crear/actualizar el perfil en el contexto de un correo electrónico transaccional).