階層化カスタム属性

このページでは、階層化カスタム属性について説明します。これにより、属性のセットを別の属性のプロパティとして定義できます。つまり、カスタム属性オブジェクトを定義するときに、そのオブジェクトに一連の追加属性を定義できます。

ネストされた属性について

ネストされた属性を使用すると、よりリッチなセグメント を作成し、単一のカスタム属性 オブジェクトからのデータを使用してメッセージをカスタマイズできます。

次の例では、カスタム属性favorite_book には、ネストされた属性s title、author、およびpublishing_date が含まれます。このオブジェクトを使用すると、作成者がユーザーを対象にしたり、日付を公開してフィルターしたり、ブックのタイトルを直接メッセージに挿入したりできます。

1
2
3
4
5

"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

サポートされるデータタイプ

以下のデータタイプがサポートされています。

階層化属性について

階層化属性を使用すると、単一のカスタム属性オブジェクトのデータを活用して、より充実したセグメントを構築したり、メッセージをパーソナライズしたりできます。

次の例では、カスタム属性 favorite_book に階層化属性 title、author、publishing_date が含まれています。このオブジェクトを使用すると、著者でユーザーをターゲティングしたり、出版日でフィルタリングしたり、本のタイトルをメッセージに直接挿入したりできます。

1
2
3
4
5

"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

サポートされるデータタイプ

以下のデータタイプがサポートされています。

考慮事項

• 階層化カスタム属性は、Braze SDK または API を通じて送信されるカスタム属性を対象としています。
• オブジェクトの最大サイズは 100 KB です。更新によってオブジェクトが 100 KB を超える場合、Braze はその更新を破棄し、属性は変更されません。
• キー名と文字列値のサイズ上限は 255 文字です。
• キー名にスペースを含めることはできません。
• ユーザープロファイルに階層化カスタム属性を送信しようとする場合、ピリオド (.) とドル記号 ($) は API ペイロードでサポートされていない文字です。
• すべての Braze パートナーが階層化カスタム属性をサポートしているわけではありません。特定のパートナー連携がこの機能をサポートしているかどうかは、パートナードキュメントを参照して確認してください。
• 階層化カスタム属性は、Connected Audience API 呼び出しを行う際のフィルターとして使用できません。
• デフォルトでは、階層化カスタム属性セグメントフィルターには、オブジェクト型カスタム属性、オブジェクト配列属性、配列型カスタム属性が含まれます。属性を選択すると、プロパティスキーマセレクターには、ネストされた配列フィールドの配列パス ([] 表記を使用) が含まれます。トップレベルの配列カスタム属性をこのフィルターから非表示にするには、Braze サポートにお問い合わせください。
• ダッシュボードで カスタムユーザーとしてプレビューを使用してメッセージをプレビューする場合、モックデータは文字列または文字列の配列としてのみ入力できます。ネストされたオブジェクトはサポートされていません。階層化カスタム属性を参照するメッセージをプレビューするには、プロファイルにすでにその階層化属性を持つ既存のユーザーを選択してください。ネストされたカスタムイベントプロパティについては、テストユーザーを対象としたライブキャンペーンを開始して、レンダリングを確認する必要があります。

APIの例

• create
• update
• delete

以下は、「Most Played Song」オブジェクトを使用した /users/track の例です。曲のプロパティを取得するために、most_played_song をオブジェクトとして、一連のオブジェクトプロパティとともに指定するAPIリクエストを送信します。

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

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
    }
  ]
}

既存のオブジェクトを更新するには、リクエストに _merge_objects パラメーターを含めて users/track にPOSTを送信します。これにより、更新内容が既存のオブジェクトデータにディープマージされます。ディープマージでは、最初のレベルだけでなく、オブジェクトのすべてのレベルが別のオブジェクトにマージされます。この例では、Brazeにすでに most_played_song オブジェクトが存在しており、新しいフィールド year_released を most_played_song オブジェクトに追加しています。

1
2
3
4
5
6
7
8
9
10
11

{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "most_played_song": {
          "year_released": 1960
      }
    }
  ]
}

このリクエストが受信されると、カスタム属性オブジェクトは次のようになります。

1
2
3
4
5
6
7
8
9
10
11

