コンテキスト

コンテキストステップを使用すると、ユーザーがキャンバス内を移動するときに、ユーザーの変数を1つ以上作成、更新できます。例えば季節割引を管理するキャンバスでは、コンテキスト変数を使用して、ユーザーがキャンバスにエントリするたびに異なる割引コードを保存できます。

仕組み

«««< HEAD ======= !キャンバスの最初のステップとしてのコンテクスト・ステップ。

main

コンテキスト・ステップでは、ユーザーが特定のキャンバス内を移動する間に一時的なデータを作成し、使用することができる。このデータは、そのCanvas ジャーニー内にのみ存在し、異なるCanvase 間やセッション外では保持されません。

このフレームワーク内で、各コンテキストステップは、複数のコンテキスト変数(ユーザーのプロファイル情報を永続的に変更することなく、遅延のパーソナライズ、ユーザーの動的セグメント化、メッセージングの拡張を可能にする一時的なデータ)を定義できます。

たとえば、フライト予約を管理している場合、各ユーザーのスケジュールされたフライト時間のコンテキスト変数を作成できます。その後、各ユーザーのフライト時間に応じて遅延を設定し、同じキャンバスから個別のリマインダーを送信できます。

コンテキスト変数は、次の2 つの方法で設定できます。

• キャンバスエントリで:ユーザがキャンバスに入ると、イベントまたはAPI トリガのデータが自動的にコンテキスト変数に入力されます。
• コンテキストステップで:コンテキストステップを追加することで、キャンバス内でコンテキスト変数を手動で定義または更新できます。

各コンテキスト変数には以下が含まれます。

• 名前 (flight_time やsubscription_renewal_date など)
• データ型 (数値、文字列、時刻、配列など)
• LiquidまたはAdd Personalizationツールを使用して割り当てる値。

定義したコンテキスト変数は、キャンバス全体で {{context.${example_variable_name}}} という形式で参照できます。

例えば、{{context.${flight_time}}} 、ユーザーのスケジュールされたフライト時間を返すことができる。

ユーザーがキャンバスにエントリするたびに (以前にキャンバスにエントリしたことがある場合でも)、コンテキスト変数は、最新のエントリデータとキャンバス設定に基づいて再定義されます。このステートフルなアプローチにより、各キャンバスエントリーは独立系のコンテキストを維持することができ、ユーザーは各ステートに固有のコンテキストを保持しながら、同じ旅の中で複数のアクティブステートを持つことができる。

例えば、顧客に2つのフライトの予定がある場合、2つの別々のカスタマージャーニーの状態が同時に実行される。これにより、ニューヨーク行きの午後2時のフライトに関するパーソナライズされたリマインダーを送る一方で、ロサンゼルス行きの明日の午前8時のフライトに関する異なる更新を送ることができ、各メッセージが特定の予約に関連したものに保たれる。

考慮事項

• コンテクスト・ステップごとに、最大10個のコンテクスト変数を持つことができる。
• 各コンテキスト変数名は100文字まで。
• コンテキスト変数名は有効な識別子（文字、数字、アンダースコアのみ）でなければならない。
• コンテキスト変数の定義は10,240文字まで可能である。
• APIトリガーのキャンバスに渡されるコンテキスト変数は、キャンバスのコンテキストステップで作成されるコンテキスト変数と同じ名前空間を共有する。つまり、/canvas/trigger/send エンドポイントコンテキストオブジェクトで変数purchased_item を送信した場合、それは{context.${purchased_item}} として参照することができ、キャンバスのコンテキストステップでその変数を再宣言すると、以前に送信されたものが上書きされる。
• コンテキスト・ステップごとに最大50KBまで保存でき、ステップごとに最大10個の変数を分散して保存できる。1ステップの合計が50KBを超える変数サイズは、ユーザーに対して評価されず、保存もされない。これらのサイズは順番に計算される。例えば、コンテキスト・ステップに3つの変数があるとする：
  • 変数1：30 KB
  • 変数2：19 KB
  • 変数3：2 KB
  • つまり、他のすべてのコンテキスト変数の合計が50KBを超えるため、変数3は評価も保存もされない。

