パーソナライゼーション構文 personalization-syntax

このページでは、​一般的なルール、予約キーワード、型強制、使用可能な名前空間、ベストプラクティスなど、Adobe Journey OptimizerのHandlebarsとPQL パーソナライゼーション構文について説明します。

Journey OptimizerのPersonalizationは、同じ式で一緒に動作する2つの補完的な構文を使用します。

どのコンテキストにいるのかを理解することは、ランタイムエラーを回避するための鍵となります。 例えば、{{...}}内に配置されたPQL関数呼び出しは、HandlebarsがPQL式として評価するのではなくヘルパーとして解決しようとするため、失敗します。

例：

属性の構造は、Adobe Experience Platform XDM スキーマで定義されます。 学習を増やす。

構文の一般的なルール general-rules

予約済みのキーワード reserved-keywords

特定のキーワードは、Profile Query Language（PQL）で予約され、パーソナライゼーション式のフィールド名または変数名として直接使用できません。 XDM スキーマに予約済みのキーワードと一致する名前のフィールドが含まれている場合、式で参照するには、バックティック（`）を使用してエスケープする必要があります。

予約済みのキーワードは次のとおりです。

例：

プロファイルスキーマに next という名前のフィールドがある場合は、バックティックで囲む必要があります。

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

バックティックがないと、パーソナライゼーションエディターは検証に失敗し、エラーが発生します。

特殊属性キーのPQL構文ルール pql-special-keys

予約済みキーワード以外にも、2つのケースでPQL エクスプレッションでバックティック エスケープが必要になります。

ハイフネーションされた属性キー hyphenated-keys

XDM スキーマにハイフン付きのフィールド名（例：my-field、event-type）または数字で始まるまたは含まれる名前が含まれている場合は、キーをPQL エクスプレッション内のバックティックにラップします。

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

PQL式でバックティックを使用しない場合、ハイフンは減算演算子として解釈され、PQL構文エラーが発生します。

コンテキスト属性の数値イベント ID numeric-event-ids

イベント IDが数値（例：1697323153）であるコンテキストイベント属性を参照する場合は、バックティックにラップします。 これはformatDate()のような関数の内部でも適用されます。

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

型強制 type-coercion

PQLは強く型付けされています。 値を比較または渡す場合、両側は同じタイプである必要があります。 一般的なケース：

使用可能な名前空間 namespaces

ヘルパー helpers-all

Handlebars ヘルパーは、パラメーターの後に付けられる単純な識別子です。 各パラメーターは、Handlebars 式です。 これらのヘルパーは、テンプレート内の任意のコンテキストからアクセスできます。

これらのブロックヘルパーは、ヘルパー名の先頭にある # で識別され、対となる同じ名前の / タグで閉じる必要があります。

ブロックは、ブロック開始タグ（{{# }}）と終了タグ（{{/}}）を持つ式です。

ヘルパー関数について詳しくは、この節を参照してください。

リテラル型 literal-types

Adobe Journey Optimizer では、次のリテラル型をサポートしています。

ベストプラクティス best-practices

パーソナライゼーション式を作成する前に、これらの構文ルールを確認します。 ほとんどのランタイムエラーは、HandlebarsとPQLのコンテキストを混在させることから発生します。

正しい条件付きブロック構文を使用

常に{%#if%} / {%else if%} / {%else%} / {%/if%}を使用してください。 {% if %} / {% elseif %} / {% endif %}構文はサポートされていません。

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

Handlebars ブロック​内のPQL関数を呼び出さない{{...}}

{{...}}はHandlebars変数とヘルパーのみを解決します。PQLは評価されません。 {{...}}内のupperCase()のようなPQL関数をラップすると、「ヘルパーが見つかりませんでした」エラーが発生します。 代わりに{%= ... %}を使用してください：

{{#each}}と{%#if%}​を組み合わせる場合は、名前付きループ エイリアスを使用します

this.fieldはHandlebars レンダラーによって解決されますが、{%#if%}条件内のPQL エバリュエーターによって解決されません。 両方のコンテキストがフィールドを解決できるように、as |item|を使用して名前付きエイリアスを定義します。

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

ループする前にPQL関数の結果を変数に割り当てます

topNなどのPQL UDFは、{{#each}}内で直接呼び出すことはできません。 最初に{% let %}で評価し、次に結果を繰り返します。

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

関数呼び出しの繰り返しを避けるために{% let %}を使用する

計算された値が複数回必要な場合は、変数に格納します。 これにより、読みやすさが向上し、冗長な評価を防ぐことができます。

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

dateDiff​の正しい引数順序を使用する

dateDiff(start, end)は前の日付を最初に使用します。 将来の日付までの残り日数を計算するには、現在の日付を最初の引数として渡します。

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

==​ではなく、=を使用してPQLで等価比較を行います

PQLは、等号に1つの=演算子を使用します。 ==を使用すると、構文エラーが発生します。

ハイフネーションされたフィールド名にバックティックを使用する – PQL式のみ

XDM スキーマフィールド名にハイフン （例：order-total）が含まれる場合は、ハイフンが減算演算子として解析されないように、ハイフンをバックティックで折り返します。 これは、{{...}}個のHandlebars ブロックではなく、{%= ... %}個のPQL式でのみサポートされています。

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

すぐに使用できるエクスプレッションについては、Personalization レシピ ​を参照してください。