Syntaxe de personnalisation personalization-syntax

Sur cette page : découvrez la syntaxe de personnalisation Handlebars et PQL dans Adobe Journey Optimizer, y compris les règles générales, les mots-clés réservés, la coercition de type, les espaces de noms disponibles et les bonnes pratiques.

Dans Journey Optimizer, Personalization utilise deux syntaxes complémentaires qui fonctionnent ensemble dans la même expression :

Comprendre dans quel contexte vous vous trouvez est essentiel pour éviter les erreurs d’exécution. Par exemple, un appel de fonction PQL placé dans {{...}} échouera, car Handlebars tente de le résoudre en tant qu’assistant plutôt que de l’évaluer en tant qu’expression PQL.

Exemples :

La structure des attributs est définie dans un schéma XDM Adobe Experience Platform. En savoir plus.

Règles générales de syntaxe general-rules

Mots-clés réservés reserved-keywords

Certains mots-clés sont réservés dans PQL (Profile Query Language) et ne peuvent pas être utilisés directement comme noms de champ ou de variable dans les expressions de personnalisation. Si votre schéma XDM contient des champs dont les noms correspondent à des mots-clés réservés, vous devez leur appliquer une séquence d’échappement à l’aide d’accents graves (`) pour les référencer dans vos expressions.

Les mots-clés réservés sont les suivants :

Exemple :

Si votre schéma de profil comporte un champ nommé next, vous devez l’encadrer de guillemets inversés :

{{profile.person.`next`.name}}

Sans les guillemets inversés, l’éditeur de personnalisation échouera lors de la validation et vous obtiendrez une erreur.

Règles de syntaxe PQL pour les clés d’attribut spéciales pql-special-keys

Au-delà des mots-clés réservés, deux cas supplémentaires nécessitent une séquence d’échappement dans les expressions PQL.

Clés d’attribut avec trait d’union hyphenated-keys

Si votre schéma XDM contient des noms de champ avec des tirets (par exemple my-field, event-type) ou des noms commençant par ou contenant des chiffres, placez la clé avec des accents graves dans les expressions PQL :

{%= profile.events.`order-total` > 100 %}

Sans backticks dans une expression PQL, le trait d’union est interprété comme un opérateur de soustraction et provoque une erreur de syntaxe PQL.

Identifiants d’événement numériques dans les attributs contextuels numeric-event-ids

Lors du référencement d’attributs d’événement contextuels où l’identifiant d’événement est un nombre (par exemple, 1697323153), placez-le entre accents graves. Cela s’applique également aux fonctions internes telles que formatDate() :

{% let ts = formatDate(toDateTime(context.journey.events.`1697323153`.timestamp), "dd/MM/yyyy") %}
{{ts}}

Type coercition type-coercion

PQL est fortement typé. Lors de la comparaison ou de la transmission de valeurs, les deux côtés doivent être du même type. Cas courants :

Espaces de noms disponibles namespaces

Assistants helpers-all

Un assistant Handlebars est un identifiant simple qui peut être suivi de paramètres. Chaque paramètre est une expression Handlebars. Ces assistants sont accessibles depuis n’importe quel contexte dans un modèle.

Ces assistants de bloc sont identifiés par un # placé devant le nom de l’assistant et une / correspondante doit être placée à la fin avec le même nom.

Les blocs sont des expressions qui ont une ouverture ({{# }}) et une fermeture ({{/}}) de bloc.

Pour plus d’informations sur les fonctions d’assistance, consultez cette section.

Types littéraux literal-types

Adobe Journey Optimizer prend en charge les types littéraux suivants :

Bonnes pratiques best-practices

Consultez ces règles de syntaxe avant de créer des expressions de personnalisation. La plupart des erreurs d’exécution proviennent du mélange des contextes Handlebars et PQL.

Utilisez la syntaxe correcte du bloc conditionnel

Utilisez toujours {%#if%} / {%else if%} / {%else%} / {%/if%}. La syntaxe {% if %} / {% elseif %} / {% endif %} n’est pas prise en charge.

{%#if profile.loyalty.tier = "gold"%}
Gold member content
{%else if profile.loyalty.tier = "silver"%}
Silver member content
{%else%}
Default content
{%/if%}

N’appelez pas les fonctions PQL dans {{...}} blocs Handlebars

{{...}} résout uniquement les variables Handlebars et les assistants ; il n’évalue pas PQL. Encapsuler une fonction PQL comme upperCase() dans {{...}} provoque une erreur « impossible de trouver un helper ». Utilisez plutôt {%= ... %} :

Utiliser un alias de boucle nommé lors de la combinaison de {{#each}} avec{%#if%}

this.field est résolu par le rendu Handlebars, mais pas par l’évaluateur PQL dans une condition de {%#if%}. Définissez un alias nommé avec as |item| afin que les deux contextes puissent résoudre le champ :

{{#each profile.orders as |order|}}
  {%#if order.status = "pending"%}
  Order {{order.id}} is pending.
  {%/if%}
{{/each}}

Attribuer les résultats de la fonction PQL à une variable avant la boucle

Les champs définis par l’utilisateur PQL tels que topN ne peuvent pas être appelés directement dans {{#each}}. Évaluez-les d’abord avec {% let %}, puis effectuez une itération sur le résultat :

{% let topOrders = topN(profile.orders, price, 3) %}
{{#each topOrders}}
  {{this.name}} — {{this.price}}€
{{/each}}

Utilisez {% let %} pour éviter de répéter les appels de fonction

Lorsqu’une valeur calculée est nécessaire plusieurs fois, stockez-la dans une variable. Cela améliore la lisibilité et évite les évaluations redondantes :

{% let cleanName = replaceAll(profile.person.name.firstName, "[^a-zA-Z]", "") %}
Hi {{cleanName}}, your code is: WELCOME-{%= upperCase(cleanName) %}

Utiliser l’ordre d’argument correct pourdateDiff

dateDiff(start, end) prend la date antérieure en premier. Pour calculer le nombre de jours restants jusqu’à une date ultérieure, transmettez la date actuelle comme premier argument :

{% let daysLeft = dateDiff(getCurrentZonedDateTime(), stringToDate(profile.loyalty.expiryDate)) %}

Utilisez = pour les comparaisons d’égalité dans PQL, et non==.

PQL utilise un seul opérateur = pour l’égalité. L’utilisation de == entraîne une erreur de syntaxe.

Utilisez des accents graves pour les noms de champ avec trait d’union — dans les expressions PQL uniquement

Si un nom de champ de schéma XDM contient un trait d’union (par exemple, order-total), placez-le dans des accents graves pour empêcher le trait d’union d’être analysé en tant qu’opérateur de soustraction. Elle est uniquement prise en charge dans les expressions {%= ... %} PQL, et non dans les blocs Handlebars {{...}} :

{%= profile.events.`order-total` > 100 %}

Pour les expressions prêtes à l’emploi que vous pouvez copier directement dans votre contenu, consultez Recettes ​.