Skip to content

Verschachtelte angepasste Attribute

Diese Seite behandelt verschachtelte angepasste Attribute, die es Ihnen ermöglichen, eine Reihe von Attributen als Eigenschaft eines anderen Attributs zu definieren. Mit anderen Worten: Wenn Sie ein angepasstes Attribut-Objekt definieren, können Sie eine Reihe von zusätzlichen Attributen für dieses Objekt festlegen.

Über verschachtelte Attribute

Verschachtelte Attribute ermöglichen es Ihnen, umfangreichere Segmente zu erstellen und Nachrichten mit Daten aus einem einzelnen angepassten Attribut-Objekt zu personalisieren.

Im folgenden Beispiel enthält das angepasste Attribut favorite_book die verschachtelten Attribute title, author und publishing_date. Dieses Objekt kann verwendet werden, um Nutzer:innen nach Autor:in anzusprechen, nach Veröffentlichungsdatum zu filtern oder den Buchtitel direkt in eine Nachricht einzufügen:

1
2
3
4
5

"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

Unterstützte Datentypen

Die folgenden Datentypen werden unterstützt:

Datentyp Beschreibung
Zahl Ein numerischer Wert, wie z. B. 1 oder 5.5.
String Ein Textwert, wie z. B. "Hello" oder "The Hobbit".
Boolescher Wert Ein Wert, der entweder zu true oder false ausgewertet wird.
Array Eine Liste von Werten, wie z. B. ["red", "blue", "green"].
Zeit Ein Zeitstempelwert, der für Datums- und Zeitvergleiche verwendet wird. Beim Filtern eines verschachtelten angepassten Zeitattributs können Sie wählen:

  • Day of Year: Prüft nur den Monat und den Tag zum Vergleich, z. B. 03-15.
  • Time: Vergleicht den vollständigen Zeitstempel einschließlich des Jahres, z. B. 2023-03-15T12:00:00Z.
Objekt Ein strukturierter Wert mit Schlüssel-Wert-Paaren, wie z. B. {"author": "Tolkien"}.
Array von Objekten Eine Liste von Objekten, wie z. B. [{"title": "The Hobbit"}, {"title": "Dune"}]. Weitere Informationen finden Sie unter Arrays von Objekten.

Hinweise

  • Verschachtelte angepasste Attribute sind für angepasste Attribute vorgesehen, die über das Braze SDK oder die API gesendet werden.
  • Objekte haben eine maximale Größe von 100 KB. Wenn ein Update dazu führt, dass das Objekt 100 KB überschreitet, verwirft Braze das Update und das Attribut bleibt unverändert.
  • Schlüsselnamen und String-Werte haben eine Größenbeschränkung von 255 Zeichen.
  • Schlüsselnamen dürfen keine Leerzeichen enthalten.
  • Punkte (.) und Dollarzeichen ($) werden in einem API-Payload nicht unterstützt, wenn Sie versuchen, ein verschachteltes angepasstes Attribut an ein Nutzerprofil zu senden.
  • Nicht alle Braze-Partner unterstützen verschachtelte angepasste Attribute. Lesen Sie die Partner-Dokumentation, um zu prüfen, ob bestimmte Partnerintegrationen dieses Feature unterstützen.
  • Verschachtelte angepasste Attribute können nicht als Filter bei einem Connected-Audience-API-Aufruf verwendet werden.
  • Standardmäßig umfasst der Segment-Filter Verschachtelte angepasste Attribute angepasste Attribute vom Typ „Objekt“, Attribute vom Typ „Array von Objekten“ und angepasste Attribute vom Typ „Array“. Wenn Sie ein Attribut auswählen, enthält der Eigenschaftsschema-Selektor Array-Pfade (mit []-Notation) für verschachtelte Array-Felder. Um angepasste Attribute vom Typ „Array“ auf oberster Ebene aus diesem Filter auszublenden, wenden Sie sich an den Braze-Support.
  • Wenn Sie Nachrichten im Dashboard mit Als angepasste:r Nutzer:in in der Vorschau anzeigen in der Vorschau betrachten, können Sie Testdaten nur als String oder String-Array eingeben – verschachtelte Objekte werden nicht unterstützt. Um eine Nachricht in der Vorschau anzuzeigen, die auf verschachtelte angepasste Attribute verweist, wählen Sie eine:n bestehende:n Nutzer:in aus, die bzw. der das verschachtelte Attribut bereits in ihrem bzw. seinem Profil hat. Für verschachtelte angepasste Event-Eigenschaften müssen Sie eine Live-Campaign starten, die auf eine:n Testnutzer:in ausgerichtet ist, um das Rendering zu überprüfen.

