Sintaxis de personalización personalization-syntax

En esta página: Conozca la sintaxis de personalización de Handlebars y PQL en Adobe Journey Optimizer, incluidas las reglas generales, las palabras clave reservadas, la coerción de tipos, los espacios de nombres disponibles y las prácticas recomendadas.

Personalization en Journey Optimizer usa dos sintaxis complementarias que funcionan juntas en la misma expresión:

Es fundamental comprender en qué contexto se encuentra para evitar errores de tiempo de ejecución. Por ejemplo, una llamada a una función de PQL colocada dentro de {{...}} fallará porque Handlebars intenta resolverla como un ayudante en lugar de evaluarla como una expresión de PQL.

Ejemplos:

La estructura de atributos se define en un esquema XDM de Adobe Experience Platform. Más información.

Sintaxis: reglas generales general-rules

Palabras clave reservadas reserved-keywords

Algunas palabras clave están reservadas en Profile Query Language (PQL) y no se pueden usar directamente como nombres de campo o variable en expresiones de personalización. Si el esquema XDM contiene campos con nombres que coinciden con palabras clave reservadas, debe escaparlos utilizando comillas invertidas (`) para hacer referencia a ellos en las expresiones.

Las palabras clave reservadas incluyen:

Ejemplo:

Si el esquema de perfil tiene un campo denominado next, debe envolverlo en acentos graves:

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

Sin las comillas invertidas, el editor de personalización falla en la validación con un error.

Reglas de sintaxis de PQL para claves de atributo especiales pql-special-keys

Más allá de las palabras clave reservadas, dos casos adicionales requieren el escape de acento grave en las expresiones PQL.

Claves de atributo con guiones hyphenated-keys

Si el esquema XDM contiene nombres de campo con guiones (p. ej. my-field, event-type) o nombres que comiencen o contengan números, ajuste la clave en comillas invertidas dentro de expresiones PQL:

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

Sin comilla invertida en una expresión PQL, el guión se interpreta como un operador de resta y provoca un error de sintaxis de PQL.

ID de eventos numéricos en atributos de contexto numeric-event-ids

Cuando se haga referencia a atributos de evento de contexto en los que el ID de evento sea un número (por ejemplo, 1697323153), encapsúlelo con acentos graves. Esto también se aplica dentro de funciones como formatDate():

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

Coerción de tipo type-coercion

PQL tiene establecimiento inflexible de tipos. Al comparar o pasar valores, ambos lados deben ser del mismo tipo. Casos frecuentes:

Áreas de nombres disponibles namespaces

Ayudantes helpers-all

Un asistente de Handlebars es un identificador simple que puede ir seguido de parámetros. Cada parámetro es una expresión Handlebars. Se puede acceder a estos ayudantes desde cualquier contexto de una plantilla.

Estos ayudantes de bloque se identifican con un # antes del nombre del ayudante y requieren un / de cierre coincidente, del mismo nombre.

Los bloques son expresiones que tienen un bloque de apertura ({{# }}) y cierre ({{/}}).

Para obtener más información sobre las funciones de ayuda, consulte esta sección.

Tipos literales literal-types

Adobe Journey Optimizer admite los siguientes tipos literales:

Prácticas recomendadas best-practices

Revise estas reglas de sintaxis antes de crear expresiones de personalización. La mayoría de los errores de tiempo de ejecución provienen de la mezcla de Handlebars y contextos PQL.

Use la sintaxis de bloque condicional correcta

Use siempre {%#if%} / {%else if%} / {%else%} / {%/if%}. No se admite la sintaxis {% if %} / {% elseif %} / {% endif %}.

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

No llame a funciones de PQL dentro de {{...}} bloques de Handlebars

{{...}} solo resuelve las variables Handlebars y los ayudantes, no evalúa PQL. Al ajustar una función de PQL como upperCase() dentro de {{...}}, se produce el error “no se pudo encontrar el asistente”. Usar {%= ... %} en su lugar:

Use un alias de bucle con nombre al combinar {{#each}} con{%#if%}

this.field lo ha resuelto el procesador Handlebars, pero no el evaluador PQL dentro de una condición {%#if%}. Defina un alias con nombre con as |item| para que ambos contextos puedan resolver el campo:

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

Asignar resultados de funciones de PQL a una variable antes del bucle

No se puede llamar a las UDF de PQL como topN directamente dentro de {{#each}}. Evalúelos primero con {% let %} y después itere en el resultado:

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

Use {% let %} para evitar repetir llamadas a funciones

Cuando un valor calculado se necesite más de una vez, almacénelo en una variable. Esto mejora la legibilidad y evita evaluaciones redundantes:

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

Use el orden de argumentos correcto paradateDiff

dateDiff(start, end) toma primero la fecha anterior. Para calcular los días restantes hasta una fecha futura, pase la fecha actual como primer argumento:

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

Use = para comparaciones de igualdad en PQL, no==

PQL usa un solo operador = para la igualdad. Usar == resulta en un error de sintaxis.

Use comillas invertidas para nombres de campos con guiones, solo en expresiones PQL

Si el nombre de un campo de esquema XDM contiene un guion (por ejemplo, order-total), encapsúlelo en comillas invertidas para evitar que el guion se analice como operador de resta. Esto solo se admite dentro de {%= ... %} expresiones PQL, no en {{...}} bloques Handlebars:

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

Para ver las expresiones listas para usar que puede copiar directamente en el contenido, consulte Fórmulas de Personalization.