変換の作成
Brazeデータ変換を使用すると、Webhook連携を構築および管理して、外部プラットフォームからBrazeへのデータフローを自動化できます。これらのWebhook連携により、さらに高度なマーケティングユースケースを実現できます。データ変換は、デフォルトのコードから構築することも、専用のテンプレートライブラリーを使用して特定の外部プラットフォームとの連携を始めることもできます。
前提条件
| 要件 | 説明 |
|---|---|
| 2 要素認証または SSO | アカウントで 2 要素認証 (2FA) またはシングルサインオン (SSO) が有効になっている必要があります。 |
| 適切な権限 | アカウント管理者またはワークスペース管理者であるか、「Manage Transformations」ユーザー権限を持っている必要があります。 |
ステップ 1: ソースプラットフォームを特定する
Braze に接続したい外部プラットフォームを特定し、そのプラットフォームが Webhook をサポートしていることを確認します。これらの設定は、「API 通知」や「Web サービスリクエスト」と呼ばれることもあります。
以下は、Typeform の Webhook の例です。Typeform のプラットフォームにログインすると設定できます。

ステップ2: 変換を作成する
Brazeダッシュボードで、データ設定 > データ変換に移動します。
変換を作成を選択して変換に名前を付け、編集エクスペリエンスを選択します。

テンプレートを使用を選択すると、データ変換のユースケースを含むテンプレートライブラリーを参照できます。または、ゼロから作成を選択してデフォルトのコードテンプレートを読み込みます。
ゼロから作成する場合は、変換の送信先を選択します。テンプレートライブラリーからコードテンプレートを挿入することもできます。
送信先の詳細
- POST: Track users: ソースプラットフォームからのWebhookを、属性、イベント、購入などのユーザープロファイル更新に変換します。
- PUT: Update multiple catalog items: ソースプラットフォームからのWebhookをカタログアイテムの更新に変換します。
- DELETE: Delete multiple catalog items: ソースプラットフォームからのWebhookをカタログアイテムの削除に変換します。
- PATCH: Edit multiple catalog items: ソースプラットフォームからのWebhookをカタログアイテムの編集に変換します。
- POST: Send messages immediately via API Only: ソースプラットフォームからのWebhookを変換し、指定したユーザーに即座にメッセージを送信します。

変換を作成すると、変換の詳細ビューが表示されます。ここでは、Webhookの詳細の下にこの変換に対して受信した最新のWebhookが表示され、変換コードの下に変換コードを記述するスペースが表示されます。
次のステップで使用するWebhook URLをコピーします。
ステップ 3: テスト Webhook を送信する (推奨)
このステップは任意ですが、ソースプラットフォームから新しく作成した変換にテスト Webhook を送信することをおすすめします。
- 変換から URL をコピーします。
- ソースプラットフォームで「テスト送信」機能を見つけ、この URL に送信するサンプル Webhook を生成させます。
- ソースプラットフォームでリクエストタイプの指定を求められた場合は、POST を選択します。
- ソースプラットフォームで認証オプションが提供されている場合は、認証なしを選択します。
- ソースプラットフォームでシークレットの指定を求められた場合は、シークレットなしを選択します。
- Braze ダッシュボードでページを更新し、Webhook が受信されたかどうかを確認します。受信されていれば、最新の Webhook の下に Webhook ペイロードが表示されます。
Typeform の場合は次のようになります。


Braze Data Transformation は、Webhook に特別な検証や認証を必要とする外部プラットフォームにはまだ対応していない場合があります。webhook authentication for external platformsをご希望ですか?製品フィードバックの送信をご検討ください。
ステップ 4: 変換コードを記述する
JavaScript コードの経験がほとんどない場合や、より詳しい手順を確認したい場合は、初級 - POST: ユーザーを追跡タブまたは初級 - PUT: 複数のカタログアイテムを更新タブに従って変換コードを記述してください。
開発者の方や JavaScript コードの経験が豊富な方は、上級 - POST: ユーザーを追跡タブで変換コード記述の概要を確認してください。