API-Beispiel

Das folgende Beispiel zeigt eine /users/track-Anfrage mit einem „Most Played Song“-Objekt. Um die Eigenschaften des Songs zu erfassen, senden wir eine API-Anfrage, die most_played_song als Objekt zusammen mit einer Reihe von Objekteigenschaften auflistet.

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

Um ein bestehendes Objekt zu aktualisieren, senden Sie einen POST an users/track mit dem Parameter _merge_objects in der Anfrage. Dadurch wird Ihre Aktualisierung per Deep Merge mit den vorhandenen Objektdaten zusammengeführt. Deep Merging stellt sicher, dass alle Ebenen eines Objekts in ein anderes Objekt zusammengeführt werden, anstatt nur die erste Ebene. In diesem Beispiel haben wir bereits ein most_played_song-Objekt in Braze und fügen nun ein neues Feld, year_released, zum most_played_song-Objekt hinzu.

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

Nachdem diese Anfrage empfangen wurde, sieht das angepasste Attribut-Objekt wie folgt aus:

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

Um ein angepasstes Attribut-Objekt zu löschen, senden Sie einen POST an users/track, wobei das angepasste Attribut-Objekt auf null gesetzt wird.

1
2
3
4
5
6
7
8

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

SDK-Beispiel

Die folgenden Beispiele zeigen, wie Sie dasselbe verschachtelte angepasste Attribut-Objekt (most_played_song) über die einzelnen SDKs erstellen, per Merge aktualisieren und löschen können.

Erstellen

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

Aktualisieren

1
2
3
4
5
6

val json = JSONObject()
    .put("year_released", 1960)

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json, true)
}

Löschen

1
2
3

braze.getCurrentUser { user ->
    user.unsetCustomUserAttribute("most_played_song")
}

Erstellen

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)

Aktualisieren

1
2
3
4
5

let json: [String: Any?] = [
  "year_released": 1960
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json, merge: true)

Löschen

1

braze.user.unsetCustomAttribute(key: "most_played_song")

Erstellen

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

Aktualisieren

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

Löschen

1
2

import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);

Erstellen

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

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("song_name", "Solea");
attributes.Add("artist_name", "Miles Davis");
attributes.Add("album_name", "Sketches of Spain");
attributes.Add("genre", "Jazz");

Dictionary<string, object> playAnalytics = new Dictionary<string, object>();
playAnalytics.Add("count", 1000);
playAnalytics.Add("top_10_listeners", true);
attributes.Add("play_analytics", playAnalytics);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes);

Aktualisieren

1
2
3
4

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("year_released", 1960);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes, true);

Löschen

1

AppboyBinding.UnsetCustomUserAttribute("most_played_song");

Datumsangaben als Objekteigenschaften erfassen

Um Datumsangaben als Objekteigenschaften zu erfassen, müssen Sie den Schlüssel $time verwenden. Im folgenden Beispiel wird ein Objekt „Important Dates“ verwendet, um die Objekteigenschaften birthday und wedding_anniversary zu erfassen. Der Wert für diese Datumsangaben ist ein Objekt mit einem $time-Schlüssel, der kein Nullwert sein darf.

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

Das folgende Liquid-Vorlagenbeispiel zeigt, wie Sie die angepassten Attribut-Objekteigenschaften referenzieren, die aus der vorhergehenden API-Anfrage gespeichert wurden, und sie in Ihren Nachrichten verwenden.

Verwenden Sie den Personalisierungs-Tag custom_attribute und die Punktnotation, um auf Eigenschaften eines Objekts zuzugreifen. Geben Sie den Namen des Objekts (und die Position im Array, wenn Sie auf ein Objekt-Array verweisen) an, gefolgt von einem Punkt, gefolgt vom Eigenschaftsnamen.

