ユーザーを追跡

post

/users/track

core endpoint

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

note:

Braze は API 経由で渡されたデータを額面通りに処理し、顧客は不要なデータポイントの消費を最小限に抑えるためにデルタ (変更されたデータ) のみを渡す必要があります。続きを読むには、データポイントを参照してください。

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人のユーザーを更新できることになります。さらに、単一のユーザープロファイルを複数のオブジェクトによって更新することもできます。

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

詳しくは、API レート制限のページを参照してください。制限を引き上げる必要がある場合は、カスタマーサクセスマネージャーに連絡してください。

要求本文:

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

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

リクエストパラメーター

important:

次のテーブルに記載されている各リクエストコンポーネントには、external_id、user_alias、braze_id、email、または phone のいずれかが必要です。

パラメーター	required	データ型	説明
`attributes`	オプション	属性オブジェクトの配列	ユーザー属性オブジェクトを参照してください
`events`	オプション	イベントオブジェクトの配列	イベントオブジェクトを参照してください
`purchases`	オプション	購入オブジェクトの配列	購入オブジェクトを参照してください

例のリクエスト

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

/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": "test@braze.com",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "test@braze.com",
            "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": "test@braze.com",
            "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エンドポイントでユーザープロファイルを更新できます。このエンドポイントは、有効な電話番号を含めた場合にのみ機能します。

important:

email とphone の両方を含むリクエストを含めると、Braze は電子メールを識別子として使用します。

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": "example@email.com",
    "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エンドポイントを使用できます。この値が省略された場合、エイリアスのみのユーザープロファイルは作成されません。エイリアスのみのユーザーを使用すると、そのエイリアスを持つ1つのプロファイルが存在することが保証されます。これは、新しい統合を構築する際に特に役立ちます。重複したユーザープロファイルの作成を防ぎます。

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@example.com"
        }
    ],
}'

回答

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

成功したメッセージ

成功したメッセージには次の応答が返されます:

{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed,
  "events_processed": (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed,
  "purchases_processed": (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed,
}

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

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

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

成功メッセージの場合、errors 配列内のエラーの影響を受けないデータは引き続き処理されます。

致命的なエラーが発生したメッセージ

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

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

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

ステータスコードおよび関連するエラーメッセージについては、リクエストが致命的なエラーに遭遇した場合に返される致命的なエラーと応答を参照してください。

「provided external_id is blacklisted and disallowed」というエラーを受け取った場合、リクエストに「dummyユーザー」が含まれている可能性があります。詳細については、「スパムのブロック」を参照してください。

よくある質問

important:

法的に要求されているトランザクションメールを SMS ゲートウェイに送信しないでください。これらのメールは配信されない可能性が高いためです。

電話番号とプロバイダーのゲートウェイドメイン（MM3として知られている）を使用して送信したメールは、SMS（テキスト）メッセージとして受信される可能性があるが、一部のメールプロバイダーはこの動作をサポートしていない。例えば、T-モバイルの電話番号（”9999999999@tmomail.net”など）にメールを送った場合、SMSメッセージはT-モバイル・ネットワークでその電話番号を所有している人に送信される。

これらのメールがSMSゲートウェイに配信されなくても、メール課金にはカウントされることを覚えておいてほしい。サポートされていないゲートウェイへのメール送信を避けるには、サポートされていないゲートウェイのドメイン名のリストを確認します。

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

external_id が存在する場合、external ID を持つ最新の更新されたプロファイルが更新の優先順位となります。external_idが存在しない場合、最も最近更新されたプロファイルが更新の優先対象となります。

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

新しいプロファイルが作成され、メール専用のユーザーが作成されます。エイリアスは作成されません。メールフィールドはtest@braze.comに設定されます。これは、メールアドレスによるユーザープロファイルの更新要求の例で示されています。

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

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

セグメンテーションツールは、ユーザーがアプリを使用したかどうかに関係なく、これらのユーザーを含めます。ユーザー API 経由でアップロードされたものの、アプリをまだ使用していないユーザーを除外する場合は、Session Count > 0 フィルターを追加します。

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

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

1か月あたりのアクティブユーザー数 CY 24-25

1か月あたりのアクティブユーザー数-CY 24-25 を購入した顧客の場合、Braze は /users/track エンドポイントでさまざまなレート制限を管理します。

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

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

GitHub でこのページを編集