Skip to content

ユーザーを追跡

post

/users/track

core endpoint

このエンドポイントを使用して、カスタムイベントと購入を記録し、ユーザープロファイル属性を更新します。

See me in Postman

前提条件

このエンドポイントを使用するには、users.track 権限を持つ API キーが必要です。

サーバー間の呼び出しに API を使用する顧客がファイアウォールの内側にいる場合には、rest.iad-01.braze.com を許可リストに登録する必要が生じることがあります。

レート制限

2024年10月28日から、すべての顧客に対して、このエンドポイントに3秒あたり3,000リクエストという基本速度制限を適用する。/users/track の各リクエストには、最大 75 個のイベントオブジェクト、75 個の属性オブジェクト、75 個の購買オブジェクトを含めることができます。各オブジェクト（イベント、アトリビュート、購入アレイ）は、それぞれ1人のユーザーを更新することができる。合計すると、1回の通話で最大225人のユーザーを更新できることになる。さらに、1つのユーザープロファイルを複数のオブジェクトで更新することもできる。

月間アクティブユーザー数 - CY 24-25 を購入した顧客には異なる制限が適用されます。これらの制限の詳細については、月間アクティブユーザー数 - CY 24-25 制限を参照してください。

詳細については、APIレート制限のページを参照のこと。また、制限の引き上げが必要な場合は、カスタマー・サクセス・マネージャーに連絡すること。

要求本文:

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5

{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object),
}

リクエストパラメーター

例のリクエスト

メールアドレスでユーザープロファイルを更新

/users/track エンドポイントを使用して、メールアドレスでユーザープロファイルを更新できます。

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
54
55
56
57
58
59
60
61
62
63
64
65
66

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "email": "[email protected]",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2022-12-06T19:20:45+01:00",
            "properties": {
                "release": {
                    "studio": "FilmStudio",
                    "year": "2022"
                },
                "cast": [
                    {
                        "name": "Actor1"
                    },
                    {
                        "name": "Actor2"
                    }
                ]
            }
        },
        {
            "user_alias": {
                "alias_name": "device123",
                "alias_label": "my_device_identifier"
            },
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2013-07-16T19:20:50+01:00"
        }
    ],
    "purchases": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "product_id": "product_name",
            "currency": "USD",
            "price": 12.12,
            "quantity": 6,
            "time": "2017-05-12T18:47:12Z",
            "properties": {
                "color": "red",
                "monogram": "ABC",
                "checkout_duration": 180,
                "size": "Large",
                "brand": "Backpack Locker"
            }
        }
    ]
}'

電話番号でユーザープロファイルを更新する

電話番号を使用して/users/trackエンドポイントでユーザープロファイルを更新できます。このエンドポイントは、有効な電話番号を含めた場合にのみ機能します。

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "phone": "+15043277269",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
}'

サブスクリプショングループを設定する

この例では、ユーザーを作成し、ユーザー属性オブジェクト内にサブスクリプショングループを設定する方法を示します。

このエンドポイントを使用してサブスクリプションステータスを更新すると、external_id で指定されたユーザー (User1 など) が更新され、そのユーザー (User1) と同じメールアドレスを持つすべてのユーザーのサブスクリプションステータスも更新されます。

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
  {
    "external_id": "user_identifier",
    "email": "[email protected]",
    "email_subscribe": "subscribed",
    "subscription_groups": [{
      "subscription_group_id": "subscription_group_identifier_1",
      "subscription_state": "unsubscribed"
      },
      {
        "subscription_group_id": "subscription_group_identifier_2",
        "subscription_state": "subscribed"
        },
        {
          "subscription_group_id": "subscription_group_identifier_3",
          "subscription_state": "subscribed"
        }
      ]
    }
  ]
}'

エイリアスのみのユーザーを作成するリクエスト例

リクエストの本文に_update_existing_onlyキーをfalseの値で設定することにより、新しいエイリアス専用ユーザーを作成するために/users/trackエンドポイントを使用できます。この値を省略すると、Brazeはエイリアスのみのユーザープロファイルを作成しない。エイリアスのみのユーザーを使用すると、そのエイリアスを持つ1つのプロファイルが存在することが保証されます。これは、Brazeが重複したユーザープロファイルを作成するのを防ぐため、新しい統合を構築するときに特に役立つ。

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
{
    "attributes": [
        {
            "_update_existing_only": false,
            "user_alias": {
                "alias_name": "example_name",
                "alias_label": "example_label"
            },
            "email": "[email protected]"
        }
    ],
}'

回答

これらのAPIリクエストのいずれかを使用する場合、次の3つの一般的な応答のいずれかを受け取るはずです: 成功メッセージ、非致命的なエラーを含む成功メッセージ、または致命的なエラーを含むメッセージ。

成功のメッセージ

メッセージングに成功すると、次のようなレスポンシブが返ってくる：

1
2
3
4
5
6

{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external_ids with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing,
}

非致命的なエラーがある成功メッセージ

