Sintaxe de personalização personalization-syntax

O Personalization no Journey Optimizer usa duas sintaxes complementares que funcionam juntas na mesma expressão:

Entender em qual contexto você está é fundamental para evitar erros de tempo de execução. Por exemplo, uma chamada de função PQL colocada dentro de {{...}} falhará porque o Handlebars tenta resolvê-la como auxiliar, em vez de avaliá-la como uma expressão PQL.

Exemplos:

A estrutura de atributos é definida em um Esquema XDM do Adobe Experience Platform. Saiba mais.

Regras gerais de sintaxe general-rules

Palavras-chave reservadas reserved-keywords

Determinadas palavras-chave são reservadas no Profile Query Language (PQL) e não podem ser usadas diretamente como nomes de campos ou variáveis em expressões de personalização. Se o esquema XDM contiver campos com nomes que correspondam a palavras-chave reservadas, você deverá fazer o escape com acentos graves (`) para referenciá-los em suas expressões.

As palavras-chave reservadas incluem:

Exemplo:

Se o esquema de perfil tiver um campo chamado next, você deverá envolvê-lo em acentos graves:

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

Sem os backticks, o editor de personalização falhará a validação com um erro.

Regras de sintaxe do PQL para chaves de atributo especiais pql-special-keys

Além das palavras-chave reservadas, dois casos adicionais exigem o escape de backtick em expressões PQL.

Chaves de atributo hifenizadas hyphenated-keys

Se o esquema XDM contiver nomes de campo com hifens (por exemplo, my-field, event-type) ou nomes que comecem com ou contenham números, coloque a chave entre acentos graves dentro de expressões PQL:

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

Sem acentos graves em uma expressão PQL, o hífen é interpretado como um operador de subtração e causa um erro de sintaxe do PQL.

IDs de evento numérico em atributos de contexto numeric-event-ids

Ao fazer referência a atributos de evento de contexto em que a ID do evento é um número (por exemplo, 1697323153), coloque-a entre acentos graves. Isso também se aplica dentro de funções como formatDate():

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

Coerção de tipo type-coercion

O PQL é altamente digitado. Ao comparar ou transmitir valores, ambos os lados devem ser do mesmo tipo. Casos comuns:

Namespaces disponíveis namespaces

Auxiliares helpers-all

Um auxiliar do Handlebars é um identificador simples que pode ser seguido por parâmetros. Cada parâmetro é uma expressão Handlebars. Esses auxiliares podem ser acessados de qualquer contexto em um modelo.

Esses auxiliares de bloco são identificados por um # precedendo o nome do auxiliar e exigem um / de fechamento correspondente, do mesmo nome.

Blocos são expressões que têm um bloco abrindo ({{# }}) e fechando ({{/}}).

Para obter mais informações sobre funções auxiliares, consulte esta seção.

Tipos literais literal-types

Adobe Journey Optimizer dá suporte aos seguintes tipos literais:

Práticas recomendadas best-practices

Revise essas regras de sintaxe antes de criar expressões de personalização. A maioria dos erros de tempo de execução vem da combinação de contextos de Handlebars e PQL.

Usar a sintaxe de bloco condicional correta

Sempre usar {%#if%} / {%else if%} / {%else%} / {%/if%}. Não há suporte para a sintaxe {% if %} / {% elseif %} / {% endif %}.

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

Não chamar funções PQL dentro de {{...}} Handlebars

{{...}} resolve somente variáveis Handlebars e auxiliares — não avalia o PQL. Encurtar uma função PQL como upperCase() dentro de {{...}} causa um erro “não foi possível encontrar auxiliar”. Em vez disso, use {%= ... %}:

Usar um alias de loop nomeado ao combinar {{#each}} com{%#if%}

this.field é resolvido pelo renderizador Handlebars, mas não pelo avaliador do PQL dentro de uma condição {%#if%}. Defina um alias nomeado com as |item| para que ambos os contextos possam resolver o campo:

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

Atribuir os resultados da função PQL a uma variável antes do loop

UDFs do PQL como topN não podem ser chamados diretamente dentro de {{#each}}. Avalie-as primeiro com {% let %} e depois repita sobre o resultado:

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

Use {% let %} para evitar chamadas de função repetidas

Quando um valor calculado for necessário mais de uma vez, armazene-o em uma variável. Isso melhora a legibilidade e evita avaliações redundantes:

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

Usar a ordem correta de argumentos paradateDiff

dateDiff(start, end) toma a data anterior primeiro. Para calcular os dias restantes até uma data futura, passe a data atual como o primeiro argumento:

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

Use = para comparações de igualdade no PQL, não==

O PQL usa um único operador = para igualdade. Usar == resulta em um erro de sintaxe.

Usar acentos graves para nomes de campo hifenizados — somente em expressões PQL

Se um nome de campo de esquema XDM contiver um hífen (por exemplo, order-total), coloque-o entre acentos graves para impedir que o hífen seja analisado como um operador de subtração. Só há suporte para isso dentro de {%= ... %} expressões PQL, não em {{...}} blocos Handlebars:

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

Para expressões prontas para uso que você pode copiar diretamente para o seu conteúdo, consulte receitas do Personalization.