AI で変換コードを生成するには、変換コードエディターで Operatorでコーディングを選択します。この機能を使用するには、変換に Webhook が送信されている必要があります。事前構築済みのテンプレートから始める場合は、テンプレートを挿入を選択します。プロンプトの例については、データ変換コードを生成するを参照してください。
Operatorでコーディングは、アカウントで Operator が有効になっている場合にのみ使用できます。表示されない場合は、アカウントマネージャーにお問い合わせください。
ここでは、さまざまな Webhook の値を Braze のユーザープロファイルにどのようにマッピングするかを定義する変換コードを記述します。
- 新しい変換には、変換コードセクションに次のデフォルトテンプレートが含まれています。
// Here, we will define a variable, "brazecall", to build up a `/users/track` request
// Everything from the incoming webhook is accessible via the special variable "payload"
// So you can template in desired values in your `/users/track` request with dot notation, such as payload.x.y.z
let brazecall = {
"attributes": [
{
"external_id": payload.user_id,
"_update_existing_only": true,
"attribute_1": payload.attribute_1
}
],
"events": [
{
"external_id": payload.user_id,
"_update_existing_only": true,
"name": payload.event_1,
"time": new Date(),
"properties": {
"property_1": payload.event_1.property_1
}
}
],
"purchases": [
{
"external_id": payload.user_id,
"_update_existing_only": true,
"product_id": payload.product_id,
"currency": payload.currency,
"price": payload.price,
"quantity": payload.quantity,
"time": payload.timestamp,
"properties": {
"property_1": payload.purchase_1.property_1
}
}
]
};
// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
- 変換呼び出しにカスタム属性、カスタムイベント、購入をすべて含める場合は、ステップ 3 に進んでください。それ以外の場合は、不要なセクションを削除します。
- 各属性、イベント、購入オブジェクトには、
external_id、user_alias、braze_id、email、phoneのいずれかのユーザー識別子が必要です。受信 Webhook のペイロードからユーザー識別子を見つけ、ペイロード行を使用して変換コードにその値をテンプレート化します。ペイロードオブジェクトのプロパティにアクセスするには、ドット表記を使用します。 - 属性、イベント、または購入として表現したい Webhook の値を見つけ、ペイロード行を使用して変換コードにそれらの値をテンプレート化します。ペイロードオブジェクトのプロパティにアクセスするには、ドット表記を使用します。
- 各属性、イベント、購入オブジェクトについて、
_update_existing_onlyの値を確認します。デフォルトテンプレートではこの値がtrueに設定されており、既存のユーザープロファイルのみが更新されます。ユーザーが存在しない場合に新規ユーザーを作成するには、この値をfalseに設定します。オブジェクトからこのフィールドを完全に省略した場合、動作はfalseと同じになります (新規ユーザーが作成されます)。 - 検証をクリックすると、コードの出力のプレビューが返され、有効な
/users/trackリクエストかどうかを確認できます。 - 変換を有効にします。有効にする前にコードについてさらにサポートが必要な場合は、Braze のアカウントマネージャーにお問い合わせください。
- ソースプラットフォームから Webhook の送信を開始します。受信 Webhook ごとに変換コードが実行され、ユーザープロファイルの更新が開始されます。
これで Webhook の統合は完了です。
ここでは、さまざまな Webhook の値を Braze のカタログアイテムの更新にどのようにマッピングするかを定義する変換コードを記述できます。
- 新しい変換には、変換コードセクションに次のデフォルトテンプレートが含まれます。
// This is a default template that you can use as a starting point
// Feel free to delete this entirely and create a new transformation, or edit specific components
// First, this code defines a variable, "brazecall", to build a PUT /catalogs/{catalog_name}/items request
// Everything from the incoming webhook is accessible via the special variable "payload"
// As such, you can template in desired values in your request with JS dot notation, such as payload.x.y.z
let brazecall = {
// For Braze Data Transformation to update Catalog items, the special variable "catalog_name" is required
// This variable is used to specify the catalog name which would otherwise go in the request URL
"catalog_name": "catalog_name",
// After defining "catalog name", construct the Update Multiple Catalog Items request as usual below
// Documentation for the destination endpoint: /docs/ja/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/
"items": [
{
"id": payload.item_id_1,
"catalog_column1": "string",
"catalog_column2": 1,
"catalog_column3": true,
"catalog_column4": "2021-09-03T09:03:19.967+00:00",
"catalog_column5": {
"Latitude": 33.6112,
"Longitude": -117.8711
}
},
{
"id": payload.item_id_2,
"catalog_column1": "string",
"catalog_column2": 1,
"catalog_column3": true,
"catalog_column4": "2021-09-03T09:03:19.967+00:00",
"catalog_column5": {
"Latitude": 33.6112,
"Longitude": -117.8711
}
},
{
"id": payload.item_id_3,
"catalog_column1": "string",
"catalog_column2": 1,
"catalog_column3": true,
"catalog_column4": "2021-09-03T09:03:19.967+00:00",
"catalog_column5": {
"Latitude": 33.6112,
"Longitude": -117.8711
}
}
]
};
// After the request body is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
/catalogs送信先への変換では、更新する特定のカタログを定義するためにcatalog_nameが必要です。このフィールドはハードコーディングすることも、ペイロード行を使用して Webhook のフィールドでテンプレート化することもできます。ペイロードオブジェクトのプロパティにアクセスするには、ドット表記を使用します。- items 配列の
idフィールドで、カタログ内の更新したいアイテムを定義します。これらのフィールドはハードコーディングすることも、ペイロード行を使用して Webhook のフィールドでテンプレート化することもできます。
catalog_columnはプレースホルダーの値であることに注意してください。アイテムオブジェクトには、カタログに存在するフィールドのみが含まれるようにしてください。 - 検証を選択すると、コードの出力のプレビューが返され、複数のカタログアイテムを更新するエンドポイントに対する有効なリクエストかどうかを確認できます。
- 変換を有効にします。有効にする前にコードについてさらにサポートが必要な場合は、Braze のアカウントマネージャーにお問い合わせください。
- ソースプラットフォームに Webhook の送信を開始する設定があるかどうかを必ず確認してください。受信 Webhook ごとに変換コードが実行され、カタログアイテムの更新が開始されます。
これで Webhook の統合は完了です。
このステップでは、ソースプラットフォームからの Webhook ペイロードを JavaScript オブジェクトの戻り値に変換します。この戻り値は、/users/track エンドポイントのリクエスト本文の形式に従う必要があります。
- 変換コードはJavaScriptプログラミング言語で記述します。if/elseロジックなど、標準的なJavaScriptの制御フローがサポートされています。
- 変換コードは
payload変数を介してWebhookリクエストボディにアクセスします。この変数は、リクエストボディのJSONを解析して生成されるオブジェクトです。 /users/trackエンドポイントでサポートされている機能はすべてサポートされています。以下が含まれます:- ユーザー属性オブジェクト、イベントオブジェクト、購入オブジェクト
- ネストされた属性およびネストされたカスタムイベントプロパティ
- 購読グループの更新
- 識別子としてのメールアドレス
検証を選択すると、コードの出力のプレビューが返され、有効な /users/track リクエストかどうかを確認できます。