{"most_played_song": {
  "song_name": "Solea",
  "artist_name" : "Miles Davis",
  "album_name": "Sketches of Spain",
  "year_released": 1960,
  "genre": "Jazz",
  "play_analytics": {
     "count": 1000,
     "top_10_listeners": true
  }
}}

警告

_merge_objects を true に設定する必要があります。設定しない場合、オブジェクトは上書きされます。_merge_objects のデフォルトは false です。

カスタム属性オブジェクトを削除するには、カスタム属性オブジェクトを null に設定して users/track にPOSTを送信します。

1
2
3
4
5
6
7
8

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

注

この方法では、オブジェクトの配列内にある階層化されたキーを削除することはできません。

SDKの例

以下のサンプルは、各SDKで同じ階層化カスタム属性オブジェクト (most_played_song) を作成、マージ更新、削除する方法を示しています。

• android sdk
• swift sdk
• web sdk
• unity sdk

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

val json = JSONObject()
    .put("song_name", "Solea")
    .put("artist_name", "Miles Davis")
    .put("album_name", "Sketches of Spain")
    .put("genre", "Jazz")
    .put(
        "play_analytics",
        JSONObject()
            .put("count", 1000)
            .put("top_10_listeners", true)
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json)
}

1
2
3
4
5
6

val json = JSONObject()
    .put("year_released", 1960)

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json, true)
}

1
2
3

braze.getCurrentUser { user ->
    user.unsetCustomUserAttribute("most_played_song")
}

1
2
3
4
5
6
7
8
9
10
11
12

let json: [String: Any?] = [
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": [
    "count": 1000,
    "top_10_listeners": true,
  ],
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json)

1
2
3
4
5

let json: [String: Any?] = [
  "year_released": 1960
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json, merge: true)

1

braze.user.unsetCustomAttribute(key: "most_played_song")

1
2
3
4
5
6
7
8
9
10
11
12

import * as braze from "@braze/web-sdk";
const json = {
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": {
    "count": 1000,
    "top_10_listeners": true
  }
};
braze.getUser().setCustomUserAttribute("most_played_song", json);

1
2
3
4
5
6

import * as braze from "@braze/web-sdk";
const json = {
  "year_released": 1960
};
braze.getUser().setCustomUserAttribute("most_played_song", json, true);

1
2

import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);

1
2
3
4
5
6
7
8
9
10
11
12

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("song_name", "Solea");
attributes.Add("artist_name", "Miles Davis");
attributes.Add("album_name", "Sketches of Spain");
attributes.Add("genre", "Jazz");

Dictionary<string, object> playAnalytics = new Dictionary<string, object>();
playAnalytics.Add("count", 1000);
playAnalytics.Add("top_10_listeners", true);
attributes.Add("play_analytics", playAnalytics);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes);

1
2
3
4

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("year_released", 1960);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes, true);

1

AppboyBinding.UnsetCustomUserAttribute("most_played_song");

オブジェクトプロパティとして日付を取得する

日付をオブジェクトプロパティとして取得するには、$time キーを使用する必要があります。次の例では、「Important Dates」オブジェクトを使用して、オブジェクトプロパティのセット birthday と wedding_anniversary を取得しています。これらの日付の値は $time キーを持つオブジェクトであり、null 値にすることはできません。

注

_merge_objects が true の場合、$time を含まない null 値を指定すると、オブジェクトから既存のネストされた日付フィールドが削除されます。フィールドがまだ存在しない場合、Braze は null 値を無視し、フィールドを作成しません。どちらの場合も、Braze はエラーを返しません。

最初に日付をオブジェクトプロパティとして取得していない場合は、すべてのユーザーについて $time キーを使用してこのデータを再送信することをお勧めします。そうしないと、$time 属性を使用する際にセグメントが不完全になる可能性があります。ただし、階層化カスタム属性内の $time の値が正しくフォーマットされていない場合、その階層化カスタム属性全体が更新されません。

1
2
3
4
5
6
7
8
9
10
11

{
  "attributes": [
    {
      "external_id": "time_with_nca_test",
      "important_dates": {
        "birthday": {"$time" : "1980-01-01"},
        "wedding_anniversary": {"$time" : "2020-05-28"}
      }
    }
  ]
}

注

階層化カスタム属性では、年が 0 未満または 3000 より大きい場合、Braze はこれらの値をユーザーに保存しません。