コンテキストステップの作成

ステップ1:ステップを追加する

キャンバスにステップを追加し、サイドバーからコンポーネントをドラッグアンドドロップするか、 plus ボタンを選択し、Context を選択します。

ステップ2: 変数の定義

コンテキスト変数を定義するには

1. コンテキスト変数にname を指定します。
2. データ型を選択します。
3. Liquid 式を手動で記述するか、Add Personalization を使用して既存の属性からLiquid スニペットを作成します。
4. コンテキスト変数の値を確認するには、プレビューを選択します。
5. (オプション) 変数を追加するには、[コンテキスト変数を追加] を選択し、手順1～4を繰り返します。
6. [完了] を選択します。

これで、[パーソナライズを追加する] を選択して、メッセージステップやユーザー更新ステップなど Liquid を使用する任意の場所で、コンテキスト変数を使用できます。フルウォークスルーについては、コンテキスト変数の使用を参照してください。

コンテキスト変数のデータ型

ステップで作成または更新されるコンテキスト変数には、次のデータ型を割り当てることができます。

デフォルトでは、時刻のデータ型はUTCである。文字列データ型を使って時間値を格納する場合、PSTのような異なるタイムゾーンとして時間を定義することができる。

例えば、ユーザーの誕生日の前日にメッセージを送信する場合、前日送信に関連するLiquidロジックがあるため、コンテキスト変数をtimeデータ型として保存する。しかし、クリスマス（12月25日）にホリデー・メッセージを送るのであれば、ダイナミックな変数として時刻を参照する必要はないだろうから、文字列データ型を使うのが望ましいだろう。

コンテキスト変数の使用

たとえば、次のフライトの前に、VIP ラウンジへのアクセスについて乗客に通知したいとします。このメッセージは、ファーストクラスのチケットを購入した乗客にのみ送信する必要があります。コンテキスト変数は、この情報を追跡する柔軟な方法です。

ユーザーは、飛行機のチケットを購入するときにキャンバスに入ります。ラウンジアクセスの適格性を判断するために、コンテキストステップでlounge_access_grantedというコンテキスト変数を作成し、その後のユーザージャーニーのステップでそのコンテキスト変数を参照します。

«««< HEAD ======= !乗客がVIPラウンジを利用できるかどうかを追跡するために設定されたコンテキスト変数である。

main

このコンテキストステップでは、{{custom_attribute.${purchased_flight}}} を使用して、購入したフライトのタイプがfirst_class かどうかを判断します。

次に、{{context.${lounge_access_granted}}} がtrue であるユーザーをターゲットにするメッセージステップを作成します。このメッセージは、個人化されたラウンジ情報を含むプッシュ通知となります。このコンテキスト変数に基づいて、適格な乗客は、フライト前に関連するメッセージを受け取ります。

• ファーストクラスの乗客は次のメッセージを受け取ります:「Enjoy exclusive VIP lounge access!」
• ビジネスクラスとエコノミークラスの乗客は次のメッセージを受け取ります:「Upgrade your flight for exclusive VIP lounge access.」

«««< HEAD ======= !購入した航空券の種類によって、送信するメッセージが異なるメッセージステップ。

main

アクションパスと終了基準について

これらのトリガーアクションでは、コンテキスト変数またはカスタム属性でプロパティフィルターを比較することができる：[カスタムイベントを実行] または [購入] のいずれかを選択できます。これらのアクショントリガーは、基本プロパティとネストされたプロパティの両方のプロパティフィルターにも対応している。