外部ネットワークリクエスト、サードパーティライブラリー、および JSON 以外の Webhook は現在サポートされていません。
ステップ5: 変換をモニタリングする
変換を有効にした後は、メインの変換ページの分析でパフォーマンスの概要を確認してください。
- 受信リクエスト: この変換のURLで受信したWebhookの数です。受信リクエストが0の場合、ソースプラットフォームがまだWebhookを送信していないか、接続を確立できていません。
- 配信: 受信リクエストを受け取った後、データ変換は変換コードを適用し、選択したBrazeの送信先に送信します。
受信リクエストの100%が配信につながることを目標にするとよいでしょう。配信数が受信リクエスト数を超えることはありません。
トラブルシューティング
より詳細なモニタリングとトラブルシューティングを行うには、ログページで個別のログを確認してください。このページには、すべてのワークスペースのすべての変換に対する直近1,000件の受信リクエストが記録されています。各ログを選択すると、受信リクエストの本文、変換の出力、変換の送信先からのレスポンス本文を確認できます。
配信がない場合は、変換コードに構文エラーがないか確認し、コードがコンパイルされることを確認してください。次に、出力が有効な送信先リクエストかどうかを確認します。
配信数が受信リクエスト数より少ない場合は、少なくとも一部のWebhookが正常に配信されていることを示しています。変換ログでエラーの例を確認し、変換の出力が想定どおりかどうかを確認してください。変換コードが、受信するWebhookのすべてのバリエーションに対応していない可能性があります。