Utiliser des personnalisations de boucle

Si vous voulez envoyer des confirmations de commande ou des rappels de paniers abandonnés, vous aurez certainement besoin d'afficher plusieurs objets à la suite. C'est là que les boucles de personnalisations sont très pratiques !

Les boucles sont en effet très utiles quand vous devez personnaliser sur base de plusieurs lignes de données.

Au lieu que la variable d'une personnalisation soit remplacée par une seule valeur, il est ainsi possible d'afficher :

• Un ensemble de valeurs liées (par exemple, le nom de l'article et le montant associé)

• Plusieurs de ces ensembles les uns à la suite des autres (par exemple, les 3 derniers achats, chacun caractérisés par le nom de l'article et le montant)

Les boucles sont disponibles aussi bien dans les e-mails marketing que dans les e-mails transactionnels.

Format de l'e-mail

La manière d'insérer une boucle dépend de si vous créez votre e-mail avec l'éditeur de templates ou en important un HTML.

Boucles dans l'éditeur de template

Les personnalisations de boucle peuvent être utilisées dans un template au moyen de blocs de boucle spécifiques.

Ces blocs compatibles sont identifiables grâce à l'icône "boucle" quand vous les sélectionnez, à côté de l'icône des conditions.

Il y a deux moyens de les insérer :

• Depuis un template de design personnalisé : si vous avez commandé un template créé par les équipes Actito, vous pouvez avoir demandé un bloc de boucles directement dans le template.

• Depuis la librairie de modules : dans tous les autres templates, vous pouvez utiliser la librairie de modules, où une sélection de blocs de boucles est disponibles avec différents designs (avec images, boutons...)

Les blocs de la librairie de modules contiennent une boucle pré-définie portant le nom "item".

En cliquant sur l'icône de boucle dans le bloc, vous pouvez déclarer un autre nom pour votre boucle.

Le nom de la boucle est important, car chaque élément de la boucle doit suivre le format ${nom de la boucle.nom de l'élément}.

Par exemple, dans la capture d'écran ci-dessous, la boucle a été renommée "article", il faut donc également modifier les éléments de la boucle en ${article.title} and ${article.description}, où "title" et "description" sont des variables qui seront personnalisées chaque fois que la boucle sera répétée.

Certaines personnalisations sont déjà définies dans chaque bloc, mais vous pouvez les modifier, en suivant le format ${nom de la boucle.nom de l'élément}. Par exemple, ${article.prix}, ${article.quantite}...

Vous pouvez changer la mise en page et appliquer des effets de style aux éléments de votre boucle selon vos besoins.

Si vous fournissez des valeurs de personnalisation par API (cf. dernière section), vous devrez vous référer au nom technique de votre boucle dans votre appel, ce qui est : le nom déclaré dans le bloc de boucle suivat d'un suffixe S.

Par exemple, dans la boucle ci-dessus nommée "article", le nom technique appelé dans l'API serait "articles".

Boucles dans les imports HTML

Les personnalisations de boucle peuvent aussi être utilisées dans vos fichiers HTML importés en insérant le fragment de code dédié.

Il convient d'utiliser le paramètre "data-Actito-each" et de le définir comme "nom de la boucle : ${nom de la boucle au pluriel}". Par exemple : **data-Actito-each ="exemple:${exemples}"**

Chaque élément de la boucle devra suivre le format : ${nom de la boucle.nom de l'élément}. Par exemple : **${exemple.element}**

Prenons un exemple concret : Nous voulons afficher une boucle reprenant les derniers achats des profils contactés et affichant pour chacun d'eux le nom de l'article et son prix.

Le code à insérer devra prendre la forme suivante :

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

"Nom de la boucle au pluriel" est simplement une suggestion lors de la déclaration du second élément du paramètre "data-Actito-each". Vous pouvez déclarer un autre nom technique de votre choix, du moment qu'il est différent du premier élément.

Par exemple, data-Actito-each= "achat:${exemple}".

Néanmoins, veuillez le garder en mémoire si les valeurs de personnalisations sont poussées par API, car le nom déclaré dans la section entre ${ } sera utilisée pour référencer la boucle dans l'appel API.

Paramétrer la personnalisation

Une fois la boucle insérée dans un bloc spécifique ou dans l'HTML, il est nécessaire de paramétrer les différentes variables appelées par la boucle de personnalisation.

Pour ce faire, rendez vous dans la modale de gestion des personnalisations.

Pour accéder aux boucles, il est tout d'abord nécessaire d'activer le "Mode expert" en haut et à droite de l'écran. Une nouvelle section appelée "Personnalisations de boucle" va apparaître.

Les valeurs de chaque élément de la boucle pourront être fournies par deux types de sources :

• Des tables du modèle de donnée (tables personnalisées) : il faudra préalablement sélectionner la table concernée dans la section "Source de données".

• Via API : veuillez vous référer à la fin de ce chapitre pour davantage d'explication sur leur fonctionnement via API.

Si la section "Personnalisation de boucles" apparaît dans l'interface mais que rien ne s'affiche quand vous cliquez sur la petite flèche pour développer la case, cela signifie que le système a reconnu votre tentative de mettre en place une boucle, mais que votre html n'est pas correct. Vérifiez votre code, le nom de la boucle et des variables.

Valeurs de boucles depuis le modèle de données

Définir les valeurs

Une fois la source sélectionnée, vous pouvez définir les valeurs que vont prendre les variables de la boucle, via la section "Personnalisation de boucle".

Sélectionnez la source de données choisie à l'étape préliminaire et associez-la au nom de la boucle. Chaque boucle ne peut faire usage que d'une source de données.

Ensuite, associez les différents éléments de la boucle aux champs de la table source.

info

Si le nom d'une variable de boucle est identique au nom technique d'un attribut d'une table personnalisée, le mapping sera effectué automatiquement lorsque vous sélectionnerez la source de la table personnalisée dans la section 'Personnalisations de boucle'.

Définir le nombre d'éléments à afficher

En plus de permettre l'affichage d'un ensemble de valeurs, les boucles permettent également d'afficher plusieurs de ces ensembles les uns à la suite des autres.

Il est nécessaire de préciser le nombre d'éléments à afficher. En effet, sans paramétrisation additionnelle, la boucle va renvoyer tous les événements de la source de données.

Pour ce faire, il est nécessaire de se rendre dans les paramètres de la source de données, en cliquant sur l'engrenage tout à droite de la ligne de source.

Vous allez pouvoir sélectionner :

• Le nombre maximum d'élément à afficher.

• Sur base de quel attribut de la table source et dans quel ordre les éléments devront être ordonnés.

Il est également possible de d'ajouter un filtre à la source. Ainsi les seuls éléments de la source pris en compte seront ceux qui respectent le ou les critères que vous avez sélectionnés sur base des attributs de la table ou d'agrégats calculés sur ceux-ci.

Vous pouvez aussi choisir la donnée Fournie par le scénario : cette option est à choisir pour vos envois scénarisés lorsque le bloc de départ du scénario est en rapport avec la valeur de la personnalisation (Par exemple, si le scénario est déclenché par la création d'un ticket...). Vous serez alors certain que l'information qui a déclenché le scénario et l'information utilisée pour la personnalisation seront les mêmes.
Cette option est uniquement disponible dans le cadre d'un envoi scénarisé (y compris transactionnel).

Ensuite, enregistrez vos paramètres en haut à droite.

Un "V' vert sur l'engrenage vous confirmera que la source a été paramétrée.

Formatage des données

Les fonctions de formatage et de transformation des données peuvent être appliquées aux valeurs de boucle lorsque la source est une table personnalisée, notamment :

• Définir une valeur par défaut
• Définir un mapping
• Formater la date (pour les attributs de type "date" et "moment")
• Formater le nombre (pour les attributs de type "nombres réel")

Plus d'informations sur les fonctions de formatage sont disponibles ici

info

L'usage des boucles n'est pas possible avec des attributs multi-valeurs.

Boucles déclenchées par API

En plus des tables personnalisées, les sources de données peuvent également être fournies via appels API quand l'e-mail est déclenché par un système externe à Actito.

Pour utiliser les APIs comme source de données, il convient d'associer l'option "Fourni par API" à votre personnalisation de boucle dans la modale de gestion des personnalisations.

Lors de la dernière étape, veillez à bien "Activer l'envoi", pour le rendre déclenchable par API.

Tester les variables "fournies par API"

L'e-mail final étant déclenché via un appel API, il peut être pertinent d'effectuer des tests en collaboration avec un de vos développeurs.

Néanmoins, Actito vous donne la possibilité de tester vos e-mails directement dans l'interface, sans mobiliser de ressource technique.

En effet, si vous utiliser une personnalisation "fournie par API", un bouton additionnel va automatiquement apparaître à l'étape de "Contrôle et test".

Il vous permet de simuler des valeurs de test pour vos personnalisations, de sorte que vos e-mails de test aient bien des données pour tester leur rendu final.

Ces données sont stockées dans le cache de votre navigateur. Elles n'apparaissent donc pas si une autre utilisateur modifie la campagne ou si vous changez de session.

Déclencher un e-mail par API

Pour déclencher un e-mail et pousser des personnalisations de boucle par API, l'appel à utiliser dépend du type d'e-mail :

• Pour les e-mails scénarisés standards (tels que les rappels de paniers abandonnés, utilisez l'appel POST /entity/{e}/mail/{m}/profile/{p}

• Pour les e-mails transactionnels (tels que les confirmations de commande), utilisez l'appel POST /entity/{e}/transactionalmail/{m}/contact

Les paramètres à renseigner pour ces appels sont :

• L'entité sur laquelle la campagne est enregistrée

• L'identifiant de la campagne (id auto-généré ou nom technique)

• L'identifiant du profil visé :

  • dans le path de l'appel s'il s'agit d'un e-mail scénarisé standard

  • dans le corps de l'appel pour un e-mail transactionnel, car le profil peut être créé/MAJ en même temps dans ce cas

• Des variables :

  • Pour les e-mails scénarisés, le corps de l'appel est juste un ensemble contenant les valeurs de personnalisations.

  • Pour les e-mails transactionnels, le corps de l'appel contient à la fois une section "profile" où pousser les valeurs pour créer/MAJ ce profil, et un ensemble "parameters" contenant les valeurs de personnalisations.

Cet appel vous permet de soumettre les variables liées aux personnalisations de boucle de votre e-mail transactionnel.
L'ensemble "parameters" devra être composé de :

• "key"" : Il faut toujours indiquer "externalData" pour déclencher une boucle par API

• "structuredValue"" : L'utilisation du paramètre "structuredValue" est obligatoire pour utiliser une boucle, à l'inverse des personnalisations standard ou des "values" simples sont poussées. La "structuredValue" est un objet contenant le "nom technique" de la boucle. Ce nom technique dépend de la manière dont vous avez déclaré la boucle dans votre e-mail :

  • Si vous l'avez insérée dans votre code HTML, il s'agit du second élément dans la déclaration de la boucle : la valeur entre accolades. Il s'agit de "achats" dans le fragment suivant : data-Actito-each="achat:${achats}".

  • Si vous avez inséré votre boucle dans un bloc de template, il s'agit du nom de la boucle tel que défini dans l'éditeur, avec un suffixe S. Avec sa boucle suivante, nommée "achat" dans l'éditeur, la valeur utilisée dans l'API serait "achats".

Vous pouvez ensuite définir un ensemble d'objets contenant les éléments de la boucle sous forme de paires "nomElement":"valeur".

La boucle sera répétée pour chaque objet poussé dans l'ensemble, avec les valeurs adaptées.

Exemple de code JSON

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

Astuce

Les personnalisations simples (qui ne font pas partie d'une boucle) sont poussées via des paires "key" - "values", où "key" est le nom de la variable tel que définis dans l'e-mail.

Vous pouvez vous référer au 'request sample' de l'appel pour déclencher un e-mail transactionnel pour un bon exemple de comment pousser à la fois les personnalisations simples et les boucles dans le même appel (+ les attributs pour créer/MAJ le profil dans le cadre d'un e-mail transactionnel).