CDI を用いたゼロコピーパーソナライゼーション

CDI を使ってキャンバストリガーを同期し、ゼロコピーパーソナライゼーションを実現する方法を説明します。この機能は、データストレージソリューションからユーザー固有の情報にアクセスし、それを送信先のキャンバスに渡します。キャンバスステップには、Braze ユーザープロファイルに永続化されないパーソナライゼーションフィールドをオプションで含めることができます。

キャンバストリガーの同期

クイックスタートステップ

Braze CDI にすでに慣れている場合、キャンバストリガー同期のセットアップはユーザーデータ CDI 連携のプロセスにほぼ準じますが、以下の注意点があります。

• external ID またはユーザーエイリアス識別子のみがサポートされています。メールアドレスと電話番号は、サポートされている識別子ではありません。
• 既存の Braze ユーザーのみ同期できます。新規ユーザーは作成できません。
• properties が payload カラムに代わるものです。これはキャンバスのエントリプロパティとしてパーソナライゼーションに使用したいフィールドの JSON 文字列です。

始めるには、新しい同期を作成する際にデータタイプとして キャンバス Triggers を選択してください。

キャンバストリガーの使用

ステップ1:キャンバストリガー用のデータソースを設定する

• snowflake
• redshift
• bigquery
• databricks
• fabric
• ファイルストレージ

ステップ1.1:Snowflake でソーステーブルを設定する

以下の例の名前を使用するか、独自のデータベース名、スキーマ名、テーブル名を選択できます。テーブルの代わりにビューやマテリアライズドビューを使用することもできます。

1
2
3
4
5
6
7
8
9
10
11

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --at least one of external_id or alias_name and alias_label is required
     EXTERNAL_ID VARCHAR(16777216),
     --if using user alias, both alias_name and alias_label are required
     ALIAS_LABEL VARCHAR(16777216),
     ALIAS_NAME VARCHAR(16777216),
     PROPERTIES VARCHAR(16777216)
);

データベース名、スキーマ名、テーブル名は自由に付けられますが、カラム名は上記の定義と一致させる必要があります。

• UPDATED_AT:この行がテーブルに更新または追加された時刻です。Braze は UPDATED_AT が最後に同期された値よりも後の行を同期します。同じタイムスタンプを持つ新しい行がある場合、正確な境界タイムスタンプの行は再同期される可能性があります。
• ユーザー識別子カラムとして external_id または alias_name と alias_label のいずれかが必要です。これらは、キャンバスメッセージングをトリガーしたいユーザーを識別します。
  • EXTERNAL_ID:キャンバスにエントリするユーザーを識別します。Braze で使用されている external_id の値と一致する必要があります。
  • ALIAS_NAME と ALIAS_LABEL:これらのカラムはユーザーエイリアスオブジェクトを作成します。alias_name は一意の識別子である必要があり、alias_label はエイリアスの種類を指定します。ユーザーは異なるラベルで複数のエイリアスを持つことができますが、alias_label ごとに 1 つの alias_name しか持てません。
• PROPERTIES:キャンバスでパーソナライゼーションプロパティとして利用可能にするフィールドの JSON 文字列です。ユーザー固有の情報を含める必要があります。

注

プロパティはすべての行やユーザーに必須ではありません。ただし、プロパティの値は有効な JSON 文字列である必要があります。行にプロパティがない場合は、空の {} 文字列を入力してください。

ステップ1.2:認証情報を設定する

ロール、ウェアハウス、ユーザーを設定し、適切な権限を付与します。既存の同期から認証情報がある場合は再利用できますが、キャンバストリガーのソーステーブルへのアクセスを拡張してください。

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC TO ROLE BRAZE_INGESTION_ROLE;

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

ステップ1.3:ネットワークポリシーを設定する

アカウントにネットワークポリシーがある場合は、CDI サービス接続を有効にするために Braze の IP を許可リストに追加してください。IP のリストについては、クラウドデータ取り込みを参照してください。

ステップ1.1:Redshift でソーステーブルを設定する

以下の例の名前を使用するか、独自のデータベース名、スキーマ名、テーブル名を選択できます。テーブルの代わりにビューやマテリアライズドビューを使用することもできます。

1
2
3
4
5
6
7
8
9
10
11

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
    updated_at timestamptz default sysdate not null,
    --at least one of external_id or alias_name and alias_label is required
    external_id varchar not null,.
    --if using user alias, both alias_name and alias_label are required
    alias_label varchar,
    alias_name varchar,
    properties varchar(max)
 );