メッセージが成功しているが、長いイベントリストの中に1つの無効なイベントオブジェクトが含まれているなどの致命的でないエラーがある場合、次の応答が返されます:

1
2
3
4
5
6
7
8

{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

成功メッセージの場合、Brazeはerrors 配列のエラーに影響されないデータを処理する。

致命的なエラーを含むメッセージ

メッセージに致命的なエラーがある場合、次の応答が返されます:

1
2
3
4
5
6
7
8

{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

致命的なエラー応答コード

リクエストが致命的なエラーに遭遇した場合にBrazeが返すステータスコードと関連するエラーメッセージについては、致命的エラー& レスポンスを参照のこと。

providedexternal_id is blacklisted and disallowed “というエラーが表示された場合、リクエストに “ダミーユーザー “が含まれている可能性がある。詳細については、「スパムのブロック」を参照してください。

よくある質問

同じメールアドレスを持つ複数のプロファイルが見つかった場合はどうなりますか？

external_id が存在する場合、Brazeは外部IDを持つ最も最近更新されたプロファイルを優先して更新する。external_id が存在しない場合、Brazeは最近更新されたプロファイルを優先して更新する。

メールアドレスのプロファイルが存在しない場合はどうなりますか？

Brazeは新しいプロファイルとEメールのみのユーザーを作成し、Eメールアドレスによるユーザープロファイルの更新リクエスト例で述べたように、Eメールフィールドを[email protected] に設定する。Brazeはエイリアスを作らない。

どのようにして/users/trackを使用してレガシーユーザーデータをインポートしますか？

まだモバイルアプリを使用していないユーザーのユーザープロファイルを生成するために、Braze APIを通じてデータを送信することができます。ユーザーがその後アプリケーションを使用する場合、SDKを使用した識別に続くすべての情報は、APIコールを使用して作成した既存のユーザープロファイルにマージされる。識別前にSDKによって匿名で記録されたユーザー行動は、既存のAPI生成ユーザープロファイルと統合された時点で失われる。

セグメンテーションツールは、アプリとのエンゲージメントの有無にかかわらず、これらのユーザーを含む。ユーザー API 経由でアップロードされたものの、アプリをまだ使用していないユーザーを除外する場合は、Session Count > 0 フィルターを追加します。

/users/trackは重複イベントをどのように処理しますか？

イベント配列内の各イベントオブジェクトは、指定された時間にユーザーによるカスタムイベントの単一の発生を表します。これは、Brazeに取り込まれる各イベントに独自のイベントIDがあることを意味し、「重複」イベントは別々のユニークなイベントとして扱われるということです。

/users/track は無効な階層化カスタム属性をどのように処理しますか？

ネストされたカスタム属性に無効な値(無効な時間形式やNULL値など)が含まれる場合、Brazeはリクエスト内のすべてのネストされたカスタム属性の更新を処理から除外する。これは、その特定の属性内のすべての階層化構造に適用されます。処理を成功させるには、階層化カスタム属性内のすべての値が有効であることを確認してから送信してください。

CY24-25の月間アクティブユーザー数、ユニバーサルMAU、Web MAU、モバイルMAU

月間アクティブユーザー数CY 24-25、ユニバーサルMAU、Web MAU、またはモバイルMAUを購入した顧客については、Brazeは/users/track エンドポイントで異なるレート制限を管理している：

  • 1時間あたりのレート制限は、アカウントで予想されるデータ取り込みアクティビティに応じて設定されます。このアクティビティは、購入した月間アクティブユーザー数、業界、季節、またはその他の要因に対応する場合があります。
  • 1 時間ごとの制限に加えて、Braze は 3 秒ごとに送信できるリクエストの数にバースト制限を適用します。
  • 各リクエストは、アトリビューション、イベント、購入オブジェクトを合わせて、最大75の更新をバッチすることができる。

予想される取り込みに基づく現在の制限は、ダッシュボードの [設定] > [API と識別子] > [API 使用状況ダッシュボード] にあります。システムの安定性を保護するためにレート制限を変更したり、アカウントのデータスループットを向上させる場合があります。毎時または毎秒のリクエスト制限とビジネスのニーズに関する質問や懸念については、Braze Supportまたはカスタマーサクセスマネージャーにお問い合わせください。

月間アクティブユーザー数（CY24-25）、ユニバーサルMAU、Web MAU、モバイルMAUのレート制限ヘッダー

レート制限のない(429 などの)すべてのレスポンスは、クライアントに時間ごとのレート制限ウィンドウの状態を示す以下のHTTPレスポンスヘッダーを含む。リクエストレートを管理するために、これらのヘッダーを使用することをお勧めする：

HTTP429 エラーが発生した場合、RateLimit-Limit 、RateLimit-Remaining 、RateLimit-Reset ヘッダーは返されないことに注意。エラーが発生すると、これらのヘッダーはX-Ratelimit-Retry-After 、 リクエストを開始できるまでの秒数を示す整数を返すヘッダーで置き換えられる。
Github   GitHub でこのページを編集
New Stuff!