変換の作成

Brazeデータ変換を使用すると、Webhook連携の構築および管理を行って、外部プラットフォームからBrazeへのデータフローを自動化できます。これらのWebhook連携により、さらに洗練されたマーケティングユースケースを強化できます。データ変換は、デフォルトのコードから構築することも、専用のテンプレートライブラリーを使用して特定の外部プラットフォームとの連携を開始することもできます。

前提条件

ステップ 1: ソースプラットフォームを特定する

Braze に接続する外部プラットフォームを特定し、そのプラットフォームが Webhook をサポートしていることを確認します。これらの設定は、「API 通知」や「Web サービスリクエスト」と呼ばれることもあります。

以下は Typeform の Webhook の例です。Typeform のプラットフォームにログインして設定できます。

ステップ 2: 変換を作成する

Brazeダッシュボードで、データ設定 > データ変換に移動します。

変換を作成を選択して変換に名前を付け、編集エクスペリエンスを選択します。

テンプレートを使用を選択すると、データ変換のユースケースを含むテンプレートライブラリーを参照できます。または、ゼロから作成を選択してデフォルトのコードテンプレートを読み込みます。

ゼロから作成する場合は、変換の送信先を選択します。テンプレートライブラリーからコードテンプレートを挿入することもできます。

注

additional templates or destinationsをご希望ですか？製品フィードバックの送信をご検討ください。

変換を作成すると、変換の詳細ビューが表示されます。ここでは、Webhookの詳細の下にこの変換に対して受信した最新のWebhookが表示され、変換コードの下に変換コードを記述するスペースが表示されます。

次のステップで使用するWebhook URLをコピーします。

ステップ 3:テスト Webhook を送信する (推奨)

このステップは任意ですが、ソースプラットフォームから新しく作成した変換にテスト Webhook を送信することをおすすめします。

1. 変換から URL をコピーします。
2. ソースプラットフォームで「テスト送信」機能を見つけ、この URL に送信するサンプル Webhook を生成させます。
   • ソースプラットフォームでリクエストタイプの入力を求められた場合は、POST を選択します。
   • ソースプラットフォームに認証オプションがある場合は、認証なしを選択します。
   • ソースプラットフォームでシークレットの入力を求められた場合は、シークレットなしを選択します。
3. Braze ダッシュボードでページを更新し、Webhook が受信されたかどうかを確認します。受信された場合は、最新の Webhook の下に Webhook ペイロードが表示されます。

Typeform の場合は次のようになります。

注

Braze Data Transformation は、Webhook に特別な検証や認証を必要とする外部プラットフォームにはまだ対応していない場合があります。webhook authentication for external platformsをご希望ですか？製品フィードバックの送信をご検討ください。

ステップ 4: 変換コードを記述する

JavaScript のコーディング経験がほとんどない場合や、より詳しい手順を確認したい場合は、Beginner - POST: Track users タブまたは Beginner - PUT: Update multiple catalog items タブに従って変換コードを記述してください。

開発者の方や JavaScript のコーディング経験が豊富な方は、Advanced - POST: Track users タブで変換コードを記述するための概要を確認してください。

ヒント

AI で変換コードを生成するには、変換コードエディターで Code with Operator を選択します。この機能を使用するには、変換に Webhook が送信されている必要があります。代わりに事前構築済みのテンプレートから始めるには、Insert Template を選択します。プロンプトの例については、データ変換コードの生成を参照してください。

Code with Operator は、アカウントで Operator が有効になっている場合にのみ使用できます。表示されない場合は、アカウントマネージャーにお問い合わせください。

• beginner - track users
• beginner - update catalog items
• advanced - track users

ここでは、さまざまな Webhook の値を Braze のユーザープロファイルにどのようにマッピングするかを定義する変換コードを記述します。

1. 新しい変換では、Transformation Code セクションに次のデフォルトテンプレートが表示されます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// 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;

2. 変換呼び出しにカスタム属性、カスタムイベント、購入を含める場合は、ステップ 3 に進んでください。それ以外の場合は、不要なセクションを削除します。
   
   
3. 各属性、イベント、購入オブジェクトには、ユーザー識別子として external_id、user_alias、braze_id、email、phone のいずれかが必要です。受信 Webhook のペイロードからユーザー識別子を見つけ、ペイロード行を使用してその値を変換コードにテンプレート化します。ペイロードオブジェクトのプロパティにアクセスするには、ドット表記を使用します。
   
   
4. 属性、イベント、購入として表現したい Webhook の値を見つけ、ペイロード行を使用してそれらの値を変換コードにテンプレート化します。ペイロードオブジェクトのプロパティにアクセスするには、ドット表記を使用します。
   
   
5. 各属性、イベント、購入オブジェクトの _update_existing_only の値を確認します。存在しない可能性のある新しいユーザーを変換で作成したい場合は、これを false に設定します。既存のプロファイルのみを更新する場合は、true のままにします。
   
   
6. Validate をクリックすると、コードの出力のプレビューが返され、有効な /users/track リクエストかどうかを確認できます。
   
   
7. 変換を有効化します。有効化する前にコードについてさらにサポートが必要な場合は、Braze のアカウントマネージャーにお問い合わせください。
   
   
8. ソースプラットフォームから Webhook の送信を開始します。変換コードは受信する Webhook ごとに実行され、ユーザープロファイルの更新が開始されます。