Liquid テンプレート

次の Liquid テンプレートの例では、前述の API リクエストで保存したカスタム属性オブジェクトのプロパティを参照し、メッセージングで使用する方法を示します。

オブジェクトのプロパティにアクセスするには、custom_attribute パーソナライゼーションタグとドット記法を使用します。オブジェクト名 (オブジェクトの配列を参照する場合は配列内の位置も) を指定し、続けてドット (ピリオド)、プロパティ名を指定します。

{{custom_attribute.${most_played_song}[0].artist_name}} — “Miles Davis”
{{custom_attribute.${most_played_song}[0].song_name}} — “Solea”
{{custom_attribute.${most_played_song}[0].play_analytics.count}} — “1000”

メッセージで階層化カスタム属性の Liquid を使用するには、次の手順に従います。

1. キャンペーンまたはキャンバスに移動し、パーソナライゼーションを追加するメッセージステップを開きます。
2. メッセージ作成画面で、値を表示したい位置に Liquid スニペットを挿入します。
3. プロファイルに階層化カスタム属性がすでに設定されている既存ユーザーを使ってプレビューとテストを行い、値が想定どおりにレンダリングされることを確認します。

パーソナライゼーション

パーソナライゼーションを追加を使用して、メッセージに階層化カスタム属性を挿入できます。

パーソナライゼーションを追加を開くには、次の手順に従います。

1. キャンペーンまたはキャンバスに移動し、パーソナライゼーションを追加するメッセージステップを開きます。
2. メッセージ作成画面でパーソナライゼーションを選択してパーソナライゼーションを追加サイドバーを開き、パーソナライゼーションのオプションを選択します。

階層化カスタム属性のパーソナライゼーションを設定するには、次の手順に従います。

1. パーソナライゼーションタイプで階層化カスタム属性を選択します。
2. トップレベル属性で、挿入する階層化カスタム属性のパスを選択します。 たとえば、preferences.neighborhood_office を選択します。
3. オプション:デフォルト値に、その属性の値を持たないユーザー向けのフォールバック値を入力します。
4. 生成された Liquid スニペットを確認し、想定どおりのパスになっていることを確認します。
5. 挿入を選択します。

この例では、Braze は preferences.neighborhood_office の階層化された値をメッセージに挿入します。デフォルト値は、属性の値を持たないユーザーに対してメッセージに含まれるフォールバックです。

ヒント

階層化カスタム属性を挿入するオプションが表示されない場合は、スキーマが生成されているかどうかを確認してください。

スキーマの生成と再生成

セグメンテーションやパーソナライゼーションで階層化カスタム属性を使用するには、その属性のスキーマを生成する必要があります。スキーマが生成された後、必要に応じて再生成できます。スキーマの詳細については、ネストされたオブジェクトエクスプローラーを使用してスキーマを生成するを参照してください。

スキーマを生成する

階層化カスタム属性を作成してBrazeにデータを送信した後、スキーマを生成できます。

1. データ設定 > カスタム属性に移動します。
2. 階層化カスタム属性を検索します。
3. 属性の属性名列で、 スキーマを生成を選択します。

スキーマが生成されると、 アイコンが プラスアイコンに変わり、それを選択してスキーマを表示・管理できます。

スキーマを再生成する

階層化カスタム属性のスキーマを再生成するには：

1. データ設定 > カスタム属性に移動します。
2. 階層化カスタム属性を検索します。
3. 属性の属性名列で、 スキーマを管理を選択してスキーマを管理します。
4. モーダルが表示されます。スキーマを再生成を選択します。

スキーマジョブがすでに進行中の場合（ステータスが生成中の間はオプションが利用できません）、別の再生成を開始することはできません。1つの会社につき、一度に実行できるスキーマ生成ジョブは1つだけです。スキーマの再生成では新しいオブジェクトのみが検出され、スキーマに現在存在するオブジェクトは削除されません。

重要

既存のオブジェクトを持つオブジェクト配列のスキーマをリセットするには、新しいカスタム属性を作成する必要があります。スキーマの再生成では既存のオブジェクトは削除されません。

スキーマを再生成した後にデータが期待どおりに表示されない場合、その属性が十分な頻度で取り込まれていない可能性があります。ユーザーデータは、指定された階層化属性についてBrazeに送信された過去のデータからサンプリングされます。属性が十分に取り込まれていない場合、スキーマに反映されません。

