階層化カスタム属性

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

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

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

次の例では、カスタム属性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の例

• 作成
• 更新
• 削除

以下は、「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オブジェクトがあり、most_played_songオブジェクトに新しいフィールドyear_releasedを追加します。

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の例

• android sdk
• swift sdk
• web 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);

オブジェクトプロパティとしての日付のキャプチャ

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

注

最初に日付をオブジェクトプロパティとしてキャプチャしていなかった場合は、すべてのユーザーに対して $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メソッドを使用して正しい形式で属性を再送信してください。

オブジェクト配列でのセグメンテーション動作

複数のNested Custom Attributeフィルターを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 に更新した場合も、データポイントを消費します。