階層化カスタム属性

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

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

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

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

サポートされるデータ型

以下のデータタイプがサポートされている：

考慮事項

• 階層化カスタム属性は、Braze SDK または API を通じて送信されるカスタム属性を対象としています。
• オブジェクトの最大サイズは 100 KB です。更新によりオブジェクトが 100 KB を超える場合、Braze はその更新を破棄し、属性は変更されません。
• キー名と文字列値のサイズ上限は 255 文字です。
• キー名にスペースを含めることはできません。
• ユーザープロファイルに階層化カスタム属性を送信する場合、API ペイロードではピリオド（.）とドル記号（$）はサポートされていない文字です。
• すべての Braze パートナーが階層化カスタム属性をサポートしているわけではありません。特定のパートナー連携がこの機能をサポートしているかどうかは、パートナードキュメントを参照してください。
• Connected Audience API コールでフィルターを作成する際に、階層化カスタム属性をフィルターとして使用することはできません。

API の例

• create
• update
• delete

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
        }
      }
    }
  ]
}

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
  }
}}

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 値にすることはできません。

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"}
      }
    }
  ]
}

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”

パーソナライゼーション

パーソナライゼーションを追加モーダルを使用して、階層化カスタム属性をメッセージングに挿入することもできます。パーソナライゼーションタイプとして階層化カスタム属性を選択します。次に、トップレベルの属性と属性キーを選択します。

例えば、以下のパーソナライゼーションモーダルでは、ユーザーの設定に基づいて、地域のオフィスの階層化カスタム属性を挿入しています。

スキーマの再生成

スキーマが生成された後、24 時間に 1 回再生成できます。このセクションでは、スキーマを再生成する方法について説明します。スキーマの詳細については、ネストされたオブジェクトエクスプローラーを使用してスキーマを生成するを参照してください。

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

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

スキーマが最後に再生成されてから 24 時間未満の場合、スキーマの再生成オプションは無効になります。スキーマの再生成では新しいオブジェクトのみが検出され、スキーマに現在存在するオブジェクトは削除されません。

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

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

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

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

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

複数の 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）に一致するためです。単一のアイテムが両方の条件を満たしていなくても、ユーザーはセグメントに入ります。

配列内の同じアイテムにすべての条件を一致させる必要がある場合は、同じパスでマルチクライテリアセグメンテーションを使用するか、クロスアイテムマッチングを避けるようにデータを再構成してください。

データポイント

送信されるキーごとに 1 データポイントを消費します。例えば、ユーザープロファイルで初期化されたこのオブジェクトは 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
        }
      }
    }
  ]
}