Sintassi di personalizzazione personalization-syntax

In questa pagina: Scopri la sintassi di personalizzazione Handlebars e PQL in Adobe Journey Optimizer, incluse le regole generali, le parole chiave riservate, la coercizione del tipo, gli spazi dei nomi disponibili e le best practice.

Personalization in Journey Optimizer utilizza due sintassi complementari che funzionano insieme nella stessa espressione:

Per evitare errori di runtime, è fondamentale capire in quale contesto ci si trova. Ad esempio, una chiamata di funzione PQL inserita all’interno di {{...}} avrà esito negativo perché Handlebars tenta di risolverla come helper anziché valutarla come espressione di PQL.

Esempi:

La struttura degli attributi è definita in uno schema XDM di Adobe Experience Platform. Ulteriori informazioni.

Regole generali di sintassi general-rules

Parole chiave riservate reserved-keywords

Alcune parole chiave sono riservate in Profile Query Language (PQL) e non possono essere utilizzate direttamente come nomi di campi o variabili nelle espressioni di personalizzazione. Se lo schema XDM contiene campi con nomi che corrispondono a parole chiave riservate, è necessario eseguirne l’escape utilizzando apici inversi (`) per farvi riferimento nelle espressioni.

Le parole chiave riservate includono:

Esempio:

Se lo schema del profilo dispone di un campo denominato next, è necessario racchiuderlo in apici:

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

Se non vengono utilizzati i backtick, l’editor di personalizzazione non riuscirà a eseguire la convalida e restituirà un errore.

Regole di sintassi PQL per chiavi di attributi speciali pql-special-keys

Oltre alle parole chiave riservate, due casi aggiuntivi richiedono l’escape backtick nelle espressioni PQL.

Chiavi attributo sillabate hyphenated-keys

Se lo schema XDM contiene nomi di campo con trattini (ad esempio my-field, event-type) o nomi che iniziano con o contengono numeri, racchiudi la chiave tra i segni di sospensione all’interno delle espressioni PQL:

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

Senza apici retroversi in un’espressione PQL, il trattino viene interpretato come un operatore di sottrazione e causa un errore di sintassi PQL.

ID evento numerici negli attributi di contesto numeric-event-ids

Quando si fa riferimento agli attributi dell’evento di contesto in cui l’ID evento è un numero (ad esempio 1697323153), racchiuderlo in apici. Questo vale anche all’interno di funzioni come formatDate():

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

Tipo coercizione type-coercion

PQL è fortemente tipizzato. Quando si confrontano o si trasmettono valori, entrambi i lati devono essere dello stesso tipo. Casi comuni:

Spazi dei nomi disponibili namespaces

Helper helpers-all

Un helper Handlebars è un semplice identificatore che può essere seguito da parametri. Ogni parametro è un’espressione Handlebars. È possibile accedere a questi helper da qualsiasi contesto in un modello.

Questi helper di blocco sono identificati da un # che precede il nome dell’helper e richiedono un / di chiusura corrispondente, con lo stesso nome.

I blocchi sono espressioni con un blocco di apertura ({{# }}) e chiusura ({{/}}).

Per ulteriori informazioni sulle funzioni di supporto, consultare questa sezione.

Tipi letterali literal-types

Adobe Journey Optimizer supporta i seguenti tipi letterali:

Best practice best-practices

Rivedi queste regole di sintassi prima di creare espressioni di personalizzazione. La maggior parte degli errori di runtime deriva dalla combinazione di Handlebars e contesti di PQL.

Utilizzare la sintassi del blocco condizionale corretta

Usa sempre {%#if%} / {%else if%} / {%else%} / {%/if%}. Sintassi {% if %} / {% elseif %} / {% endif %} non supportata.

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

Non chiamare funzioni PQL all’interno di {{...}} blocchi Handlebars

{{...}} risolve solo le variabili Handlebars e gli helper, ma non valuta PQL. Il wrapping di una funzione PQL come upperCase() in {{...}} causa un errore di tipo “Impossibile trovare l’helper”. Utilizza invece {%= ... %}:

Utilizzare un alias loop denominato quando si combina {{#each}} con{%#if%}

this.field è risolto dal renderer Handlebars ma non dal valutatore PQL all’interno di una condizione {%#if%}. Definire un alias denominato con as |item| in modo che entrambi i contesti possano risolvere il campo:

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

Assegnare i risultati della funzione PQL a una variabile prima di eseguire un ciclo

Impossibile chiamare le FDU di PQL come topN direttamente in {{#each}}. Valutali prima con {% let %}, quindi esegui un’iterazione sul risultato:

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

Utilizza {% let %} per evitare di ripetere le chiamate di funzione

Se un valore calcolato è necessario più di una volta, memorizzalo in una variabile. Ciò migliora la leggibilità e impedisce le valutazioni ridondanti:

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

Utilizza l’ordine corretto degli argomenti perdateDiff

dateDiff(start, end) prende prima la data precedente. Per calcolare i giorni rimanenti fino a una data futura, passare la data corrente come primo argomento:

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

Utilizzare = per i confronti di uguaglianza in PQL, non==

PQL utilizza un singolo operatore = per l’uguaglianza. L’utilizzo di == genera un errore di sintassi.

Usa i contrassegni per i nomi dei campi sillabati, solo nelle espressioni PQL

Se il nome di un campo dello schema XDM contiene un trattino (ad esempio order-total), racchiudilo tra apici per evitare che il trattino venga analizzato come operatore di sottrazione. Questo è supportato solo all’interno di {%= ... %} espressioni PQL, non nei blocchi Handlebars {{...}}:

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

Per le espressioni pronte all’uso che puoi copiare direttamente nel contenuto, consulta Composizioni di Personalization.