{{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“

So verwenden Sie verschachtelte angepasste Attribute als Liquid in Ihrer Nachricht:

  1. Gehen Sie zu einer Campaign oder einem Canvas und öffnen Sie dann den Nachrichtenschritt, in dem Sie Personalisierung hinzufügen möchten.
  2. Fügen Sie im Nachrichten-Editor das Liquid-Snippet an der Stelle ein, an der der Wert erscheinen soll.
  3. Verwenden Sie Vorschau und Test mit einer bestehenden Nutzer:in, die das verschachtelte angepasste Attribut bereits in ihrem Profil hat, um zu bestätigen, dass der Wert wie erwartet gerendert wird.

Personalisierung

Sie können Personalisierung hinzufügen verwenden, um ein verschachteltes angepasstes Attribut in Ihre Nachricht einzufügen.

So öffnen Sie Personalisierung hinzufügen:

  1. Gehen Sie zu einer Campaign oder einem Canvas und öffnen Sie dann den Nachrichtenschritt, in dem Sie Personalisierung hinzufügen möchten.
  2. Wählen Sie im Nachrichten-Editor Personalisierung aus, um die Seitenleiste Personalisierung hinzufügen zu öffnen, in der Sie Personalisierungsoptionen auswählen können.

So konfigurieren Sie die Personalisierung mit verschachtelten angepassten Attributen:

  1. Wählen Sie unter Personalisierungstyp die Option Verschachtelte angepasste Attribute aus.
  2. Wählen Sie unter Attribut der obersten Ebene den Pfad des verschachtelten angepassten Attributs aus, den Sie einfügen möchten. Wählen Sie zum Beispiel preferences.neighborhood_office aus.
  3. Optional: Geben Sie unter Standardwert einen Fallback-Wert für Nutzer:innen ein, die keinen eigenen Wert für dieses Attribut haben.
  4. Überprüfen Sie das generierte Liquid-Snippet, um sicherzustellen, dass es mit dem erwarteten Pfad übereinstimmt.
  5. Wählen Sie Einfügen aus.

In diesem Beispiel fügt Braze den verschachtelten Wert für preferences.neighborhood_office in Ihre Nachricht ein. Standardwerte sind Fallbacks, die Ihre Nachricht für Nutzer:innen enthält, die keinen eigenen Wert für ein Attribut haben.

Schemas generieren und neu generieren

Um verschachtelte angepasste Attribute in der Segmentierung und Personalisierung zu verwenden, müssen Sie ein Schema für das Attribut generieren. Nachdem ein Schema generiert wurde, können Sie es bei Bedarf neu generieren. Ausführlichere Informationen zu Schemas finden Sie unter Schema mit dem Nested-Object-Explorer generieren.

Schema generieren

Nachdem Sie ein verschachteltes angepasstes Attribut erstellt und Daten an Braze gesendet haben, können Sie das Schema generieren:

  1. Gehen Sie zu Data Settings > Custom Attributes.
  2. Suchen Sie nach Ihrem verschachtelten angepassten Attribut.
  3. Wählen Sie in der Spalte Attribute Name für Ihr Attribut Generate Schema aus.

Nachdem das Schema generiert wurde, ändert sich das -Symbol zu einem -Plus-Symbol, das Sie auswählen können, um das Schema anzuzeigen und zu verwalten.

Schema neu generieren

So generieren Sie das Schema für Ihr verschachteltes angepasstes Attribut neu:

  1. Gehen Sie zu Data Settings > Custom Attributes.
  2. Suchen Sie nach Ihrem verschachtelten angepassten Attribut.
  3. Wählen Sie in der Spalte Attribute Name für Ihr Attribut Manage schema aus, um das Schema zu verwalten.
  4. Ein Modal wird angezeigt. Wählen Sie Regenerate Schema aus.

Sie können keine weitere Neugenerierung starten, während ein Schema-Job bereits in Bearbeitung ist (die Option ist nicht verfügbar, solange der Status Generating lautet). Pro Unternehmen kann jeweils nur ein Schema-Generierungsjob gleichzeitig ausgeführt werden. Die Schema-Neugenerierung erkennt nur neue Objekte und löscht keine Objekte, die derzeit im Schema vorhanden sind.

Wenn Daten nach der Schema-Neugenerierung nicht wie erwartet angezeigt werden, wird das Attribut möglicherweise nicht häufig genug erfasst. Nutzerdaten werden auf Basis zuvor an Braze gesendeter Daten für das jeweilige verschachtelte Attribut gesampelt. Wenn das Attribut nicht häufig genug erfasst wird, wird es nicht für das Schema berücksichtigt.

Änderungen an verschachtelten angepassten Attributen triggern

Sie können triggern, wenn sich ein verschachteltes angepasstes Attribut-Objekt ändert. Diese Option ist nicht für Änderungen an Objekt-Arrays verfügbar. Wenn Sie keine Option zum Anzeigen des Pfad-Explorers sehen, überprüfen Sie, ob Sie ein Schema generiert haben.

In einer aktionsbasierten Campaign können Sie beispielsweise eine neue Aktion triggern für Angepassten Attributwert ändern, um Nutzer:innen anzusprechen, die ihre Präferenzen für das Nachbarschaftsbüro geändert haben.

So konfigurieren Sie diesen Trigger in einer aktionsbasierten Campaign:

  1. Erstellen oder bearbeiten Sie eine Campaign und setzen Sie den Zustellungstyp auf Aktionsbasierte Zustellung.
  2. Wählen Sie in den Trigger-Einstellungen Angepassten Attributwert ändern aus.
  3. Wählen Sie den Pfad des verschachtelten angepassten Attributs aus, den Sie überwachen möchten. Wählen Sie beispielsweise preferences.neighborhood_office aus.
  4. Wählen Sie die gewünschte Trigger-Bedingung aus, z. B. beliebiger neuer Wert.
  5. Schließen Sie die Konfiguration Ihrer Campaign-Nachricht und Zielgruppe ab und starten Sie dann die Campaign.

Fehlerbehebung

Verschachtelte angepasste Attributwerte werden nicht konsistent angewendet

Wenn Sie feststellen, dass verschachtelte angepasste Attributwerte nicht konsistent zu Nutzerprofilen hinzugefügt werden, liegt das Problem häufig an Datentyp-Abweichungen.

So diagnostizieren und beheben Sie dieses Problem:

  1. Nutzerbeispiele vergleichen: Beschaffen Sie sich ein erfolgreiches und ein nicht erfolgreiches Nutzerbeispiel, bei dem das verschachtelte angepasste Attribut gesetzt worden sein sollte.
  2. Datenstruktur überprüfen: Sehen Sie sich die angepassten Attributwerte in beiden Profilen an und vergleichen Sie sie:
    • Sind die Eigenschaften unter einem Objekt gespeichert?
    • Sind die Eigenschaften als Array von Eigenschaften gespeichert?
  3. Segmentierungsfilter prüfen: Vergleichen Sie die gespeicherte Datenstruktur damit, wie das verschachtelte angepasste Attribut in Ihren Segmentierungsfiltern referenziert wird.
  4. Datentyp überprüfen: So identifizieren Sie den Datentyp eines angepassten Attributs:
    • Gehen Sie zu Dateneinstellungen > Angepasste Attribute.
    • Suchen Sie nach dem übergeordneten angepassten Attribut, das das verschachtelte Attribut enthält, das Sie überprüfen möchten.
    • Wenn in der Zeile Schema generieren angezeigt wird, wählen Sie diese Option, um das Schema zuerst zu generieren.
    • Nachdem das Schema generiert wurde, wählen Sie das Plus-Symbol in der Spalte Attributname für dieses Attribut.
    • Überprüfen Sie im Modal Schema bearbeiten die verschachtelten Attribute und ihre entsprechenden Werte in der Spalte Datentyp.

Wenn Sie feststellen, dass der Datentyp nicht mit dem beabsichtigten Format über die Nutzerprofile hinweg übereinstimmt, entfernen Sie den falsch formatierten Wert aus den betroffenen Nutzerprofilen und senden Sie das Attribut im korrekten Format erneut, indem Sie die entsprechende API-Anfrage oder SDK-Methode verwenden.

Segmentierungsverhalten bei Objekt-Arrays

Wenn Sie mehrere Filter für Nested Custom Attribute mit UND-Logik verwenden, um auf einem Objekt-Array zu segmentieren, wird jeder Filter unabhängig über alle Elemente im Array ausgewertet. Nutzer:innen qualifizieren sich für das Segment, wenn irgendein Element im Array jeden einzelnen Filter erfüllt – die Filter müssen nicht auf dasselbe Element zutreffen.

Angenommen, Nutzer:innen haben das folgende Array:

1
2
3
4
5
6

{
  "orders": [
    {"product": "Shoes", "price": 80},
    {"product": "Hat", "price": 25}
  ]
}

Ein Segment mit den folgenden UND-Filtern:

  • orders[].price ist größer als 50
  • orders[].price ist kleiner als 30

Diese Nutzer:innen würden sich qualifizieren, weil der erste Filter auf den Artikel „Shoes“ zutrifft (80 > 50) und der zweite Filter auf den Artikel „Hat“ zutrifft (25 < 30). Obwohl kein einzelnes Element beide Bedingungen erfüllt, werden die Nutzer:innen trotzdem in das Segment aufgenommen.

Wenn alle Bedingungen auf dasselbe Element innerhalb eines Arrays zutreffen müssen, verwenden Sie die Multikriterien-Segmentierung auf demselben Pfad oder strukturieren Sie Ihre Daten um, um elementübergreifendes Matching zu vermeiden.

Datenpunkte

Jeder gesendete Schlüssel verbraucht einen Datenpunkt. Zum Beispiel zählt dieses im Nutzerprofil initialisierte Objekt als sieben (7) Datenpunkte:

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
        }
      }
    }
  ]
}
New Stuff!