Array von Objekten

Auf dieser Seite erfahren Sie, wie Sie ein Array von Objekten verwenden können, um verwandte Attribute zu gruppieren. Sie können z. B. eine Gruppe von Haustierobjekten, Liedobjekten und Kontoobjekten haben, die alle zu einer Nutzer:in gehören. Diese Arrays von Objekten können verwendet werden, um Ihr Messaging mit Liquid zu personalisieren oder Zielgruppen-Segmente zu erstellen, wenn irgendein Element innerhalb eines Objekts den Kriterien entspricht.

Unterstützte Datentypen

Die folgenden Datentypen werden unterstützt:

Überlegungen

• Arrays von Objekten sind für angepasste Attribute vorgesehen, die über die API gesendet werden. CSV-Uploads werden nicht unterstützt. Das liegt daran, dass Kommas in der CSV-Datei als Spaltentrennzeichen interpretiert werden und Kommas in Werten zu Parsing-Fehlern führen.
• Für Arrays von Objekten gibt es keine Begrenzung der Anzahl der Artikel, aber eine maximale Größe von 100 KB. Wenn ein Update (z. B. $add oder $update) dazu führt, dass das Array diese Grenze überschreitet, verwirft Braze das Update, und das Attribut bleibt unverändert. Die API-Anfrage gibt trotzdem eine Erfolgsantwort zurück. Um das Array unter der Grenze zu halten, damit neue Artikel hinzugefügt werden können, verwenden Sie zunächst $remove, um Artikel aus dem Array zu löschen.
• Nicht alle Braze-Partner unterstützen Arrays von Objekten. In der Partner-Dokumentation können Sie überprüfen, ob die Integration dieses Feature unterstützt.

Um Artikel in einem Array zu aktualisieren oder zu entfernen, muss der Artikel anhand von Schlüssel und Wert identifiziert werden. Erwägen Sie daher, für jeden Artikel im Array einen eindeutigen Bezeichner aufzunehmen. Die Eindeutigkeit gilt nur innerhalb des Arrays und ist nützlich, wenn Sie bestimmte Objekte in Ihrem Array aktualisieren und entfernen möchten. Braze erzwingt dies nicht.

Wichtig

Wenn ein verschachteltes angepasstes Attribut in Ihrer Anfrage ungültige Werte enthält (z. B. ungültige Zeitformate oder null-Werte), verwirft Braze alle Updates verschachtelter angepasster Attribute in der Anfrage und verarbeitet sie nicht. Dies gilt für alle verschachtelten Strukturen innerhalb dieses Attributs. Überprüfen Sie vor dem Senden, dass alle Werte in verschachtelten angepassten Attributen gültig sind. Weitere Informationen finden Sie unter Nutzer:innen erstellen und aktualisieren.

Tipp

Weitere Informationen zur Verwendung von Arrays von Objekten für Nutzerattributobjekte finden Sie unter Nutzerattributobjekt.

API-Beispiel

Verwenden Sie diese Beispiele, wenn Sie /users/track-Anfragen senden, die verschachtelte angepasste Attribute als Arrays von Objekten erstellen oder aktualisieren. Die Payload verwendet die Operatoren $add, $remove und $update, damit Sie bestimmte Objekte ändern können, ohne bei jeder Anfrage das gesamte Array neu aufbauen zu müssen.

• create
• add
• update
• remove

Das folgende Beispiel zeigt eine /users/track-Anfrage mit einem pets-Array. Um die Eigenschaften der Haustiere zu erfassen, senden Sie eine API-Anfrage, die pets als Array von Objekten auflistet. Beachten Sie, dass jedem Objekt eine eindeutige id zugewiesen wurde, auf die Sie später bei Updates verweisen können.

Verwenden Sie dieses Format, wenn Sie das Attribut zum ersten Mal erstellen oder das gesamte Array durch einen neuen Basissatz von Objekten ersetzen möchten.

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

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Mochi"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel"
        }
      ]
    }
  ]
}

Fügen Sie dem Array mit dem Operator $add einen weiteren Artikel hinzu. Das folgende Beispiel zeigt, wie dem pets-Array der Nutzer:in drei weitere Haustier-Objekte hinzugefügt werden.

Verwenden Sie $add, wenn Sie ein oder mehrere neue Objekte anhängen und die vorhandenen Objekte unverändert lassen möchten.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

Aktualisieren Sie Werte für bestimmte Objekte innerhalb eines Arrays mit dem Parameter _merge_objects und dem Operator $update. Wie bei Updates anderer Objekte mit verschachtelten angepassten Attributen wird dabei ein Deep Merge durchgeführt.

Beachten Sie, dass Sie mit $update keine verschachtelte Eigenschaft aus einem Objekt innerhalb eines Arrays entfernen können. Dazu müssen Sie den gesamten Artikel aus dem Array entfernen und das Objekt anschließend ohne diesen Schlüssel wieder hinzufügen (mit einer Kombination aus $remove und $add).

Verwenden Sie $update, wenn das Objekt bereits existiert und Sie ein oder mehrere Felder ändern möchten, indem Sie über $identifier_key und $identifier_value abgleichen.

Das folgende Beispiel zeigt, wie die Eigenschaft breed für das Objekt mit der id 4 auf goldfish aktualisiert wird. Dieses Anfragebeispiel aktualisiert außerdem das Objekt mit der id 5 mit dem neuen name Annette. Da der Parameter _merge_objects auf true gesetzt ist, bleiben alle anderen Felder dieser beiden Objekte unverändert.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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

