ユーザー属性オブジェクト

属性オブジェクトに任意のフィールドを含む API リクエストは、指定されたユーザープロファイル上で、その名前の属性を指定された値で作成または更新します。

Braze のユーザープロファイルフィールド名（以下に記載されているもの、または Braze ユーザープロファイルフィールドのセクションに記載されているもの）を使用して、ダッシュボードのユーザープロファイル上のこれらの特別な値を更新したり、独自のカスタム属性データをユーザーに追加したりします。

オブジェクト本文

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

{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required
  "external_id" : (optional, string) see external user ID,
  "user_alias" : (optional, User alias object),
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" defaults to true.
  "_update_existing_only" : (optional, boolean),
  // See note regarding anonymous push token imports
  "push_token_import" : (optional, boolean),
  // Braze User Profile Fields
  "first_name" : "Alex",
  "email" : "[email protected]",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
  // Array of objects custom attribute
  "my_array_of_objects_attribute": [{"key": "value"}, {"key": "value"}],
  // Adding to an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$add": [{"key": "value"}] },
  // Removing from an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• 外部ユーザー ID
• ユーザーエイリアス

注

通常の配列カスタム属性には、add と remove ($ なし) を使用します。

オブジェクトの配列 (階層化カスタム属性) には、/users/track リクエストのペイロードで $add、$remove、$update を使用します。これらの演算子は、識別子 ($identifier_key と $identifier_value) を照合してオブジェクト単位で変更を適用し、$new_object によるその場での更新をサポートします。

既存の配列内でオブジェクトを追加、削除、または更新しつつ、配列の残りの状態を維持したい場合は、この形式を使用します。リクエストの完全な例については、オブジェクトの配列の API 例とオブジェクトの配列の SDK 例を参照してください。

プロファイル属性を削除するには、その属性を null に設定します。external_id や user_alias などの一部のフィールドは、ユーザープロファイルに追加した後は削除できません。

識別子の解決

匿名プッシュトークンのインポートを実行する場合を除き、各ユーザー属性オブジェクトには少なくとも 1 つの識別子 (external_id、user_alias、braze_id、email、または phone) を含める必要があります。どのユーザープロファイルが更新または作成されるのかが曖昧にならないよう、可能な限りオブジェクトごとに識別子を 1 つだけ含めてください。

識別子を使用する際は、次の点に注意してください。

• external_id と user_alias は同時に使用できません。 同じユーザー属性オブジェクトに両方を含めると、エラーが返されます。すでに external_id を持つユーザーにエイリアスを追加するには、/users/alias/new エンドポイントを使用してください。
• email は phone よりも優先されます。 同じオブジェクトに email と phone の両方が含まれている場合、Braze は email を識別子として使用します。つまり、電話番号が別のプロファイルに属している場合でも、属性はそのメールアドレスに関連付けられたユーザープロファイルに適用されます。

重要

予期しない動作を避けるため、ユーザー属性オブジェクトごとに識別子を 1 つだけ使用してください。異なるユーザープロファイルを参照する複数の識別子を指定すると、属性が誤ったプロファイルに適用される可能性があります。

既存のプロファイルのみを更新する

Braze 内の既存のユーザープロファイルのみを更新したい場合は、リクエストの本文内で _update_existing_only キーを値 true で渡してください。この値を省略すると、external_id がまだ存在しない場合に Braze は新しいユーザープロファイルを作成します。

注

/users/track エンドポイントを使用してエイリアスのみのユーザープロファイルを作成する場合は、_update_existing_only を false に設定する必要があります。この値を省略すると、Braze はエイリアスのみのプロファイルを作成しません。

プッシュトークンのインポート

Braze にプッシュトークンをインポートする前に、本当にインポートが必要かどうかを確認してください。Braze SDKを導入すると、SDKがプッシュトークンを自動的に処理するため、API を通じてアップロードする必要はありません。

API を通じてアップロードする必要がある場合は、識別済みユーザーまたは匿名ユーザーのどちらに対してもアップロードできます。つまり、external_id が存在するか、匿名ユーザーの push_token_import フラグが true に設定されている必要があります。

注

他のシステムからプッシュトークンをインポートする場合、external_id が常に利用できるとは限りません。Braze への移行中もこれらのユーザーとのコミュニケーションを維持するには、push_token_import を true に指定することで、external_id を指定せずに匿名ユーザーのレガシートークンをインポートできます。

push_token_import を true に指定する場合:

• external_id と braze_id は指定しないでください
• 属性オブジェクトにはプッシュトークンを必ず含めてください
• トークンがすでに Braze に存在する場合、リクエストは無視されます。存在しない場合、Braze はトークンごとに一時的な匿名ユーザープロファイルを作成し、これらのユーザーへのメッセージ送信を継続できるようにします

インポート後、各ユーザーが Braze 対応バージョンのアプリを起動すると、Braze はインポートされたプッシュトークンをそのユーザーの Braze ユーザープロファイルに自動的に移動し、一時的なプロファイルをクリーンアップします。

Braze は月に 1 回、push_token_import フラグを持ちながらプッシュトークンを持たない匿名プロファイルがないかを確認します。匿名プロファイルにプッシュトークンがなくなっている場合、Braze はそのプロファイルを削除します。ただし、匿名プロファイルにまだプッシュトークンがある場合は、実際のユーザーがそのプッシュトークンを持つデバイスにまだログインしていないことを示しているため、Braze は何もしません。

詳細については、プッシュトークンの移行を参照してください。

カスタム属性のデータ型

カスタム属性として保存できるデータ型は次のとおりです。

ヒント

カスタムイベントとカスタム属性の使い分けに関するガイダンスについては、カスタムイベントとカスタム属性を参照してください。

オブジェクトの配列の例

このオブジェクトの配列を使用すると、宿泊内の特定の条件に基づいてセグメントを作成したり、Liquid テンプレートで各宿泊のデータを使用してメッセージをパーソナライズしたりできます。

1
2
3
4

{"hotel_stays": [
  { "hotel_name": "Ocean View Resort", "check_in_date": "2023-06-15", "nights_stayed": 5 },
  { "hotel_name": "Mountain Lodge", "check_in_date": "2023-09-10", "nights_stayed": 3 }
]}

$add、$remove、$update を使用するオブジェクトの配列の例については、オブジェクトの配列の API 例とオブジェクトの配列の SDK 例を参照してください。

Braze ユーザープロファイルフィールド

重要

次のユーザープロファイルフィールドは大文字と小文字が区別されるため、必ず小文字で参照してください。

ヒント

カテゴリ別に整理され、SDK、API、CSV、Cloud Data Ingestion に関するガイダンスを含む標準属性項目の顧客向けリファレンスについては、標準属性項目を参照してください。

この API を通じて明示的に設定された言語の値は、Braze がデバイスから自動的に受信するロケール情報よりも優先されます。

ユーザー属性のリクエスト例

この例には 4 つのユーザー属性オブジェクトが含まれています。API 呼び出しごとに許可される属性オブジェクトは合計 75 個です。

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

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Alex",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Lee",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": "Your App Identifier", "token": "abcd", "device_id": "optional_field_value"}]

    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "first_name" : "Yuri",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

プッシュトークンを移行する

Braze を統合する前に、独自に、または別のプロバイダーを通じてプッシュ通知を送信していた場合、プッシュトークンを移行すると、プッシュトークンが登録されているユーザーに引き続きプッシュ通知を送信できます。

SDK による自動移行

Braze SDKを統合すると、オプトインしたユーザーのプッシュトークンは、次回そのユーザーがアプリを開いたときに自動的に移行されます。それまでは、Braze からそれらのユーザーにプッシュ通知を送信できません。

または、プッシュトークンを手動で移行して、ユーザーとのエンゲージメントをより迅速に再開することもできます。

Web トークンに関する考慮事項

Web プッシュトークンの性質上、Web 向けのプッシュを実装する際は、次の点を必ず考慮してください。

API による手動移行

プッシュトークンの手動移行とは、以前に作成したこれらのキーを API 経由で Braze プラットフォームにインポートするプロセスです。

users/track エンドポイントを使用して、iOS (APNs) および Android (FCM) のトークンをプログラムでプラットフォームに移行します。識別済みユーザー (external ID が関連付けられているユーザー) と匿名ユーザー (external ID がないユーザー) の両方を移行できます。

注

Brazeは、インポートされたプッシュトークンをアプリと環境に対する有効なフォアグラウンドプッシュトークンとして扱います。

iOSトークンをインポートする際、BrazeはそれらのApple Push Notification service（APNs）ゲートウェイ（developmentまたはproduction）を保存しません。Brazeはアプリの設定済みゲートウェイを通じてこれらのトークンに送信します。トークンが別の環境用に生成されたものであった場合、APNsはBadDeviceTokenとして拒否し、送信はバウンスされます。

Brazeがトークンのゲートウェイを保存するのは、SDKが後から同じトークンを登録し、ゲートウェイを報告した場合のみです。

プッシュトークンの移行時にはアプリの app_id を指定して、適切なプッシュトークンを適切なアプリに関連付けます。各アプリ (iOS、Android など) には独自の app_id があり、API キーページの 識別 セクションで確認できます。必ず正しいプラットフォームの app_id を使用してください。

重要

API を使用して Web プッシュトークンを移行することはできません。これは、Web プッシュトークンが他のプラットフォームと同じスキーマに準拠していないためです。

Web プッシュトークンをプログラムで移行しようとすると、次のようなエラーが表示される場合があります: Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

API による移行の代わりに、SDKを統合し、トークンベースが自然に再構築されるようにすることをお勧めします。

• external id present
• external id missing

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-API-KEY-HERE' \
--data-raw '{
  "attributes" : [
    {
      "push_token_import" : false,
      "external_id": "example_external_id",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING"}
      ]
    }
  ]
}'

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    },

    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE_1": "YOUR_VALUE",
      "YOUR_CUSTOM_ATTRIBUTE_2": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    }
  ]
}'

