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

Mit verschachtelten Attributen können Sie aussagekräftigere Segmente erstellen und Nachrichten mit Daten aus einem einzigen angepassten Attributobjekt personalisieren.

Im folgenden Beispiel enthält das angepasste Attribut favorite_book die verschachtelten Attribute title, author und publishing_date. Mit diesem Objekt können Sie Nutzer:innen nach Autor:in ansprechen, nach Veröffentlichungsdatum filtern oder den Buchtitel direkt in eine Nachricht einfü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:

Überlegungen

• 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 einer 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. In der Partner-Dokumentation können Sie überprü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, Objekt-Array-Attribute und angepasste Attribute vom Typ Array. Wenn Sie ein Attribut auswählen, enthält der Eigenschaftsschema-Selektor Array-Pfade (in []-Notation) für verschachtelte Array-Felder. Wenn Sie angepasste Array-Attribute der obersten Ebene in diesem Filter ausblenden möchten, wenden Sie sich an den Braze-Support.
• Wenn Sie im Dashboard eine Vorschau von Nachrichten mit Vorschau als angepasste:r Nutzer:in anzeigen, können Sie Testdaten nur als String oder String-Array eingeben – verschachtelte Objekte werden nicht unterstützt. Um eine Vorschau einer Nachricht anzuzeigen, die auf verschachtelte angepasste Attribute verweist, wählen Sie eine:n bestehende:n Nutzer:in aus, die oder der das verschachtelte Attribut bereits im Profil hat. Für verschachtelte Eigenschaften angepasster Events müssen Sie eine Live-Campaign starten, die auf eine:n Testnutzer:in ausgerichtet ist, um die Darstellung zu überprüfen.

API-Beispiel

• erstellen
• aktualisieren
• löschen

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

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 Ihr Update per Deep Merge mit den bestehenden Objektdaten zusammengeführt. Ein Deep Merge sorgt dafür, dass alle Ebenen eines Objekts mit einem anderen Objekt zusammengeführt werden und nicht nur die erste Ebene. In diesem Beispiel ist in Braze bereits ein Objekt most_played_song vorhanden, und wir fügen dem Objekt most_played_song nun ein neues Feld hinzu: year_released.

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 eingegangen ist, sieht das angepasste Attributobjekt 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
  }
}}

Warnung

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

Um ein angepasstes Attributobjekt zu löschen, senden Sie einen POST an users/track, bei dem das angepasste Attributobjekt auf null gesetzt ist.

1
2
3
4
5
6
7
8

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

Hinweis

Mit diesem Ansatz lässt sich kein verschachtelter Schlüssel innerhalb eines Arrays von Objekten löschen.

SDK-Beispiel

Die folgenden Beispiele zeigen, wie Sie dasselbe Objekt eines verschachtelten angepassten Attributs (most_played_song) in jedem SDK erstellen, per Merge aktualisieren und löschen.

• android sdk
• swift sdk
• web sdk
• unity 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);

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

1
2
3
4

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

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

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 nicht null sein darf.

Hinweis

Wenn _merge_objects auf true gesetzt ist, löscht ein null-Wert ohne $time ein vorhandenes verschachteltes Datumsfeld aus dem Objekt. Wenn das Feld noch nicht existiert, ignoriert Braze den null-Wert und legt das Feld nicht an. In beiden Fällen gibt Braze keinen Fehler zurück.

Wenn Sie Datumsangaben anfangs nicht als Objekteigenschaften erfasst haben, empfehlen wir, diese Daten für alle Nutzer:innen erneut mit dem Schlüssel $time zu senden. Andernfalls kann dies bei Verwendung des Attributs $time zu unvollständigen Segmenten führen. Wenn der Wert für $time in einem verschachtelten angepassten Attribut jedoch nicht korrekt formatiert ist, wird das gesamte verschachtelte angepasste Attribut nicht aktualisiert.

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

Hinweis

Bei verschachtelten angepassten Attributen speichert Braze Werte nicht im Nutzerprofil, wenn die Jahreszahl kleiner als 0 oder größer als 3000 ist.

Liquid-Templating

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 Ihren Nachrichten verwenden.

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