データベース名、スキーマ名、テーブル名は自由に付けられますが、カラム名は上記の定義と一致させる必要があります。

• UPDATED_AT:この行がテーブルに更新または追加された時刻です。Braze は UPDATED_AT が最後に同期された値よりも後の行を同期します。同じタイムスタンプを持つ新しい行がある場合、正確な境界タイムスタンプの行は再同期される可能性があります。
• ユーザー識別子カラムとして external_id または alias_name と alias_label のいずれかが必要です。これらは、キャンバスメッセージングをトリガーしたいユーザーを識別します。
  • EXTERNAL_ID:キャンバスにエントリするユーザーを識別します。Braze で使用されている external_id の値と一致する必要があります。
  • ALIAS_NAME と ALIAS_LABEL:これらのカラムはユーザーエイリアスオブジェクトを作成します。alias_name は一意の識別子である必要があり、alias_label はエイリアスの種類を指定します。ユーザーは異なるラベルで複数のエイリアスを持つことができますが、alias_label ごとに 1 つの alias_name しか持てません。
• PROPERTIES:キャンバスでパーソナライゼーションプロパティとして利用可能にするフィールドの JSON 文字列です。ユーザー固有の情報を含める必要があります。

注

プロパティはすべての行やユーザーに必須ではありません。ただし、プロパティの値は有効な JSON 文字列である必要があります。行にプロパティがない場合は、空の {} 文字列を入力してください。

ステップ1.2:認証情報を設定する

ロール、ウェアハウス、ユーザーを設定し、適切な権限を付与します。既存の同期から認証情報がある場合は再利用できますが、キャンバストリガーのソーステーブルへのアクセスを拡張してください。

1
2
3

CREATE USER braze_user PASSWORD '{password}';
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
GRANT SELECT ON TABLE CANVAS_TRIGGERS_SYNC TO braze_user;

ステップ1.3:ネットワークポリシーを設定する

アカウントにネットワークポリシーがある場合は、CDI サービス接続を有効にするために Braze の IP を許可リストに追加してください。IP のリストについては、クラウドデータ取り込みを参照してください。

ステップ1.1:ソーステーブル用の新しいプロジェクトまたはデータセットを作成する（オプション）

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

ステップ1.2:BigQuery でソーステーブルを設定する

ソーステーブルを作成する際は、以下を参照してください。

フィールド名	タイプ	必須
UPDATED_AT	Timestamp	はい
PROPERTIES	JSON	はい
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

注

プロパティはすべての行やユーザーに必須ではありません。ただし、プロパティの値は有効な JSON 文字列である必要があります。行にプロパティがない場合は、空の {} 文字列を入力してください。

1
2
3
4
5
6
7
8
9
10

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties JSON
);

ステップ1.3:認証情報を設定する

ユーザーを作成し、権限を付与します。別の同期から認証情報がある場合は、キャンバストリガーテーブルへのアクセス権がある限り再利用できます。

権限	目的
BigQuery Connection User	Braze が接続できるようにします。
BigQuery User	Braze がクエリの実行、メタデータの読み取り、テーブルの一覧表示を行えるようにします。
BigQuery Data Viewer	Braze がデータセットとその内容を表示できるようにします。
BigQuery Job User	Braze がジョブを実行できるようにします。

権限を付与した後、Braze がサービスアカウントとして認証する方法を設定します。

Workload Identity Federation: Braze プリンシパルをサービスアカウントにバインドすることで、キーを作成する必要がなくなります。手順については、Workload Identity Federation 用の Google Cloud の設定を参照してください。

サービスアカウントキー: JSON キーを生成します。手順については、Keys create and delete を参照してください。後で Braze ダッシュボードにアップロードします。

ステップ1.4:ネットワークポリシーを設定する

アカウントにネットワークポリシーがある場合は、CDI サービス接続を有効にするために Braze の IP を許可リストに追加してください。IP のリストについては、クラウドデータ取り込みを参照してください。

ステップ1.1:ソーステーブル用のカタログまたはスキーマを作成する

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

ステップ1.2:Databricks でソーステーブルを設定する

ソーステーブルを作成する際は、以下を参照してください。

フィールド名	タイプ	必須
UPDATED_AT	Timestamp	はい
PROPERTIES	JSON	はい
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