iOS プッシュトークンをインポートする

/users/track で iOS プッシュトークンを移行する場合、プッシュトークンに gateway フィールドは設定されません。Braze は API 経由でインポートされたトークンを有効なフォアグラウンドプッシュトークンとみなしますが、そのトークンがどの APNs 環境に属するかを判断することはできません。

gateway フィールドがない場合、Braze はプッシュ通知の送信時にアプリで設定されたフォールバック環境の設定を使用します。トークンの実際の環境が設定されたフォールバックと異なる場合、BadDeviceToken エラーが発生する可能性があります。たとえば、開発用トークンを本番ゲートウェイ経由で送信すると失敗します。

配信の問題を避けるには、次の点に注意してください。

• Braze ダッシュボードにおけるアプリの環境設定が、インポートするトークンと一致していることを確認してください。
• 本番アプリの場合は、本番用トークンのみをインポートしてください。
• テスト環境の場合は、アプリの設定とインポートするトークンの両方が開発環境を使用していることを確認してください。

注

Braze SDKを通じて登録されたトークンには gateway フィールドが自動的に含まれます。SDKがアプリのエンタイトルメントから環境を検出するためです。

Android プッシュトークンをインポートする

重要

以下の考慮事項は Android アプリにのみ適用されます。iOS アプリではこれらの手順は必要ありません。iOS プラットフォームにはプッシュを表示するためのフレームワークが 1 つしかなく、Braze が必要なプッシュトークンと証明書を持っていれば、プッシュ通知はすぐに表示されるためです。

