オブジェクト配列
このページでは、オブジェクトの配列を使って関連する属性をグループ化する方法を説明します。例えば、1人のユーザーに属するペットオブジェクト、曲オブジェクト、アカウントオブジェクトをすべて含むグループがあるとします。これらのオブジェクト配列を使用して、Liquidでメッセージングをパーソナライズしたり、オブジェクト内のいずれかの要素が条件に一致する場合にオーディエンスセグメントを作成したりできます。
サポートされるデータタイプ
以下のデータタイプがサポートされています。
| データタイプ | 説明 |
|---|---|
| 数値 | 1や5.5などの数値です。 |
| 文字列 | "Hello"や"The Hobbit"などのテキスト値です。 |
| ブール値 | trueまたはfalseのいずれかに評価される値です。 |
| 配列 | ["red", "blue", "green"]などの値のリストです。 |
| 時刻 |
日付と時刻の比較に使用されるタイムスタンプ値です。ネストされた時刻カスタム属性でフィルターする際に、以下を選択できます。
|
| オブジェクト | {"author": "Tolkien"}のようなキーと値のペアを持つ構造化された値です。 |
| オブジェクトの配列 |
[{"title": "The Hobbit"}, {"title": "Dune"}]のようなオブジェクトのリストです。
詳細については、オブジェクトの配列 を参照してください。
|
考慮事項
- オブジェクトの配列は、API を通じて送信されるカスタム属性を対象としています。CSVアップロードはサポートされていません。CSVファイル内のコンマは列の区切り文字として解釈され、値に含まれるコンマが解析エラーの原因となるためです。
- オブジェクトの配列には項目数の制限はありませんが、最大サイズは 100 KB です。更新 (
$addや$updateなど) によって配列がこの制限を超える場合、Braze はその更新を破棄し、属性は変更されません。この場合でも、API リクエストは成功のレスポンスを返します。新しい項目を追加できるように配列を制限内に保つには、まず$removeを使用して配列から項目を削除してください。 - すべての Braze パートナーがオブジェクトの配列をサポートしているわけではありません。統合がこの機能をサポートしているかどうかは、パートナーのドキュメントで確認してください。
配列内の項目を更新または削除するには、キーと値で項目を識別する必要があるため、配列内の各項目に一意の識別子を含めることを検討してください。この一意性は配列内でのみ適用され、配列から特定のオブジェクトを更新または削除する場合に役立ちます。なお、Braze によって一意性が強制されることはありません。
リクエスト内の階層化カスタム属性に無効な値 (無効な時刻形式や null 値など) が含まれている場合、Braze はそのリクエスト内のすべての階層化カスタム属性の更新を処理せずに破棄します。これは、その属性内のすべての階層構造に適用されます。送信する前に、階層化カスタム属性内のすべての値が有効であることを確認してください。詳細については、ユーザーの作成と更新を参照してください。
API の例
ネストされたカスタム属性をオブジェクトの配列として作成または更新する /users/track リクエストを送信する際は、以下の例を参考にしてください。ペイロードでは $add、$remove、$update の各オペレーターを使用するため、リクエストのたびに配列全体を再構築しなくても、特定のオブジェクトだけを変更できます。
以下は、pets 配列を使用した /users/track の例です。ペットのプロパティを記録するには、pets をオブジェクトの配列として指定した API リクエストを送信します。各オブジェクトには一意の id が割り当てられており、後で更新する際にこの id を参照できます。
属性を初めて作成する場合や、配列全体を新しいベースラインのオブジェクトセットに置き換える場合は、この形式を使用します。
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}
]
}
]
}
$add オペレーターを使用して、配列に別の項目を追加します。次の例では、ユーザーの pets 配列にペットのオブジェクトを 3 つ追加しています。
既存のオブジェクトを変更せずに、1 つ以上の新しいオブジェクトを追加する必要がある場合は、$add を使用します。
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$add": [
{
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Biscuit"
},
{
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Pepper"
},
{
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Noodle"
}
]
}
}
]
}
_merge_objects パラメーターと $update オペレーターを使用して、配列内の特定のオブジェクトの値を更新します。他の階層化カスタム属性オブジェクトの更新と同様に、この操作ではディープマージが実行されます。
$update では、配列内のオブジェクトからネストされたプロパティを削除することはできません。削除するには、配列から項目全体を削除してから、その特定のキーを含まないオブジェクトを追加する必要があります（$remove と $add を組み合わせて使用します）。
オブジェクトがすでに存在し、$identifier_key と $identifier_value で一致させて 1 つ以上のフィールドを変更する場合は、$update を使用します。
次の例では、id が 4 のオブジェクトの breed プロパティを goldfish に更新しています。このリクエスト例では、id が 5 のオブジェクトの name も Annette に更新しています。_merge_objects パラメーターが true に設定されているため、これら 2 つのオブジェクトのその他のフィールドはすべてそのまま維持されます。
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"pets": {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
}
}
]
}
_merge_objects を true に設定する必要があります。設定しないと、オブジェクトが上書きされます。_merge_objects はデフォルトで false です。
$remove オペレーターを、一致させるキー ($identifier_key) と値 ($identifier_value) と組み合わせて使用し、配列からオブジェクトを削除します。
id = 2 や type = dog など、既知の識別子のペアに一致するすべてのオブジェクトを削除する場合は、$remove を使用します。
次の例では、pets 配列内で、id の値が 1 のオブジェクト、id の値が 2 のオブジェクト、および type の値が dog のオブジェクトをすべて削除しています。type の値が dog のオブジェクトが複数ある場合は、一致するすべてのオブジェクトが削除されます。
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$remove": [
// Remove by ID
{
"$identifier_key": "id",
"$identifier_value": 1
},
{
"$identifier_key": "id",
"$identifier_value": 2
},
// Remove any dog
{
"$identifier_key": "type",
"$identifier_value": "dog"
}
]
}
}
]
}
処理順序
1 つの /users/track リクエストに、同じ配列属性に対する $add、$remove、$update の操作が含まれている場合、Braze は次の順序で処理します。
$add$remove$update
この順序は、1 つのリクエスト内の単一の属性更新オブジェクトに適用され、すべての操作が評価された後の配列の最終状態を決定します。
$add は $remove より先に実行されるため、1 つのリクエスト内で $remove の後に $add を指定してアップサートの仕組みとして使用することはできません。$add が先に処理され、その後 $remove によって項目が削除されます。アップサートを行うには、$add の前に別のリクエストで $remove を送信してください。
タイムスタンプ
オブジェクトの配列にタイムスタンプなどのフィールドを含める場合は、プレーンな文字列や Unix エポックの整数ではなく、$time 形式を使用してください。
{
"attributes": [
{
"external_id": "user123",
"purchases": [
{
"item_name": "T-shirt",
"price": 19.99,
"purchase_time": {
"$time": "2020-05-28"
}
}
]
}
]
}
SDKの例
val json = JSONArray()
.put(JSONObject()
.put("id", 1)
.put("type", "dog")
.put("breed", "beagle")
.put("name", "Gus"))
.put(JSONObject()
.put("id", 2)
.put("type", "cat")
.put("breed", "calico")
.put("name", "Pixel")
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json)
}
val json = JSONObject()
.put("\$add", JSONArray()
.put(JSONObject()
.put("id", 3)
.put("type", "dog")
.put("breed", "corgi")
.put("name", "Doug"))
.put(JSONObject()
.put("id", 4)
.put("type", "fish")
.put("breed", "salmon")
.put("name", "Pepper"))
.put(JSONObject()
.put("id", 5)
.put("type", "bird")
.put("breed", "parakeet")
.put("name", "Noodle")
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
val json = JSONObject()
.put("\$update", JSONArray()
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 4)
.put("\$new_object", JSONObject()
.put("breed", "goldfish")
)
)
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 5)
.put("\$new_object", JSONObject()
.put("name", "Annette")
)
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
val json = JSONObject()
.put("\$remove", JSONArray()
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 1)
)
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 2)
)
.put(JSONObject()
.put("\$identifier_key", "type")
.put("\$identifier_value", "dog")
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
let json: [[String: Any?]] = [
[
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
],
[
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
]
]
braze.user.setCustomAttribute(key: "pets", array: json)
let json: [String: Any?] = [
"$add": [
[
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Biscuit"
],
[
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Pepper"
],
[
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Noodle"
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
let json: [String: Any?] = [
"$update": [
[
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": [
"breed": "goldfish"
]
],
[
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": [
"name": "Annette"
]
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
let json: [String: Any?] = [
"$remove": [
[
"$identifier_key": "id",
"$identifier_value": 1,
],
[
"$identifier_key": "id",
"$identifier_value": 2,
],
[
"$identifier_key": "type",
"$identifier_value": "dog",
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
AppboyKitでは、階層化カスタム属性はサポートされていません。
import * as braze from "@braze/web-sdk";
const json = [{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
}, {
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}];
braze.getUser().setCustomUserAttribute("pets", json);
import * as braze from "@braze/web-sdk";
const json = {
"$add": [{
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Doug",
}, {
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Pepper",
}, {
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Noodle",
}]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
import * as braze from "@braze/web-sdk";
const json = {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
import * as braze from "@braze/web-sdk";
const json = {
"$remove": [
{
"$identifier_key": "id",
"$identifier_value": 1,
},
{
"$identifier_key": "id",
"$identifier_value": 2,
},
{
"$identifier_key": "type",
"$identifier_value": "dog",
}
]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
Liquidテンプレート
この pets 配列を使用して、メッセージをパーソナライズできます。以下のLiquidテンプレートの例では、前述のAPIリクエストで保存したカスタム属性オブジェクトのプロパティを参照し、メッセージングで使用する方法を示しています。
{% assign pets = {{custom_attribute.${pets}}} %}
{% for pet in pets %}
I have a {{pet.type}} named {{pet.name}}! They are a {{pet.breed}}.
{% endfor %}
このシナリオでは、Liquidを使用して pets 配列をループ処理し、ペットごとに文を出力できます。pets カスタム属性に変数を割り当て、ドット表記を使用してオブジェクトのプロパティにアクセスします。オブジェクト名、ピリオド .、プロパティ名の順に指定します。
セグメンテーション
オブジェクトの配列に基づいてユーザーをセグメント化する場合、配列内のいずれかのオブジェクトが条件に一致すると、ユーザーはそのセグメントの対象となります。
新しいセグメントを作成し、フィルターとして階層化カスタム属性を選択します。次に、オブジェクトの配列の名前を検索して選択します。
ドット表記を使用して、オブジェクトの配列内で使用するフィールドを指定します。テキストフィールドの先頭に空の角括弧 [] を入力して、オブジェクトの配列の中を参照していることを Braze に伝えます。その後にピリオド . を追加し、続けて使用するフィールドの名前を入力します。
たとえば、top_3_movies というオブジェクトの配列を type フィールドに基づいてフィルタリングする場合は、[].type と入力し、Fantasy Movie など、フィルタリングする映画を選択します。
ネストのレベル
配列のネストは 1 レベル (別の配列内の配列) までのセグメントを作成できます。たとえば、次の属性がある場合、pets[].name に Mochi が含まれるセグメントは作成できますが、pets[].nicknames[] に Gugu が含まれるセグメントは作成できません。
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi",
"nicknames": [
"MoMo",
"Mochi"
]
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel",
"nicknames": [
"PiPi",
"Pixel"
]
}
]
}
]
}
データポイント
データポイントは、プロパティを作成、更新、削除のどれで操作するかによって記録のされ方が異なります。
新しい配列を作成すると、オブジェクト内の属性ごとに1つのデータポイントが記録されます。この例では、各ペットオブジェクトに4つの属性があり、オブジェクトが2つあるため、8データポイントを消費します。
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}
]
}
]
}
既存の配列を更新すると、追加されたプロパティごとに1つのデータポイントが記録されます。この例では、2つのオブジェクトそれぞれで1つのプロパティのみを更新するため、2データポイントを消費します。
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"pets": {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
}
}
]
}
配列からオブジェクトを削除すると、送信した削除条件ごとに1つのデータポイントが記録されます。この例では、このステートメントで複数の犬を削除する可能性がある場合でも、3データポイントを消費します。
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$remove": [
// Remove by ID
{
"$identifier_key": "id",
"$identifier_value": 1
},
{
"$identifier_key": "id",
"$identifier_value": 2
},
// Remove any dog
{
"$identifier_key": "type",
"$identifier_value": "dog"
}
]
}
}
]
}