階層化カスタム属性

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

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

ネストされた属性を使用すると、よりリッチな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 です。
• キー名と文字列値のサイズ上限は 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”

セグメンテーション

階層化カスタム属性に基づいてセグメントを構築し、ユーザーのターゲットをより細かく設定できます。そのためには、カスタム属性オブジェクトに基づいてセグメントにフィルターを適用し、セグメンテーションの基準にするプロパティ名と関連する値へのパスを指定します。そのパスがどのようなものかわからない場合は、スキーマを生成し、Braze の階層化オブジェクトエクスプローラーを使用してそのパスを自動入力できます。

プロパティにパスを追加した後、[Validate] を選択して、パスフィールドの値が有効であることを確認します。

階層化カスタム属性を使用してセグメント化するには、[Nested Custom Attributes] フィルターを選択してドロップダウンを表示し、そこから特定の階層化カスタム属性を選択します。

階層化カスタム属性でのセグメンテーションを使用する場合、データタイプごとにグループ化された新しい比較演算子にアクセスできます。たとえば、play_analytics.count は数値であるため、Number カテゴリの下で比較演算子を選択できます。

時間データタイプへのフィルター適用

時間の階層化カスタム属性にフィルターを適用する場合、日付値を比較するときに [Day of Year] または [Time] のカテゴリにある演算子を使用できます。

[Day of Year] カテゴリの演算子を選択すると、階層化カスタム属性値のタイムスタンプ全体ではなく、比較対象として月と日のみがチェックされます。[Time] カテゴリの演算子を選択すると、年を含むタイムスタンプ全体が比較されます。

多条件セグメンテーション

1 つのオブジェクト内で複数の条件に一致するセグメントを作成するには、多条件セグメンテーションを使用します。これにより、指定されたすべての条件に一致するオブジェクト配列がユーザーに少なくとも 1 つある場合、ユーザーはセグメントに入れられます。例えば、キーが空白でなく、かつ数値が 0 より大きい場合にのみ、ユーザーはこのセグメントに該当します。

[Copy Liquid for segment] 機能を使用してこのセグメントの Liquid コードを生成し、メッセージで使用することもできます。例えば、口座オブジェクトの配列と、アクティブで課税対象の口座を持つ顧客を対象とするセグメントがあるとします。アクティブで課税対象の口座のいずれかに関連する口座目標に顧客が貢献するよう促すには、働きかけるメッセージを作成する必要があります。

[Copy Liquid for segment] を選択すると、Braze によりアクティブで課税対象の口座のみを含むオブジェクト配列を返す Liquid コードが自動的に生成されます。

1
2
3
4
5
6
7
{% assign segmented_nested_objects = '' | split: '' %}
{% assign obj_array = {{custom_attribute.${accounts}}} %}
{% for obj in obj_array %}
  {% if obj["account_type"] == 'taxable' and obj["active"] == true %}
    {% assign segmented_nested_objects = obj_array | slice: forloop.index0 | concat: segmented_nested_objects | reverse %}
  {% endif %}
{% endfor %}

ここから、segmented_nested_objects を使用してメッセージをパーソナライズできます。この例では、最初のアクティブな課税対象口座から目標を取得してパーソナライズします。

1
Get to your {{segmented_nested_objects[0].goal}} goal faster, make a deposit using our new fast deposit feature!

これにより、顧客に次のメッセージが返されます。「Get to your retirement goal faster, make a deposit using our new fast deposit feature!」

階層化オブジェクトエクスプローラーを使用したスキーマの生成

階層化オブジェクトのパスを記憶しなくても、オブジェクトのスキーマを生成してセグメントフィルターを作成できます。そのためには、次のステップを実行します。

ステップ 1: スキーマの生成

この例では、さきほど Braze に送信した accounts オブジェクト配列があるとします。

1
2
3
4
5
6
7
8
{"accounts": [
  {"type": "taxable",
  "balance": 22500,
  "active": true},
  {"type": "non-taxable",
  "balance": 0,
  "active": true}
]}

Braze ダッシュボードで、[データ設定] > [カスタム属性] に移動します。

オブジェクトまたはオブジェクト配列を検索します。[Attribute Name] 列で、[Generate Schema] を選択します。

スキーマが生成されると、[Generate Schema] ボタンの代わりに新しい プラスボタンが表示されます。これをクリックすると、この階層化カスタム属性について Braze が把握している内容を確認できます。

スキーマの生成中に、Braze は以前に送信されたデータを確認し、この属性に関するデータの最適な表現を作成します。また、Braze は階層化された値のデータタイプを分析して追加します。これは、指定された階層化属性について、Braze に送信された以前のデータをサンプリングすることによって行われます。

この accounts オブジェクト配列では、そのなかに次の内容を含むオブジェクトがあることがわかります。

• ブール型で active のキーを持つ（口座がアクティブかどうかは無関係）
• 数値型で balance（口座残高）のキーを持つ
• 文字列型で type（非課税口座または課税対象口座）のキーを持つ

データの分析と表現の作成が完了したので、セグメントを作成します。

ステップ 2: セグメントの作成

入金を促すメッセージの送信先として、残高が 100 未満の顧客をターゲットにします。

セグメントを作成してフィルター Nested Custom Attribute を追加し、オブジェクトまたはオブジェクト配列を検索して選択します。ここでは、accounts オブジェクト配列を追加しました。

パスフィールドの プラスボタンを選択します。これにより、オブジェクトまたはオブジェクト配列の表現が表示されます。リストされている項目のいずれかを選択すると、Braze によりそれらがパスフィールドに挿入されます。この例では、残高を取得する必要があります。残高を選択すると、パス（この例では [].balance）がパスフィールドに自動的に入力されます。

[Validate] を選択して、パスフィールドの内容が有効であることを確認し、必要に応じて残りのフィルターを構築できます。ここでは、残高が 100 未満でなければならないと指定しました。

以上です。データの構造を知らなくても、階層化カスタム属性を使用してセグメントを作成できました。Braze の階層化オブジェクトエクスプローラーによってデータが視覚的に表現されるため、セグメントの作成に必要なものを調べて正確に選択できました。

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

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

例えば、次のアクションベースのキャンペーンでは、[Change Custom Attribute Value] の新しいトリガーアクションを追加して、基本設定で最寄りのオフィスを変更したユーザーをターゲットにすることができます。

パーソナライゼーション

[Add Personalization] モーダルを使用して、階層化カスタム属性をメッセージングに挿入することもできます。パーソナライゼーションタイプとして [Nested Custom Attributes] を選択します。次に、最上位の属性と属性キーを選択します。

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

スキーマの再生成

スキーマは、その生成後、24 時間に 1 回再生成できます。このセクションでは、スキーマを再生成する方法について説明します。スキーマの詳細については、この記事のスキーマの生成に関するセクションを参照してください。

階層化カスタム属性のスキーマを再生成するには、次の手順に従います。

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

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

スキーマの再生成後にデータが期待どおりに表示されない場合は、属性が十分な頻度で取り込まれていない可能性があります。ユーザーデータは、指定した階層化属性について Braze に送信された以前のデータに基づいてサンプリングされます。十分な量の属性が取り込まれていないと、スキーマ用として選択されません。

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

オブジェクト配列に対して AND ロジックで複数の Nested Custom Attribute フィルターを使用してセグメント化する場合、各フィルターは配列内のすべてのアイテムに対して独立して評価されます。配列内の_いずれかの_アイテムが個々のフィルターをそれぞれ満たしていれば、ユーザーはセグメントに該当します。フィルターが_同じ_アイテムに一致する必要はありません。

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

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