Notifications & templates

Captain Metrics a la particularité de pouvoir envoyer des notifications multi-canal (email, SMS, push...) et multi-lingues (FR, EN, DE...).

Pour cette raison, avant de pouvoir créer un template qui va définir le contenu du message, il faudra créer une "Notification" pour spécifier sur quels canaux elle peut être transmise et dans quelles langues.

On devra ensuite créer un template pour chaque canal et chaque traduction.

Exemple : si une notification "Abandon de panier" est disponible par email et SMS, en Anglais et en Français, elle devra contenir 4 templates : email-en, email-fr, sms-en, sms-fr.

Si la langue du profil de votre utilisateur n'a pas de traduction disponible lors de l'envoi du message, la langue par défaut de votre projet sera choisie.

Templates

Puisque chaque canal de notification a ses particularités, les formulaires de création des templates sont différents pour chaque canal (email, sms...).

Mais dans l'ensemble vous trouverez toujours :

• un éditeur de contenu

• un éditeur des données de test pour la personnalisation au format JSON

• un aperçu de votre contenu utilisant les données de test

Si vous n'êtes pas un développeur, bonne nouvelle : le templating n'est pas vraiment de la programmation, n'ayez pas peur, ce n'est pas compliqué !

Pour vous aidez à personnaliser le plus finement possible vos templates, vous pouvez utiliser le langage de templating Nunjucks (même syntaxe que Twig, Jinja2...).

Lors de l'envoi d'une notification à un utilisateur, un objet de variables JSON contenant le profil de l'utilisateur destinataire est transmis à votre template via la propriété user.

De cette façon, vous pouvez écrire dans votre template : Bonjour {{ user.firstName }}

D'autres variables peuvent être présentes dans l'objet JSON lors de l'envoi des notifications (abandonedCart, enterSegment...) lorsqu'elles sont déclenchées par les Workflows.

Données de test

Lorsque vous créez votre template, vous allez utiliser des variables pour personnaliser le contenu de vos messages.

Et pour simuler l'aperçu du message qui sera transmis à vos utilisateurs, vous aurez besoin d'ajouter des données de test. Pour cela, il suffit d'ajouter un objet au format JSON dans la zone "Test data".

Syntaxe de templating

Données JSON

Le JSON est un format cross-plateforme utilisé partout sur le web et particulièrement dans les API.

Un objet JSON commence toujours avec les "brackets" { } et les clés sont écrites entre double-guillemets comme ceci: {"key": "value"}. Les valeurs peuvent être des chaînes de caractères, des nombres, un autre objet JSON, un tableau, un booléen true/false ou null.

Les chaînes de caractères doivent être écrites entre double-guillemets comme ceci : {"monTexte": "Je suis un texte"}.

Les nombres ne sont pas écrits entre double-guillemets: {"monNombre": 10.5}.

Les objets JSON commencent avec des "brackets:" {"monObjet": {"key": "value"}}.

Les tableaux sont déclarés entre crochets, et peuvent contenir n'importe quel type de données JSON : {"monTableau":["a_string", 3, true]}.

Les booléens sont true ou false: {"winner": true}.

Variables

Nous allons maintenant apprendre quelques syntaxes pour le templating, en utilisant les données JSON suivantes pour exemple :

{
  "firstName": "John",
  "basket": {
    "banana": 7,
    "orange": 8
  },
  "tags": ["customer", "vip"]
}

Pour afficher une variable dans le template, il suffit la déclarer entre double-brackets comme ceci : Hello {{ firstName }}.

Pour accéder aux propriétés d'un objet JSON, vous pouvez soit utiliser un point . {{ basket.orange }} ou des crochets: {{ basket["orange"] }}.

Lorsque l'on utilise les crochets pour accéder à une propriété d'un objet JSON, il faut absolument mettre la clé entre double-guillemets, sinon le moteur de templating va interpréter la clé comme une variable.

Pour accéder aux valeurs d'un tableau, il faudra également utiliser les doubles crochets mais cette fois-ci la clé sera un nombre : l'index de la ligne a accéder. La première valeur d'un tableau se trouvera toujours à l'index 0. Exemple : {{ tags[0] }} affichera : customer.

Conditions

Et pour afficher une variable seulement si elle existe ? Nous avons besoin des conditions : {% if myCondition %} I'm in baby! {% endif %}

Le contenu présent à l'intérieur du bloc if / endif s'affichera uniquement si la condition est valide. Vous pouvez utiliser les opérateurs logiques et de comparaison : and or not == != > >= < <=, ainsi que des parenthèses pour grouper les expressions.

