コンテキスト変数
コンテキスト変数とは、特定のキャンバス内をユーザーが移動する過程で作成・使用できる一時的なデータです。遅延をパーソナライズしたり、ユーザーをダイナミックにセグメント化したり、メッセージングを充実させたりすることが、ユーザープロファイル情報を恒久的に変更することなく実現できます。コンテキスト変数はキャンバスセッション内でのみ存在し、異なるキャンバス間やセッション外では永続化されません。
コンテキスト変数の仕組み
コンテキスト変数は2つの方法で設定できます。
- キャンバスエントリ時：ユーザーがキャンバスに入ると、イベントまたは API トリガーのデータが自動的にコンテキスト変数に入力されます。
- コンテキストステップ内：コンテキストステップを追加することで、キャンバス内でコンテキスト変数を手動で定義または更新できます。
各コンテキスト変数には以下が含まれます。
- 名前（
flight_timeやsubscription_renewal_dateなど） - データタイプ（数値、文字列、時刻、配列など）
- Liquid またはパーソナライゼーションを追加ツールを使用して割り当てる値
定義したコンテキスト変数は、キャンバス全体で {{context.${example_variable_name}}} という形式で参照できます。
例えば、{{context.${flight_time}}} はユーザーのスケジュールされたフライト時刻を返すことができます。
ユーザーがキャンバスにエントリするたびに（以前にエントリしたことがある場合でも）、コンテキスト変数は最新のエントリデータとキャンバス設定に基づいて再定義されます。このステートフルなアプローチにより、各キャンバスエントリは独自の独立したコンテキストを維持できます。これにより、ユーザーは同一のジャーニー内で複数のアクティブな状態を保持しつつ、各状態固有のコンテキストを維持できます。
例えば、顧客が2つのフライトを予約している場合、2つの別々のジャーニー状態が同時に進行します。それぞれに、出発時刻や目的地といったフライト固有のコンテキスト変数が存在します。これにより、午後2時のニューヨーク行きのフライトについてはパーソナライズされたリマインダーを送信しつつ、明日の午前8時のロサンゼルス行きフライトについては別の更新情報を送信できます。こうして各メッセージが特定の予約に関連した内容となります。
考慮事項
コンテキストステップごとに最大10個のコンテキスト変数を定義できます。各変数名は最大100文字までで、英字、数字、またはアンダースコアのみを使用する必要があります。
コンテキスト変数の定義は最大10,240文字まで可能です。API によってトリガーされたキャンバスにコンテキスト変数を渡した場合、それらの変数はコンテキストステップで作成された変数と同じ名前空間を共有します。例えば、/canvas/trigger/send エンドポイントのコンテキストオブジェクトに変数 purchased_item を送信した場合、それを {{context.${purchased_item}}} として参照できます。その変数をコンテキストステップで再定義すると、新しい値がそのユーザーのジャーニーにおける API 値を上書きします。
コンテキストステップごとに最大50KBを保存でき、これは最大10個の変数に分散して保存されます。ステップ内の全変数の合計サイズが50KBを超える場合、制限値を超えた変数は評価も保存も行われません。例えば、コンテキストステップに3つの変数がある場合：
- 変数1：30KB
- 変数2：19KB
- 変数3：2KB
変数3は評価も保存もされません。前の変数の合計が50KBを超えているためです。
データタイプ
ステップで作成または更新されるコンテキスト変数には、次のデータタイプを割り当てることができます。
コンテキスト変数は、カスタムイベントと同様のデータタイプの形式が期待されます。
配列型を使用する場合、Braze はその値を JSON として解析しようとします。これにより、オブジェクトの配列が正常に作成されます。配列内のオブジェクトが有効な JSON でない場合、結果は単純な文字列の配列となります。
ネストされたオブジェクトやオブジェクトの配列には、as_json_string Liquid フィルターを使用してください。コンテキストステップで同じオブジェクトを作成する場合、as_json_string を使用してオブジェクトをレンダリングする必要があります。例えば、{{context.${object_array} | as_json_string }}
| データタイプ | 変数名の例 | 値の例 |
|---|---|---|
| ブール値 | loyalty_program | true |
| 数値 | credit_score | 740 |
| 文字列 | product_name | green_tea |
| 配列 | favorite_products | ["wireless_headphones", "smart_homehub", "fitness_tracker_swatch"] |
| 配列（オブジェクトの） | pet_details | [ |
| 時間（UTC） | last_purchase_date | 2025-12-25T08:15:30:250-0800 |
| オブジェクト（フラット化） | user_profile | { |
デフォルトでは、時刻データタイプは UTC です。文字列データタイプで時刻値を保存する場合、その時刻を PST のような別のタイムゾーンとして定義できます。
例えば、ユーザーの誕生日の前日にメッセージを送信する場合、前日に送信するという Liquid ロジックが関連しているため、コンテキスト変数を時間データタイプとして保存します。ただし、クリスマスの日（12月25日）にホリデーメッセージを送る場合、時間をダイナミックな変数として参照する必要はないため、文字列データタイプを使用するのが望ましいです。
オブジェクトデータタイプの場合、ドット記法を使用してデータ内のパスを指定できます。例えば、コンテキストステップで以下の構造を持つコンテキスト変数 order_summary を定義した場合：
1
2
3
4
5
{
"shipping": {
"carrier": "overnight"
}
}
オーディエンスパスや条件分岐フィルターでは、ドット記法を使用してコンテキスト変数名としてパスを入力します（例：order_summary.shipping.carrier）。フィルターが評価されると、Braze はそのパスを値 overnight に解決します。
Liquid 内（メッセージステップなど）では、代わりに {{context.${order_summary}.shipping.carrier}} を使用してください。
コンテキスト変数の使用
キャンバス内の Liquid を使用する場所ならどこでも、コンテキスト変数を使用できます。例えばメッセージステップやユーザー更新ステップでパーソナライゼーションを追加を選択するだけです。アプリ内メッセージやメッセージステップ内のバナーでは、コンテキスト変数を選択してメッセージの有効期限を決定できます。
例えば、次のフライトの前に VIP ラウンジへのアクセスについて乗客に通知したいとします。このメッセージは、ファーストクラスのチケットを購入した乗客にのみ送信する必要があります。コンテキスト変数は、この情報を追跡する柔軟な方法です。
ユーザーは、飛行機のチケットを購入するときにキャンバスに入ります。ラウンジアクセスの適格性を判断するために、コンテキストステップで lounge_access_granted というコンテキスト変数を作成し、その後のユーザージャーニーのステップでそのコンテキスト変数を参照します。
このコンテキストステップでは、{{custom_attribute.${purchased_flight}}} を使用して、購入したフライトのタイプが first_class かどうかを判断します。
次に、{{context.${lounge_access_granted}}} が true であるユーザーをターゲットにするメッセージステップを作成します。このメッセージは、パーソナライズされたラウンジ情報を含むプッシュ通知となります。このコンテキスト変数に基づいて、適格な乗客はフライト前に関連するメッセージを受け取ります。
- ファーストクラスの乗客は次のメッセージを受け取ります：「Enjoy exclusive VIP lounge access!」
- ビジネスクラスとエコノミークラスの乗客は次のメッセージを受け取ります：「Upgrade your flight for exclusive VIP lounge access.」
コンテキストステップの情報を使用して、パーソナライズされた遅延オプションを追加できます。つまり、ユーザーを遅延させる変数を選択できます。
アクションパスと終了条件について
これらのトリガーアクションでは、コンテキスト変数またはカスタム属性のいずれかを使用してプロパティフィルターの比較を活用できます：カスタムイベントを実行および購入。これらのアクショントリガーは、基本プロパティとネストされたプロパティの両方に対するプロパティフィルターもサポートしています。
- 基本プロパティとの比較では、利用可能な比較はカスタムイベントで定義されたプロパティの型に一致します。例えば、文字列プロパティは完全一致や正規表現一致を持ちます。ブール値プロパティは true か false になります。
- ネストされたプロパティとの比較では、型は事前定義されていないため、ブール値、数値、文字列、時刻、年の日数といった複数のデータタイプにわたる比較を選択できます。これは階層化カスタム属性の比較と同様です。比較時に、ネストされたプロパティの実際のデータタイプと一致しないデータタイプを選択した場合、ユーザーはアクションパスや終了条件に一致しません。
アクションパスの例
カスタム属性の比較では、アクションが実行された時点でのカスタム属性値を使用します。これは、比較時にこのカスタム属性が設定されていない場合、またはカスタム属性の値が定義されたプロパティ比較と一致しない場合、ユーザーがアクションパスのグループに一致しないことを意味します。ユーザーがアクションパスステップに入った時点で条件に合致していた場合でも、この現象は発生します。
以下のアクションパスは、カスタムイベント Account_Created を実行したユーザーを、基本プロパティ source をコンテキスト変数 app_source_variable と照合してソートするように設定されています。
以下のアクションパスは、特定の製品名 shoes に対する基本プロパティ brand をコンテキスト変数 promoted_shoe_brand に一致させるように設定されています。
終了条件の例
終了条件は、キャンバス内のユーザージャーニーのいずれかの時点で、以下の条件を満たした場合にユーザーがキャンバスから退出することを示しています。
- カスタムイベントカート放棄を実行し、かつ
- 基本プロパティカート内のアイテムがコンテキスト変数
cart_item_thresholdの文字列値と一致する。
終了条件は、キャンバス内のユーザージャーニーのいずれかの時点で、以下の条件を満たした場合にユーザーがキャンバスから退出することを示しています。
- 「book」という商品名で特定の購入を行い、かつ
- その購入のネストされたプロパティ「loyalty_program」がユーザーのカスタム属性「VIP」と等しい。
有効期限の設定
キャンバスのメッセージステップ内のバナーやアプリ内メッセージでは、有効期限としてステップが利用可能になってからの期間を選択し、期間をパーソナライズをオンにすることで、コンテキスト変数から利用可能時間枠を制御できます。例えば、コンテキストステップのプロモーションや予約期間に合わせることができます。
期間をパーソナライズは、その期間ベースの有効期限オプションに適用されます。代わりに特定の日時を選択した場合は、日時コントロールを使用して有効期限を設定してください。
アクションパスの遅延
アクションパスステップの評価時間枠で、遅延をパーソナライズをオンにすると、コンテキスト変数からユーザーがステップに留まる時間を設定できます。ティアやリージョンなどの詳細に基づいて、待機期間をユーザーごとに変える必要がある場合に使用してください。
コンテキスト変数フィルター
オーディエンスパスと条件分岐ステップでは、事前に宣言されたコンテキスト変数を使用するフィルターを作成できます。
コンテキスト変数フィルターは、オーディエンスパスと条件分岐ステップでのみ利用可能です。
コンテキスト変数はキャンバスのスコープ内で宣言され、アクセス可能となります。つまり、セグメント内では参照できません。コンテキスト変数フィルターは、オーディエンスパスと条件分岐ステップで同様の機能を持ちます。オーディエンスパスステップは複数のグループを表し、条件分岐ステップは二値の決定を表します。
キャンバスのコンテキスト変数が事前定義された型を持つのと同様に、コンテキスト変数と静的値の比較ではデータタイプが一致していなければなりません。コンテキスト変数フィルターは、ブール値、数値、文字列、時刻、および年の日数といった複数のデータタイプ間で比較を可能にします。これは、階層化カスタム属性に対する比較と同様です。
コンテキスト変数と比較には同じデータタイプを使用してください。例えば、コンテキスト変数が時間データタイプの場合、時間比較（「前」や「後」など）を使用します。データタイプの不一致（時間コンテキスト変数との文字列比較など）を使用すると、予期しない動作を引き起こす可能性があります。
「Day of year」と「Time」のフィルタータイプの選択について：日付を含むコンテキスト変数をフィルタリングする際は、その日付が毎年繰り返されるかどうかに基づいて、適切な比較タイプを選択してください。
- 毎年繰り返される日付（誕生日、記念日、クリスマスなどの祝日など）には「Day of year」を使用してください。この比較タイプは、年の要素を無視し、その年の日数（1〜365/366）に基づいて計算します。
- 繰り返されない絶対日付（契約終了日、予約日、サブスクリプションの更新日など）には「Time」を使用してください。この比較タイプは、年を含む完全なタイムスタンプに基づいて計算します。
絶対日付に「Day of year」を使用すると、計算が年の要素を無視するため、誤った結果や予期しない結果が生じることがあります。例えば、4月の将来の契約終了日が63日以内かどうかを判断する場合、「Day of year」を使用すると、日付番号（119対359）のみを比較し、実際には4月まで188日あることを考慮しないため、誤った一致が生じる可能性があります。
一般的な指針：その日付は毎年繰り返されますか？はい → 「Day of year」を使用してください。いいえ → 「Time」を使用してください。
以下は、コンテキスト変数 product_name を正規表現 /braze/ と比較するコンテキスト変数フィルターの例です。
コンテキスト変数やカスタム属性との比較
コンテキスト変数またはカスタム属性との比較トグルを選択することで、事前に定義されたコンテキスト変数やユーザーのカスタム属性と比較するコンテキスト変数フィルターを構築できます。これは、API トリガーの context などユーザーごとにダイナミックな比較を行う場合や、コンテキスト変数にまたがって定義された複雑な比較ロジックを簡略化するのに有用です。
例えば、ダイナミックな非アクティブ期間の後にユーザーへパーソナライズされたリマインダーを送信したい場合を考えてみましょう。具体的には、過去3日間アプリにログインしていないユーザー全員にメッセージが届くようにします。
コンテキスト変数 re_engagement_date があり、{{now | minus: 3 | append: ' days'}} として定義されています。3 days は変数量であり、ユーザーのカスタム属性としても保存できます。re_engagement_date が last_login_date（ユーザープロファイルのカスタム属性として保存）の後にある場合、そのユーザーにはメッセージが送信されます。
以下のフィルターは、コンテキスト変数 reminder_date がコンテキスト変数 appointment_deadline より前にあるかどうかを比較します。これにより、オーディエンスパスステップ内のユーザーをグループ分けし、予約期限前に追加のリマインダーを受け取るべきかどうかを判断できます。
タイムゾーンの一貫性に関する標準化
キャンバスでは、タイムスタンプ型を使用するイベントプロパティの大半は既に UTC で管理されていますが、例外も存在します。Canvas Context の追加により、アクションベースのキャンバスにおけるすべてのデフォルトのタイムスタンプイベントプロパティは、一貫して UTC で表示されるようになります。この変更は、キャンバスのステップやメッセージを編集する際の操作性をより予測可能で一貫性のあるものにするための、より広範な取り組みの一環です。この変更は、特定のキャンバスがコンテキストステップを使用しているかどうかに関わらず、すべてのアクションベースのキャンバスに影響を与えることに注意してください。
いかなる状況においても、タイムスタンプを希望のタイムゾーンで表現するには、Liquid time_zone フィルターを使用することを強く推奨します。このよくある質問はコンテキストステップの記事で例として参照できます。
GitHub でこのページを編集