• 基本プロパティと比較する場合、利用可能な比較はカスタムイベントによって定義されたプロパティのタイプと一致する。例えば、文字列プロパティは、正規表現と完全に一致する。ブール型プロパティは真か偽になる。
• 階層化されたプロパティを比較する場合、型はあらかじめ定義されていないため、階層化されたカスタム属性の比較と同様に、真偽値、数値、文字列、時刻、曜日について、複数のデータ型にまたがる比較を選択することができる。比較時にネストされたプロパティの実際のデータ型と一致しないデータ型を選択した場合、ユーザーはアクションパスまたは終了基準に一致しない。

アクションパスの例

• perform custom event
• make purchase

終了基準の例

• perform custom event
• make purchase

コンテキスト変数フィルター

オーディエンスパスと 条件分岐ステップで、以前に宣言したコンテキスト変数を使用するフィルターを作成できる。

つまり、セグメンテーションの中で参照することはできない。オーディエンスパスのステップは複数のグループを表し、条件分岐のステップは二値決定を表す。

«««< HEAD ======= !条件分岐ステップの例では、コンテキスト変数でフィルターを作成することができる。

main

キャンバスのコンテキスト変数があらかじめ定義された型を持っているのと同様に、コンテキスト変数とスタティック値の比較も、データ型が一致していなければならない。コンテキスト変数フィルターは、階層化されたカスタム属性の比較と同様に、ブーリアン、数値、文字列、時刻、曜日について、複数のデータ型にまたがる比較を可能にする。

以下は、コンテキスト変数product_name を正規表現/braze/ と比較するコンテキスト変数フィルターの例である。

«««< HEAD ======= !コンテキスト変数”product_name” 、正規表現”/braze/”にマッチするようにフィルターが設定されている。

main

コンテキスト変数やカスタム属性との比較

コンテキスト変数またはカスタム属性と比較するトグルを選択することにより、以前に定義されたコンテキスト変数またはユーザーカスタム属性と比較するコンテキスト変数フィルターを構築することができる。これは、APIトリガー（context ）のようにユーザーごとにダイナミックな比較を実行する場合や、コンテキスト変数にまたがって定義された複雑な比較ロジックを凝縮する場合に便利である。

• example 1
• example 2

ユーザーパスをプレビューする

メッセージが適切なオーディエンスに送信され、コンテキストの変数が期待される結果に対して評価されていることを確認するために、ユーザーパスをテストしプレビューすることをお勧めする。

無効なコンテキスト変数を作成する一般的なシナリオを必ず観察すること。ユーザーパスをプレビューする際、コンテキスト変数を使用してパーソナライズされたDelayステップの結果、およびユーザーを任意のコンテキスト変数に一致させるオーディエンス、意思決定、またはアクションパスのステップ比較を表示することができる。

コンテキスト変数が有効な場合は、キャンバス全体で変数を参照できます。しかし、コンテキスト変数が正しく作成されなかった場合、キャンバスの今後のステップも正しく実行されない。例えば、ユーザーにアポイントメントタイムを割り当てるためにコンテキストステップを作成し、アポイントメントタイムの値を過去の日付に設定した場合、メッセージステップのリマインダーメールは送信されない。

接続されたコンテンツ文字列のJSON への変換

コンテキストステップでコネクテッドコンテンツ呼び出しを実行すると、整合性とエラー防止のために、呼び出しから返された JSON が文字列データ型として評価されます。この文字列をJSON に変換する場合は、as_json_string を使用して変換します。以下に例を示します。