{{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 Liquid für verschachtelte angepasste Attribute in Ihrer Nachricht:

1. Gehen Sie zu einer Campaign oder einem Canvas und öffnen Sie den Nachrichtenschritt, in dem Sie die 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 & Test mit einem bestehenden Nutzer:innen-Profil, das bereits das verschachtelte angepasste Attribut enthält, um zu überprüfen, ob der Wert wie erwartet dargestellt wird.

Personalisierung

Mit Personalisierung hinzufügen können Sie ein verschachteltes angepasstes Attribut in Ihre Nachricht einfügen.

So öffnen Sie Personalisierung hinzufügen:

1. Gehen Sie zu einer Campaign oder einem Canvas und öffnen Sie den Nachrichtenschritt, in dem Sie die 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 dem erwarteten Pfad entspricht.
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.

Tipp

Wenn Sie die Option zum Einfügen verschachtelter angepasster Attribute nicht sehen, prüfen Sie, ob ein Schema generiert wurde.

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 > angepasste Attribute.
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 > angepasste Attribute.
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.

Wichtig

Um das Schema für ein Objekt-Array mit einem vorhandenen Objekt zurückzusetzen, müssen Sie ein neues angepasstes Attribut erstellen. Die Schema-Neugenerierung löscht keine vorhandenen Objekte.

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 einen Trigger auslösen, wenn sich ein verschachteltes angepasstes Attributobjekt ändert. Diese Option ist für Änderungen an Objekt-Arrays nicht verfügbar. Wenn Ihnen keine Option zum Anzeigen des Pfad-Explorers angezeigt wird, überprüfen Sie, ob Sie ein Schema generiert haben.

In einer aktionsbasierten Campaign können Sie beispielsweise eine neue Trigger-Aktion für Wert des angepassten Attributs ändern hinzufügen, um Nutzer:innen anzusprechen, die ihre Präferenzen für das Büro in ihrer Nähe geändert haben.

So konfigurieren Sie diesen Trigger in einer aktionsbasierten Campaign:

1. Erstellen oder bearbeiten Sie eine Campaign und legen Sie dann den Zustellungstyp auf Aktionsbasierte Zustellung fest.
2. Wählen Sie in den Trigger-Einstellungen Wert des angepassten Attributs ändern aus.
3. Wählen Sie den Pfad des verschachtelten angepassten Attributs aus, den Sie überwachen möchten. Wählen Sie zum Beispiel 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

Werte verschachtelter angepasster Attribute werden nicht einheitlich übernommen

Wenn Sie feststellen, dass Werte verschachtelter angepasster Attribute nicht einheitlich zu Nutzerprofilen hinzugefügt werden, liegt das Problem häufig an nicht übereinstimmenden Datentypen.

So diagnostizieren und beheben Sie dieses Problem:

1. Nutzerbeispiele vergleichen: Suchen Sie ein erfolgreiches und ein nicht erfolgreiches Nutzerbeispiel, bei denen das verschachtelte angepasste Attribut hätte gesetzt werden sollen.
2. Datenstruktur prüfen: Sehen Sie sich die Werte der angepassten Attribute 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 ermitteln 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 aus, um zuerst das Schema zu generieren.
   • Nachdem das Schema generiert wurde, wählen Sie in der Spalte Attributname das Plus-Symbol für dieses Attribut aus.
   • Prüfen Sie im Modal Schema bearbeiten die verschachtelten Attribute und die zugehörigen Werte in der Spalte Datentyp.

Wenn Sie feststellen, dass der Datentyp in den Nutzerprofilen nicht dem vorgesehenen Format entspricht, entfernen Sie den falsch formatierten Wert aus den betroffenen Nutzerprofilen und senden Sie das Attribut mit der entsprechenden API-Anfrage oder SDK-Methode erneut im korrekten Format.

Segmentierungsverhalten bei Arrays von Objekten

Wenn Sie mehrere Nested Custom Attribute-Filter mit UND-Logik verwenden, um nach einem Array von Objekten zu segmentieren, wird jeder Filter unabhängig über alle Artikel im Array hinweg ausgewertet. Nutzer:innen qualifizieren sich für das Segment, wenn irgendein Artikel im Array den jeweiligen Filter erfüllt – die Filter müssen nicht auf denselben Artikel zutreffen.

Angenommen, ein:e Nutzer:in hat beispielsweise 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:r Nutzer:in würde sich qualifizieren, da der erste Filter auf den Artikel „Shoes“ zutrifft (80 > 50) und der zweite Filter auf den Artikel „Hat“ (25 < 30). Obwohl kein einzelner Artikel beide Bedingungen erfüllt, wird die Person trotzdem in das Segment aufgenommen.

Wenn alle Bedingungen auf denselben Artikel innerhalb eines Arrays zutreffen sollen, verwenden Sie die Segmentierung nach mehreren Kriterien für denselben Pfad, oder strukturieren Sie Ihre Daten so um, dass artikelübergreifende Übereinstimmungen vermieden werden.

Datenpunkte

Jeder gesendete Schlüssel verbraucht einen Datenpunkt. Dieses im Nutzerprofil initialisierte Objekt zählt beispielsweise 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
        }
      }
    }
  ]
}

Hinweis

Auch das Aktualisieren eines angepassten Attributobjekts auf null verbraucht einen Datenpunkt.