Skip to content

購入オブジェクト

この記事では、購入オブジェクトのさまざまなコンポーネント、正しい使用方法、ベストプラクティス、参考となる例について説明します。

購入オブジェクトとは？

購入オブジェクトは、購入が行われたときにAPIを通じて渡されるオブジェクトです。各購入オブジェクトは購入配列内に配置され、各オブジェクトは特定のユーザーによる特定の時点での単一の購入を表します。購入オブジェクトにはさまざまなフィールドがあり、Brazeバックエンドがこの情報を保存して、カスタマイズ、データ収集、パーソナライゼーションに使用できるようにします。

オブジェクト本体

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required.
  "external_id" : (optional, string) External user ID,
  "user_alias" : (optional, User Alias Object) User alias object,
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  "app_id" : (optional, string) see App Identifier,
  // See the following product_id naming conventions for clarification.
  "product_id" : (required, string) identifier for the purchase, for example, Product Name or Product Category,
  "currency" : (required, string) ISO 4217 Alphabetic Currency Code,
  //Revenue from a purchase object is calculated as the product of quantity and price.
  "price" : (required, float) value in the base currency unit (for example, Dollars for USD, Yen for JPY),
  "quantity" : (optional, integer) the quantity purchased (defaults to 1, must be <= 100 -- currently, Braze treats a quantity _X_ as _X_ separate purchases with quantity 1),
  "time" : (required, datetime as string in ISO 8601) Time of purchase,
  // See the following purchase object explanation for clarification.
  "properties" : (optional, Properties Object) properties of the event,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" mode is always true.
  "_update_existing_only" : (optional, boolean)
}

購入プロダクト ID

購入オブジェクト内の product_id は、購入の識別子です（Product Name や Product Category など）。

  • Braze では、ダッシュボードに最大5,000個の product_id を保存できます。
  • product_id は最大255文字です。

命名規則

Braze では、購入オブジェクトの product_id に関する一般的な命名規則を提供しています。product_id を選択する際、Braze では（SKU ではなく）商品名や商品カテゴリーなどのシンプルな名前を使用することを推奨しています。これは、この product_id で記録されたすべてのアイテムをグループ化することを意図しています。

これにより、セグメンテーションやトリガーで商品を識別しやすくなります。

注文レベルでの購入記録

商品レベルではなく注文レベルで購入を記録したい場合は、注文名や注文カテゴリーを product_id として使用できます（Online Order や Completed Order など）。

たとえば、Web SDKで注文レベルの購入を記録するには、次のようにします。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "Completed Order",
      "currency" : "USD",
      "price" : 219.98,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99, },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99, }
        ]
      }
    }
  ]
}

購入プロパティオブジェクト

The properties values must be an object up to 50 KB where the keys are the property names and the values are the property values. Property names must be strings, 255 characters or fewer, with no leading dollar signs ($).

Property values can be any of the following data types:

Data type Description
Number Integer or float
Boolean Value true or false
Datetime String in ISO 8601 or yyyy-MM-dd'T'HH:mm:ss:SSSZ format. Not supported within arrays.
String 255 characters or fewer
Array Supported; datetimes are not supported within arrays.
Object Ingested as strings (not nested objects). For nested data, use a string value (for example, JSON serialized).

The following keys are reserved and cannot be used as property names: time, product_id, quantity, event_name, price, and currency. Using a reserved key in the properties object returns the error “Invalid ‘properties’ field”.

カスタム属性、イベントプロパティ、カタログにわたるデータタイプの統合リファレンスについては、データタイプを参照してください。

購入プロパティ

購入プロパティは、Liquidを使用したメッセージのトリガーやパーソナライゼーションに使用でき、これらのプロパティに基づいてセグメント化することもできます。

命名規則

この機能は購入ごとではなく、製品ごとに有効であることに注意してください。たとえば、個別の製品が大量にあっても、それぞれのプロパティが同じである場合、セグメンテーションは不要になる可能性があります。

この場合、データ構造を設定する際に、トランザクションレベルの識別子ではなく「グループレベル」で製品名を使用することをお勧めします。たとえば、鉄道チケット会社では、「片道」、「往復」、「複数都市」といった製品を用意すべきであり、「取引123」や「取引046」などの特定の取引名にすべきではありません。別の例として、「食べ物」の購入イベントでは、プロパティは「ケーキ」や「サンドイッチ」に設定するのが最適です。

購入オブジェクトの例

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

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "backpack",
      "currency" : "USD",
      "price" : 40.00,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "color" : "red",
        "monogram" : "ABC",
        "checkout_duration" : 180,
        "size" : "Large",
        "brand" : "Backpack Locker"
      }
    },
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pencil",
      "currency" : "USD",
      "price" : 2.00,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "number" : 2,
        "sharpened" : true
      }
    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pen",
      "currency" : "USD",
      "price" : 2.50,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "color" : "blue",
      }
    }
  ]
}

購入オブジェクト、イベントオブジェクト、およびwebhook

提供された例を使用すると、誰かが色、モノグラム、チェックアウト時間、サイズ、ブランドのプロパティを持つバックパックを購入したことがわかります。次に、購入イベントプロパティを使用してこれらのプロパティでセグメントを作成したり、Liquidを使用してチャネル経由でカスタムメッセージを送信したりできます。たとえば、「こんにちは Ann F. さん、赤のミディアムバックパックを $40.00 でご購入いただきありがとうございます！Backpack Locker でのお買い物ありがとうございました！」

プロパティを保存、保管、追跡してセグメント化に使用する場合は、それらをカスタム属性として設定する必要があります。これはセグメントエクステンションを使用して行うことができ、カスタムイベントやそのユーザープロファイルの生涯にわたって保存される購入行動に基づいてユーザーをターゲットにすることができます。
New Stuff!