スキーマ名とテーブル名は自由に付けられますが、カラム名は上記の定義と一致させる必要があります。

• UPDATED_AT:この行がテーブルに更新または追加された時刻です。Braze は UPDATED_AT が最後に同期された値よりも後の行を同期します。同じタイムスタンプを持つ新しい行がある場合、正確な境界タイムスタンプの行は再同期される可能性があります。
• ユーザー識別子カラムとして external_id または alias_name と alias_label のいずれかが必要です。これらは、キャンバスメッセージングをトリガーしたいユーザーを識別します。
  • EXTERNAL_ID:キャンバスにエントリするユーザーを識別します。Braze で使用されている external_id の値と一致する必要があります。
  • ALIAS_NAME と ALIAS_LABEL:これらのカラムはユーザーエイリアスオブジェクトを作成します。alias_name は一意の識別子である必要があり、alias_label はエイリアスの種類を指定します。ユーザーは異なるラベルで複数のエイリアスを持つことができますが、alias_label ごとに 1 つの alias_name しか持てません。
• PROPERTIES:キャンバスでパーソナライゼーションプロパティとして利用可能にするフィールドの文字列または struct です。ユーザー固有の情報を含める必要があります。

注

プロパティはすべての行やユーザーに必須ではありません。ただし、プロパティの値は有効な JSON 文字列である必要があります。行にプロパティがない場合は、空の {} 文字列を入力してください。

1
2
3
4
5
6
7
8
9
10

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp(),
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties STRING, STRUCT, or MAP
);

ステップ1.3:認証情報を設定する

OAuth マシン間 (M2M) 認証情報を持つサービスプリンシパル（推奨）、またはパーソナルアクセストークンを作成します。別の同期から認証情報がある場合は、キャンバストリガーテーブルへのアクセス権がある限り再利用できます。

OAuth M2M: サービスプリンシパルを作成し、クライアントシークレットを生成し、サービスプリンシパルに SQL ウェアハウスの Can use 権限を付与し、キャンバストリガーテーブルに対する SELECT 権限を付与します。手順については、Braze の認証情報を作成するを参照してください。

パーソナルアクセストークン:

1. ユーザー名を選択し、User Settings を選択します。
2. Access tokens タブで、Generate new token を選択します。
3. トークンを識別するためのコメントを追加します（例:「Braze CDI」）。
4. 有効期限なしにするには Lifetime (days) を空白のままにして、Generate を選択します。
5. トークンをコピーし、Braze ダッシュボードで使用するために安全に保存します。

ステップ1.4:ネットワークポリシーを設定する

アカウントにネットワークポリシーがある場合は、CDI サービス接続を有効にするために Braze の IP を許可リストに追加してください。IP のリストについては、クラウドデータ取り込みを参照してください。

ステップ1.1:Fabric でソーステーブルを設定する

1
2
3
4
5
6
7
8
9
10
11

CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PROPERTIES VARCHAR NOT NULL,
  --at least one of external_id or alias_name and alias_label is required
  EXTERNAL_ID VARCHAR,
  --if using user alias, both alias_name and alias_label are required
  ALIAS_NAME VARCHAR,
  ALIAS_LABEL VARCHAR
)
GO

ステップ1.2:認証情報を設定する

サービスプリンシパルを作成し、権限を付与します。別の同期から認証情報がある場合は、アカウントテーブルへのアクセス権がある限り再利用できます。

ステップ1.3:ネットワークポリシーを設定する

アカウントにネットワークポリシーがある場合は、CDI サービス接続を有効にするために Braze の IP を許可リストに追加してください。IP のリストについては、クラウドデータ取り込みを参照してください。

ファイルストレージからキャンバストリガーを同期するには、以下のフィールドを含むソースファイルを作成します。

フィールド	必須	説明
EXTERNAL_ID	はい。external_id または alias_name と alias_label のいずれかが必要	更新したいユーザーを識別します。Braze で使用されている external_id の値と一致する必要があります。
ALIAS_NAME と ALIAS_LABEL	はい。external_id または alias_name と alias_label のいずれかが必要	これら 2 つのカラムはユーザーエイリアスオブジェクトを作成します。alias_name は一意の識別子である必要があり、alias_label はエイリアスの種類を指定します。ユーザーは異なるラベルで複数のエイリアスを持つことができますが、alias_label ごとに 1 つの alias_name しか持てません。
PROPERTIES	はい	キャンバスでパーソナライゼーションプロパティとして利用可能にするフィールドの JSON 文字列です。ユーザー固有の情報を含める必要があります。