これで Webhook の統合は完了です。

ここでは、さまざまな Webhook の値を Braze のカタログアイテムの更新にどのようにマッピングするかを定義する変換コードを記述できます。

1. 新しい変換では、Transformation Code セクションに次のデフォルトテンプレートが含まれます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// 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;

2. /catalogs 送信先への変換では、更新する特定のカタログを定義するために catalog_name が必要です。このフィールドはハードコーディングすることも、ペイロード行を使用して Webhook のフィールドでテンプレート化することもできます。ペイロードオブジェクトのプロパティにアクセスするには、ドット表記を使用します。
   
   
3. items 配列の id フィールドで、カタログ内のどのアイテムを更新するかを定義します。これらのフィールドはハードコーディングすることも、ペイロード行を使用して Webhook のフィールドでテンプレート化することもできます。
   
   catalog_column はプレースホルダーの値であることに注意してください。アイテムオブジェクトには、カタログに存在するフィールドのみが含まれるようにしてください。
   
   
4. Validate を選択すると、コードの出力のプレビューが返され、複数のカタログアイテムを更新するエンドポイントに対する有効なリクエストかどうかを確認できます。
   
   
5. 変換を有効化します。有効化する前にコードについてさらにサポートが必要な場合は、Braze のアカウントマネージャーにお問い合わせください。
   
   
6. ソースプラットフォームに Webhook の送信を開始する設定があるかどうかを必ず確認してください。変換コードは受信する Webhook ごとに実行され、カタログアイテムの更新が開始されます。

これで Webhook の統合は完了です。

このステップでは、ソースプラットフォームからの Webhook ペイロードを JavaScript オブジェクトの戻り値に変換します。この戻り値は、/users/track エンドポイントのリクエスト本文の形式に従う必要があります。

• 変換コードはJavaScriptプログラミング言語で記述します。if/elseロジックなど、標準的なJavaScriptの制御フローがサポートされています。
• 変換コードはpayload変数を介してWebhookリクエストボディにアクセスします。この変数は、リクエストボディのJSONを解析して生成されるオブジェクトです。
• /users/trackエンドポイントでサポートされている機能はすべてサポートされています。以下が含まれます:
  • ユーザー属性オブジェクト、イベントオブジェクト、購入オブジェクト
  • ネストされた属性およびネストされたカスタムイベントプロパティ
  • 購読グループの更新
  • 識別子としてのメールアドレス

Validate を選択すると、コードの出力のプレビューが返され、有効な /users/track リクエストかどうかを確認できます。

注

外部ネットワークリクエスト、サードパーティライブラリ、および JSON 以外の Webhook は現在サポートされていません。

ステップ 5: 変換をモニタリングする

変換を有効化した後は、メインのTransformationsページで分析を参照し、パフォーマンスの概要を確認します。

• 受信リクエスト: この変換の URL で受信した Webhook の数です。受信リクエストが 0 の場合、ソースプラットフォームから Webhook が送信されていないか、接続を確立できていません。
• 配信: 受信リクエストを受け取った後、Data Transformation は変換コードを適用して、選択した Braze の送信先に送信します。

受信リクエストの 100% が配信につながることを目標にするとよいでしょう。配信数が受信リクエスト数を超えることはありません。

トラブルシューティング

より詳細なモニタリングとトラブルシューティングを行うには、Logsページで個々のログを参照してください。このページには、すべてのワークスペースにわたるすべての変換に対する直近 1,000 件の受信リクエストが記録されています。各ログを選択すると、受信リクエストの本文、変換の出力、および変換の送信先からのレスポンス本文を確認できます。

配信がない場合は、変換コードに構文エラーがないか確認し、コードがコンパイルされることを確認してください。次に、出力が有効な送信先リクエストであるかどうかを確認します。

配信数が受信リクエスト数より少ない場合は、少なくとも一部の Webhook が正常に配信されていることを示しています。変換ログでエラーの例を参照し、変換の出力が想定どおりかどうかを確認してください。変換コードが、受信する Webhook のすべてのバリエーションに対応していない可能性があります。