階層化カスタム属性の変更をトリガーする

階層化カスタム属性オブジェクトが変更されたときにトリガーできます。このオプションは、オブジェクト配列の変更には使用できません。パスエクスプローラーを表示するオプションが見つからない場合は、スキーマを生成済みであることを確認してください。

たとえば、アクションベースのキャンペーンでは、カスタム属性値を変更の新しいトリガーアクションを追加して、近隣オフィスの設定を変更したユーザーをターゲットにできます。

アクションベースのキャンペーンでこのトリガーを設定するには、次の手順に従います。

1. キャンペーンを作成または編集し、配信タイプをアクションベースの配信に設定します。
2. トリガー設定で、カスタム属性値を変更を選択します。
3. 監視する階層化カスタム属性のパスを選択します。 たとえば、preferences.neighborhood_office を選択します。
4. 任意の新しい値など、目的のトリガー条件を選択します。
5. キャンペーンのメッセージとオーディエンスの設定を完了し、キャンペーンを開始します。

トラブルシューティング

階層化カスタム属性の値が一貫して適用されない

階層化カスタム属性の値がユーザープロファイルに一貫して追加されていない場合、多くの場合はデータ型の不一致が原因です。

この問題を診断して解決するには:

1. ユーザー例を比較する: 階層化カスタム属性が設定されているはずのユーザーについて、成功した例と失敗した例を1つずつ用意します。
2. データ構造を確認する: 両方のプロファイルのカスタム属性の値を表示して比較します。
   • プロパティはオブジェクトの下に保存されていますか？
   • プロパティはプロパティの配列として保存されていますか？
3. セグメンテーションフィルターを確認する: 保存されているデータ構造と、セグメンテーションフィルターでの階層化カスタム属性の参照方法を比較します。
4. データ型を確認する: カスタム属性のデータ型を特定するには:
   • データ設定 > カスタム属性に移動します。
   • 確認したい階層化属性を含む最上位のカスタム属性を検索します。
   • 行に スキーマを生成と表示されている場合は、それを選択して先にスキーマを生成します。
   • スキーマが生成されたら、その属性の属性名列にあるプラスアイコンを選択します。
   • スキーマを編集モーダルで、階層化属性と、データ型列に表示される対応する値を確認します。

ユーザープロファイル間でデータ型が意図した形式と一致しないことがわかった場合は、影響を受けるユーザープロファイルから誤った形式の値を削除し、適切な API リクエストまたは SDK メソッドを使用して正しい形式で属性を再送信してください。

オブジェクトの配列を使用したセグメンテーションの動作

オブジェクトの配列でセグメント化する際に、複数の 階層化カスタム属性 フィルターを AND ロジックで使用すると、各フィルターは配列内のすべての項目に対して独立して評価されます。配列内のいずれかの項目が個々のフィルターをそれぞれ満たしていれば、ユーザーはセグメントの対象になります。各フィルターが同じ項目に一致する必要はありません。

たとえば、ユーザーが次の配列を持っているとします。

1
2
3
4
5
6

{
  "orders": [
    {"product": "Shoes", "price": 80},
    {"product": "Hat", "price": 25}
  ]
}

次の AND フィルターを持つセグメントがあるとします。

• orders[].price が 50 より大きい
• orders[].price が 30 より小さい

このユーザーはセグメントの対象になります。最初のフィルターは「Shoes」項目 (80 > 50) に一致し、2 番目のフィルターは「Hat」項目 (25 < 30) に一致するためです。両方の条件を満たす単一の項目がなくても、ユーザーはセグメントに入ります。

配列内の同じ項目ですべての条件を一致させる必要がある場合は、同じパスで複数条件のセグメンテーションを使用するか、項目をまたいだ一致が発生しないようにデータを再構成してください。

データポイント

送信されるキーはすべてデータポイントを消費します。たとえば、ユーザープロファイルで初期化された次のオブジェクトは、7 データポイントとしてカウントされます。

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

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "year_released": 1960,
        "genre": "Jazz",
        "play_analytics": {
          "count": 1000,
          "top_10_listeners": true
        }
      }
    }
  ]
}

注

カスタム属性オブジェクトを null に更新した場合も、データポイントを消費します。