1
2
{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

タイムゾーンの一貫性の標準化

キャンバスコンテキストの追加により、アクションベースのキャンバスのトリガーイベントプロパティから datetimeタイプを持つすべてのタイムスタンプは、常にUTCに正規化される。以前は、例外を除き、イベントプロパティのタイムスタンプはUTCに正規化されていた。これでキャンバスのステップやメッセージの編集がより一貫したものになる。

この変更がキャンバスのタイムスタンプにどのような影響を与えるかの例を考えてみよう。アクション・ベースのキャンバスで、イベント・プロパティをキャンバスの最初のステップで使い、次のメッセージ・ステップを使うとしよう：

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

«««< HEAD ======= !メッセージ・ステップを最初のステップとするコンテクスト・ジャーニー。

main

ステップはまた、次のようなイベントペイロードを持つ：

1
2
3
{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
}

歴史的に見れば、メッセージはこうだろう： Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

キャンバス・コンテキストの早期アクセスによって、メッセージはこうなる：Your appointment is scheduled for 2025-08-05 4:15pm, we’ll see you then! これは、タイムスタンプがUTCであるためで、太平洋時間（元のペイロードで-08:00)で指定されたタイムゾーンより8時間進んでいる。

Liquidを使用して、希望するタイムゾーンでのタイムスタンプを示す。

次のLiquidのスニペットを考えてみよう：

1
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

このロジックの結果は以下のようになる： Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

優先タイムゾーンは、イベントプロパティのペイロードで送信し、Liquidロジックで使用することもできる：

1
2
3
4
{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

これはLiquidスニペットの例である：

1
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: canvas_entry_properties.${user_timezone} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

トラブルシューティング

無効なコンテキスト変数

以下の場合、コンテキスト変数は無効と見なされます。

• 埋め込み接続コンテンツへの呼び出しが失敗します。
• 実行時のLiquid 式は、データ型と一致しない値、または空(NULL) の値を返します。

たとえば、コンテキスト変数のデータ型がNumber であるが、Liquid 式が文字列を返す場合、これは無効です。

このような状況では次のようになります。

• ユーザーは次のステップに進みます。
• キャンバスステップ分析では、これは_未更新_としてカウントされます。

トラブルシューティングの際には、_未更新_指標を監視して、コンテキスト変数が正しく更新されることを確認します。コンテキスト変数が無効な場合、ユーザーはコンテキストステップを過ぎてもキャンバスに留まることができますが、後のステップには適さない場合があります。

各データ型の設定例については、コンテキスト変数データ型を参照してください。

よくある質問

コンテキスト変数は、Canvas エントリプロパティとはどのように異なるのですか?

コンテキストステップの初期アクセスに参加している場合は、キャンバスのエントリプロパティがキャンバスのコンテキスト変数として含まれるようになりました。つまり、Liquid スニペットでコンテキスト変数を使用する場合と同様に、Braze API を使用してキャンバスエントリのプロパティを送信し、他のステップでこれらのプロパティを参照できます。

変数は、1つのコンテキストステップ内で相互に参照できますか?

はい。コンテキストステップのすべての変数は、シーケンスで評価されます。つまり、以下のコンテキスト変数を設定できます。

これは、複数のコンテキストステップにも適用されます。例えば次のシーケンスを考えてみます。

1. 最初のコンテキストステップでは、JobInfo という変数を作成して値 job_title を設定します。
2. メッセージステップは {{context.${JobInfo}}} を参照し、job_title をユーザーに表示します。
3. その後、コンテキストステップによってコンテキスト変数が更新され、JobInfo の値がjob_description に変更されます。
4. JobInfo を参照する以降のすべてのステップで、更新された値job_description が使用されるようになりました。

コンテキスト変数は、キャンバス全体で最新の値を使用します。更新を行うたびに、その変数を参照する後続のすべてのステップに影響します。

キャンバスコンテキストのタイムゾーン一貫性の標準化は、APIトリガーのキャンバスに影響を与えるか？

いや、この変更はアクショントリガーのキャンバスにしか影響しない。APIトリガーのCanvasesに送られるタイムスタンプは、時間型ではなく文字列型であるため、元のタイムゾーンは常に保持される。

これは、キャンバスのエントリー・プロパティやイベント・プロパティに記されている例外イベントとどのように関係しているのか？

キャンバスコンテキストの早期アクセスに参加すると、キャンバスコンテキストのステップを使用しているかどうかにかかわらず、これらの例外がなくなる。