ヒント

ファイル名は AWS のルールに従い、一意である必要があります。一意性を確保するためにタイムスタンプを付加してください。Amazon S3 同期の詳細については、ファイルストレージ連携を参照してください。

ステップ2:宛先キャンバスを設定する

1. キャンバストリガー用の宛先キャンバスを設定します。新しい API トリガーキャンバスを作成するか、既存のものを選択します。API トリガー配信スケジュールタイプのキャンバスの作成方法については、エントリスケジュールタイプを参照してください。
2. API トリガー配信スケジュールタイプを選択した後、キャンバスの設定を続行してキャンバスを構築します。キャンバスはシンプルな単一メッセージ送信から、複数のステップを持つ複雑な顧客ワークフローまで多岐にわたります。
3. キャンバスステップ内で、キャンバスエントリプロパティを使用して、ソーステーブルから同期する予定のプロパティフィールドでメッセージをパーソナライズします。
   • 例えば、ステップ1で account_balance のプロパティフィールドを設定した場合、以下の Liquid テンプレートを使用してメッセージをパーソナライズします: \{\{canvas_entry_properties.\$\{account_balance\}\}\}。
4. キャンバスの構築が完了したら、起動してステップ3に進みます。

ステップ3:ゼロコピー同期を作成する

ソースの設定が完了し、宛先キャンバスが起動したら、新しいデータ同期を作成します。

1. Braze で、データ設定 > クラウドデータ取り込みに移動します。
2. 接続の詳細（または既存の認証情報を再利用）とステップ1のソーステーブルを入力して接続を設定します。
3. 連携の名前を付けます。
4. キャンバス triggers データタイプを選択します。
5. 宛先キャンバスを選択します（ステップ2から）。
6. 同期頻度を選択します。
7. 通知設定を行います。
8. Test Connection を選択して、すべてが期待どおりに動作することを確認します。Snowflake に接続する場合は、まずダッシュボードに表示される公開キーを、Braze が Snowflake に接続するために作成したユーザーに追加します。このステップを完了するには、Snowflake で SECURITYADMIN 以上のアクセス権が必要です。
9. 同期を保存して、キャンバストリガーの同期を開始します。

同期が実行されると、ソーステーブル内のユーザーがキャンバスにエントリし始めます。キャンバスの分析とクラウドデータ取り込みの同期ログページを使用して、パフォーマンスを監視してください。

ヒント

予期しない送信を避けるために、同期の動作からキャンバスの設定まで、設定全体を確認してください。レート制限、フリークエンシーキャップ、セグメンテーションフィルターなどのキャンバス設定を使用して、メッセージ配信をさらに精緻化できます。

本番環境のユースケースを実装する前に、小規模なテストオーディエンスでトライアルランを実施することをお勧めします。

考慮事項

CDI キャンバストリガーは、/canvas/trigger/send の REST API レート制限を使用します。このエンドポイントを CDI キャンバストリガーと同時に使用している場合、合計使用量がレート制限にカウントされることに注意してください。

各同期実行は、1 時間あたり最大約 375 万ユーザーのレートで、それぞれの宛先キャンバスにユーザーをエントリさせます。以下の場合は、ソースからキャンバスエントリまでの時間が長くなることに備えてください。

• 1 回の同期実行で 375 万人以上のユーザーを同期する場合。
• REST APIの /canvas/trigger/send のレート制限をすでに最大限に使用している状態で CDI キャンバストリガーを使用する場合。

メッセージアーカイブが有効な場合のゼロコピー CDI について、以下を考慮してください。

• テーブルの結果は処理中に Braze 内に一時的に保存されます。また、同期された内容を正確に確認できるよう、Snowflake に 30 日間エクスポートされます。
• アーカイブされたメッセージは Braze 内のどこにも保存されません。コピーは、設定されたストレージにのみ保存されるために送信されます。
• キャンバストリガーでゼロコピー CDI を使用する場合、Braze はデータウェアハウスからのクエリ結果のバックアップを保存せず、データはユーザープロファイルにコピーされません。
• キャンバスのコンテキストプロパティは、内部システムに最大 30 日間ログが記録される場合があります。