Il est possible de chaîner autant de conditions que vous le souhaitez avec le bloc {% elif condition %} (elif signifie "else-if") et finir par {% else %} ... {% endif %} comme ceci :

{% if user.isCustomer %} ... {% endif %}

{% if not user.isCustomer %} ... {% endif %}

{% if comments|length > 5 %} ... {% endif %}

{% if order.payment == "creditcard" and order.total > 1000 %}
      ...
{% elif (x > 5 or y > 5) and not user.isMad %}
      ...
{% else %}
      ...
{% endif %}

Boucles

Pour personnaliser vos templates en affichant par exemple une liste de nouveaux produits vous allez devoir faire une boucle sur un tableau. Utilisons le JSON suivant pour exemple :

{
  "products": [
    {"name": "Bike", "price": 150},
    {"name": "Skateboard", "price": 70}
  ]
}

Pour boucler sur une liste, on va utiliser le bloc {% for item in items %} ... {% endfor %} comme ceci :

{% for product in products %}
  - {{ product.name }} at {{product.price}} USD!
{% else %}
  The "else" can be used to say something if your list is empty
  i.e: there is no new products...
{% endfor %}

Il est aussi possible de boucler sur les propriété d'un objet JSON avec : {% for key, value in myObject %} ... {% endfor %}.

Nunjucks fournit aussi 2 fonctions utiles pour améliorer vos boucles : range & cycler.

The range([start], stop, [step]) function returns an array with a defined length:

{% for i in range(0, 5) %}
  {{ i }} is gonna be: 0, 1, 2, 3, 4 
{% endfor %}

The cycler(item1, item2, ...itemN) function is often used 
to create invoices with even/odd table rows:

{% set cls = cycler("odd", "even") %}

{% for row in rows %}
  <div class="{{ cls.next() }}">{{ row.name }}</div>
{% endfor %}

Commentaires

Pour placer des commentaires dans vos templates, qui seront supprimés lors de la compilation du message, il faut utiliser un bloc avec hash : {# my beautiful comment... #}

Contrôle des espaces vides

Le moteur de templating affichera tous les caractères qui ne font pas partie de la syntaxe de templating y compris les retours à la lignes et espaces.

Il est indispensable parfois de ne pas insérer des retours à la lignes inutiles, surtout lorsque l'on envoie un SMS ou un email au format texte.

Vous pouvez indiquer au moteur de templating de retirer les retours à la lignes et espaces vides en ajoutant un signe négatif (-) lors de l'ouverture et la fermeture d'un bloc. Exemple :

{% for i in [1,2,3,4,5] -%}
    {{ i }}
{%- endfor %}

Le résultat exact de l'exemple ci-dessus sera 12345, sans retours à la ligne. L'instruction -%} supprime les espaces après l'ouverture bloc et {%- supprime les espaces avant la fermeture du bloc.

Filtres

Pour faciliter le formattage des données, Nunjucks fournit certains filtres.

Exemple : {{ article.description|truncate(100) }} va découper le texte pour seulement garder les 100 premiers caractères et ajouter "..." à la fin.

Quelques filtres utiles :

Filtre	Description
​batch​	Permet de créer un batch d'après un tableau. Exemple : afficher 3 produits par ligne dans votre newsletter.
​capitalize​	Transforme la première lettre d'un mot en lettre capitale.
​escape​	Converti les caractères &, <, >, ‘, et ” pour qu'ils ne soient pas interprétés comme du HTML.
​format​	Applique un formattage des caractères à un objet en utilisant la syntaxe du langage python.
​groupby​	Groupe une liste d'objets par un clé commune. Exemple : vous souhaitez grouper et afficher des produits par catégorie.
​join​	Retourne une chaîne de caractère en concaténant un tableau. Exemple : vous souhaitez convertir un tableau de tags en : tag1,tag2,tag3
​length​	Retourne la taille d'un tableau ou le nombre de clés d'un objet. Exemple: vous souhaitez afficher le nombre total de commentaires...
​random​	Retourne une entrée aléatoire d'un tableau.
​round​	Arrondi un nombre pour une précision donnée. Permet d'éviter les nombres à ralonge après avoir fait un calcul.
​safe​	Permet à une variable d'être interprétée comme du HTML.
​title​	Transforme la première lettre de chaque mot d'une phrase en lettre capitale.
​truncate​	Découpe un mot pour n'en garder que les premiers caractères.
​upper​	Converti tout un mot en lettres capitales.
​urlencode​	Encode et transforme les variables pour pouvoir être injectée proprement dans des paramètres d'URL.