Warnung

Sie müssen _merge_objects auf true setzen, sonst werden Ihre Objekte überschrieben. _merge_objects ist standardmäßig false.

Entfernen Sie Objekte aus einem Array mit dem Operator $remove in Kombination mit einem passenden Schlüssel ($identifier_key) und Wert ($identifier_value).

Verwenden Sie $remove, wenn Sie alle übereinstimmenden Objekte für ein bekanntes Bezeichnerpaar löschen möchten, etwa id = 2 oder type = dog.

Das folgende Beispiel zeigt, wie jedes Objekt im pets-Array entfernt wird, das eine id mit dem Wert 1, eine id mit dem Wert 2 oder einen type mit dem Wert dog hat. Gibt es mehrere Objekte mit dem type-Wert dog, werden alle übereinstimmenden Objekte entfernt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

Verarbeitungsreihenfolge

Wenn eine einzelne /users/track-Anfrage $add-, $remove- und $update-Operationen für dasselbe Array-Attribut enthält, verarbeitet Braze diese in folgender Reihenfolge:

1. $add
2. $remove
3. $update

Diese Reihenfolge gilt innerhalb eines einzelnen Attribut-Update-Objekts in einer Anfrage und bestimmt den endgültigen Zustand des Arrays, nachdem alle Operationen ausgewertet wurden.

Da $add vor $remove ausgeführt wird, können Sie $remove gefolgt von $add innerhalb einer einzelnen Anfrage nicht als Upsert-Mechanismus verwenden. $add wird zuerst verarbeitet, danach löscht $remove den Artikel. Für ein Upsert senden Sie $remove in einer separaten Anfrage vor $add.

Zeitstempel

Wenn Sie Felder wie Zeitstempel in ein Array von Objekten aufnehmen, verwenden Sie das Format $time anstelle von einfachen Strings oder Unix-Epoch-Ganzzahlen.

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

{
  "attributes": [
    {
      "external_id": "user123",
      "purchases": [
        {
          "item_name": "T-shirt",
          "price": 19.99,
          "purchase_time": {
            "$time": "2020-05-28"
          }
        }
      ]
    }
  ]
}

Tipp

Weitere Informationen finden Sie unter Verschachtelte angepasste Attribute.

SDK-Beispiel

• android sdk
• swift sdk
• web sdk

• create
• add
• update
• delete

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

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

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

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

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

• create
• add
• update
• delete

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

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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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)

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

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)

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

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)

Wichtig

Verschachtelte angepasste Attribute werden für AppboyKit nicht unterstützt.

• create
• add
• update
• delete

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

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);

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

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);

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

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);

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

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

Sie können dieses pets-Array verwenden, um eine Nachricht zu personalisieren. Das folgende Liquid-Templating-Beispiel zeigt, wie Sie auf die Eigenschaften des angepassten Attributobjekts verweisen, die mit der vorherigen API-Anfrage gespeichert wurden, und diese in Ihrem Messaging verwenden.

1
2
3
4
5

{% assign pets = {{custom_attribute.${pets}}} %}

{% for pet in pets %}
I have a {{pet.type}} named {{pet.name}}! They are a {{pet.breed}}.
{% endfor %}

In diesem Szenario können Sie mit Liquid das pets-Array in einer Schleife durchlaufen und für jedes Haustier eine Aussage ausgeben. Weisen Sie dem angepassten Attribut pets eine Variable zu und verwenden Sie die Punktnotation, um auf Eigenschaften eines Objekts zuzugreifen. Geben Sie den Namen des Objekts an, gefolgt von einem Punkt . und anschließend dem Namen der Eigenschaft.

Segmentierung

Wenn Sie Nutzer:innen anhand von Arrays von Objekten segmentieren, qualifiziert sich ein:e Nutzer:in für das Segment, sobald irgendein Objekt im Array die Kriterien erfüllt.

Erstellen Sie ein neues Segment und wählen Sie Verschachteltes angepasstes Attribut als Filter aus. Suchen Sie dann nach dem Namen Ihres Arrays von Objekten und wählen Sie ihn aus.

Geben Sie mit der Punktnotation an, welches Feld im Array von Objekten Sie verwenden möchten. Beginnen Sie das Textfeld mit einem leeren Paar eckiger Klammern [], damit Braze weiß, dass Sie innerhalb eines Arrays von Objekten suchen. Fügen Sie danach einen Punkt . hinzu, gefolgt vom Namen des Feldes, das Sie verwenden möchten.

Wenn Sie beispielsweise ein Array von Objekten top_3_movies anhand des Feldes type filtern möchten, geben Sie [].type ein und wählen Sie die Filme aus, nach denen gefiltert werden soll, etwa Fantasy Movie.

Verschachtelungsebenen

Sie können ein Segment mit bis zu einer Ebene der Array-Verschachtelung erstellen (ein Array innerhalb eines anderen Arrays). Bei den folgenden Attributen können Sie zum Beispiel ein Segment für pets[].name enthält Mochi erstellen, jedoch kein Segment für pets[].nicknames[] enthält Gugu.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

Datenpunkte

Datenpunkte werden unterschiedlich protokolliert, je nachdem, ob Sie eine Eigenschaft erstellen, aktualisieren oder entfernen.

• create
• update
• remove

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

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Mochi"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel"
        }
      ]
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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