Braze SDKの統合が完了する前にユーザーに Android プッシュ通知を送信する必要がある場合は、キーと値のペアを使用してプッシュ通知を検証してください。

プッシュペイロードを処理して表示するためのレシーバーが必要です。レシーバーにプッシュペイロードを通知するには、必要なキーと値のペアをプッシュキャンペーンに追加します。これらのペアの値は、Braze 以前に使用していたプッシュパートナーによって異なります。

注

一部のプッシュ通知プロバイダーでは、キーと値のペアを正しく解釈できるように、Braze がキーと値のペアをフラット化する必要があります。特定の Android アプリのキーと値のペアをフラット化するには、カスタマーサクセスマネージャーにお問い合わせください。

よくある質問

スパムとして扱われているユーザーやメッセージングをブロックされているユーザーを見つけるにはどうすればよいですか？

Brazeでは、ダッシュボードに専用のスパムリストは用意されていません。Brazeは、セッション数が500万を超える個々のユーザープロファイル（「ダミーユーザー」）、カスタムイベント名の種類が20,000を超えるユーザープロファイル、または購入における製品名の種類が20,000を超えるユーザープロファイルをブロックし、そのプロファイルについてSDKとREST APIの両方からのすべての受信データの取り込みを停止します。識別子がブロックされている場合、/users/track からエラー "provided external_id is blacklisted and disallowed" が返されることがあります。この文言はAPIレスポンスからそのまま引用したものです。過剰なセッションが原因でブロックされたプロファイルを見つけるには、セッション数フィルターを5,000,000より多いに設定したセグメントを作成し、そのセグメントをCSVとしてエクスポートしてから、エンゲージメント > ユーザー検索または /users/export/ids エンドポイントでプロファイルのフィールドを照合します。カスタムイベント名や製品名の種類数に対応するフィルターはないため、これらの理由でブロックされたプロファイルを特定するには、Brazeのアカウントマネージャーにお問い合わせください。詳しくは、スパムブロッキングを参照してください。