Nutzer:innen-Attribute-Objekt

Eine API-Anfrage mit beliebigen Feldern im Attributobjekt erstellt oder aktualisiert ein Attribut mit diesem Namen und dem angegebenen Wert im angegebenen Nutzerprofil.

Verwenden Sie die Feldnamen des Braze-Nutzerprofils (wie nachfolgend aufgelistet oder alle im Abschnitt für Braze-Nutzerprofilfelder aufgeführten), um diese speziellen Werte im Nutzerprofil im Dashboard zu aktualisieren, oder fügen Sie Ihre eigenen angepassten Attributdaten für die Nutzer:innen hinzu.

Objektkörper

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
30

{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required
  "external_id" : (optional, string) see external user ID,
  "user_alias" : (optional, User alias object),
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" defaults to true.
  "_update_existing_only" : (optional, boolean),
  // See note regarding anonymous push token imports
  "push_token_import" : (optional, boolean),
  // Braze User Profile Fields
  "first_name" : "Alex",
  "email" : "[email protected]",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
  // Array of objects custom attribute
  "my_array_of_objects_attribute": [{"key": "value"}, {"key": "value"}],
  // Adding to an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$add": [{"key": "value"}] },
  // Removing from an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• Externe Nutzer-ID
• Nutzer-Aliase

Hinweis

Verwenden Sie für reguläre angepasste Array-Attribute add und remove (ohne $).

Verwenden Sie für Arrays von Objekten (verschachtelte angepasste Attribute) $add, $remove und $update in /users/track-Anfrage-Payloads. Diese Operatoren wenden Änderungen auf Objektebene an, indem sie Bezeichner ($identifier_key und $identifier_value) abgleichen und unterstützen In-place-Updates mit $new_object.

Verwenden Sie dieses Format, wenn Sie Objekte innerhalb eines bestehenden Arrays anhängen, entfernen oder aktualisieren müssen und dabei den restlichen Array-Zustand beibehalten möchten. Vollständige Anfrage-Beispiele finden Sie unter Array von Objekten – API-Beispiel und Array von Objekten – SDK-Beispiel.

Um ein Profilattribut zu entfernen, setzen Sie es auf null. Einige Felder, wie external_id und user_alias, können nicht mehr entfernt werden, nachdem sie einem Nutzerprofil hinzugefügt wurden.

Bezeichnerauflösung

Sofern Sie keinen anonymen Push-Token-Import durchführen, muss jedes Nutzerattribut-Objekt mindestens einen Bezeichner enthalten: external_id, user_alias, braze_id, email oder phone. Verwenden Sie nach Möglichkeit nur einen Bezeichner pro Objekt, um Mehrdeutigkeiten darüber zu vermeiden, welches Nutzerprofil aktualisiert oder erstellt wird.

Beachten Sie Folgendes bei der Verwendung von Bezeichnern:

• external_id und user_alias schließen sich gegenseitig aus. Wenn beide im selben Nutzerattribut-Objekt enthalten sind, wird ein Fehler zurückgegeben. Um einen Alias zu einer Nutzerin oder einem Nutzer hinzuzufügen, die/der bereits eine external_id hat, verwenden Sie den /users/alias/new-Endpunkt.
• email hat Vorrang vor phone. Wenn sowohl email als auch phone im selben Objekt enthalten sind, verwendet Braze email als Bezeichner. Das bedeutet, dass die Attribute dem Nutzerprofil zugeordnet werden, das mit dieser E-Mail-Adresse verknüpft ist – selbst wenn die Telefonnummer zu einem anderen Profil gehört.

Wichtig

Um unerwartetes Verhalten zu vermeiden, verwenden Sie einen einzelnen Bezeichner pro Nutzerattribut-Objekt. Die Angabe mehrerer Bezeichner, die auf verschiedene Nutzerprofile verweisen, kann dazu führen, dass Attribute dem falschen Profil zugeordnet werden.

Nur bestehende Profile aktualisieren

Wenn Sie ausschließlich bestehende Nutzerprofile in Braze aktualisieren möchten, sollten Sie den Schlüssel _update_existing_only mit dem Wert true im Body Ihrer Anfrage übergeben. Wird dieser Wert weggelassen, erstellt Braze ein neues Nutzerprofil, falls die external_id noch nicht existiert.

Hinweis

Wenn Sie ein Nur-Alias-Nutzerprofil über den /users/track-Endpunkt erstellen, müssen Sie _update_existing_only auf false setzen. Wenn Sie diesen Wert weglassen, erstellt Braze das Nur-Alias-Profil nicht.

Push-Token-Import

Bevor Sie Push-Token in Braze importieren, überprüfen Sie, ob dies erforderlich ist. Wenn die Braze-SDKs eingerichtet sind, verwalten sie Push-Token automatisch – ein Upload über die API ist dann nicht nötig.

Falls Sie sie dennoch über die API hochladen müssen, können sie entweder für identifizierte oder anonyme Nutzer:innen hochgeladen werden. Das bedeutet, dass entweder eine external_id vorhanden sein muss oder bei anonymen Nutzer:innen das Flag push_token_import auf true gesetzt sein muss.

Hinweis

Beim Import von Push-Token aus anderen Systemen ist eine external_id nicht immer verfügbar. Um die Kommunikation mit diesen Nutzer:innen während Ihres Übergangs zu Braze aufrechtzuerhalten, können Sie die Legacy-Token für anonyme Nutzer:innen ohne Angabe einer external_id importieren, indem Sie push_token_import als true angeben.

Wenn push_token_import auf true gesetzt ist:

• external_id und braze_id sollten nicht angegeben werden
• Das Attribut-Objekt muss ein Push-Token enthalten
• Wenn das Token bereits in Braze existiert, wird die Anfrage ignoriert; andernfalls erstellt Braze ein temporäres, anonymes Nutzerprofil für jedes Token, damit Sie diese Personen weiterhin kontaktieren können

Nach dem Import verschiebt Braze automatisch das importierte Push-Token in das Braze-Nutzerprofil, sobald die jeweiligen Nutzer:innen die Braze-fähige Version Ihrer App starten, und bereinigt das temporäre Profil.

Braze prüft einmal monatlich, ob anonyme Profile mit dem Flag push_token_import vorhanden sind, die kein Push-Token mehr haben. Wenn ein anonymes Profil kein Push-Token mehr hat, löscht Braze das Profil. Hat das anonyme Profil jedoch noch ein Push-Token – was darauf hindeutet, dass sich die tatsächlichen Nutzer:innen noch nicht auf dem Gerät mit dem betreffenden Push-Token angemeldet haben –, unternimmt Braze nichts.

Weitere Informationen finden Sie unter Push-Token migrieren.

Datentypen für angepasste Attribute

Die folgenden Datentypen können als angepasstes Attribut gespeichert werden:

Tipp

Hinweise dazu, wann ein angepasstes Event gegenüber einem angepassten Attribut verwendet werden sollte, finden Sie unter Angepasste Events und Angepasste Attribute.

Array-von-Objekten-Beispiel

Dieses Array von Objekten ermöglicht es Ihnen, Segmente basierend auf bestimmten Kriterien innerhalb der Aufenthalte zu erstellen und Ihre Nachrichten mit den Daten aus jedem Aufenthalt mithilfe von Liquid-Templates zu personalisieren.

1
2
3
4

{"hotel_stays": [
  { "hotel_name": "Ocean View Resort", "check_in_date": "2023-06-15", "nights_stayed": 5 },
  { "hotel_name": "Mountain Lodge", "check_in_date": "2023-09-10", "nights_stayed": 3 }
]}

Beispiele für Array-von-Objekten-Operationen mit $add, $remove und $update finden Sie unter Array von Objekten – API-Beispiel und Array von Objekten – SDK-Beispiel.

Braze-Nutzerprofilfelder

Wichtig

Die folgenden Nutzerprofilfelder unterscheiden Groß- und Kleinschreibung. Stellen Sie daher sicher, dass Sie diese Felder in Kleinbuchstaben angeben.

Tipp

Eine nach Kategorien geordnete Referenz der Standardattribute mit Anleitungen für SDK, API, CSV und Cloud Data Ingestion finden Sie unter Standardattribute.

Sprachwerte, die explizit über diese API gesetzt werden, haben Vorrang vor den Gebietsschema-Informationen, die Braze automatisch vom Gerät erhält.

Beispiel-Anfrage für Nutzerattribute

Dieses Beispiel enthält vier Nutzerattribut-Objekte, von insgesamt 75 zulässigen Attribut-Objekten pro API-Aufruf.

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
30

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Alex",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Lee",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": "Your App Identifier", "token": "abcd", "device_id": "optional_field_value"}]

    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "first_name" : "Yuri",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

Push-Token migrieren

Wenn Sie vor der Integration von Braze bereits Push-Benachrichtigungen versendet haben – sei es eigenständig oder über einen anderen Anbieter –, ermöglicht Ihnen die Push-Token-Migration, weiterhin Push-Benachrichtigungen an Ihre Nutzer:innen mit registrierten Push-Token zu senden.

Automatische Migration über das SDK

Nachdem Sie das Braze SDK integriert haben, werden Push-Token für Ihre eingewilligten Nutzer:innen automatisch migriert, sobald diese Ihre App das nächste Mal öffnen. Bis dahin können Sie diesen Nutzer:innen keine Push-Benachrichtigungen über Braze senden.

Alternativ können Sie Ihre Push-Token manuell migrieren, um Ihre Nutzer:innen schneller erneut anzusprechen.

Besondere Hinweise für Web-Token

Aufgrund der Beschaffenheit von Web-Push-Token sollten Sie bei der Implementierung von Push für Web Folgendes beachten:

Manuelle Migration über die API

Die manuelle Push-Token-Migration ist der Prozess, bei dem diese zuvor erstellten Schlüssel über die API in Ihre Braze-Plattform importiert werden.

Migrieren Sie iOS- (APNs) und Android-Token (FCM) programmatisch auf Ihre Plattform, indem Sie den users/track-Endpunkt verwenden. Sie können sowohl identifizierte Nutzer:innen (Nutzer:innen mit einer zugeordneten externen ID) als auch anonyme Nutzer:innen (Nutzer:innen ohne externe ID) migrieren.

Hinweis

Braze geht davon aus, dass importierte Push-Token gültige Vordergrund-Push-Token für Ihre App und Umgebung sind.

Beim Import von iOS-Token speichert Braze kein Apple Push Notification service (APNs)-Gateway (development oder production) für diese. Braze sendet an diese Token über das konfigurierte Gateway Ihrer App. Wenn ein Token für die andere Umgebung generiert wurde, lehnt APNs es mit BadDeviceToken ab und der Versand führt zu einem Bounce.

Braze speichert ein Gateway für das Token nur, wenn das SDK später dasselbe Token registriert und ein Gateway meldet.

Geben Sie bei der Push-Token-Migration die app_id Ihrer App an, um das entsprechende Push-Token der richtigen App zuzuordnen. Jede App (iOS, Android usw.) hat eine eigene app_id, die im Abschnitt Identification auf der Seite API-Schlüssel zu finden ist. Verwenden Sie unbedingt die app_id der richtigen Plattform.

Wichtig

Es ist nicht möglich, Web-Push-Token über die API zu migrieren. Dies liegt daran, dass Web-Push-Token nicht demselben Schema wie andere Plattformen entsprechen.

Wenn Sie versuchen, Web-Push-Token programmatisch zu migrieren, wird möglicherweise ein Fehler wie der folgende angezeigt: Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

Als Alternative zur API-Migration empfehlen wir, das SDK zu integrieren und Ihre Token-Basis auf natürliche Weise wieder aufzubauen.

• externe id vorhanden
• externe id nicht vorhanden

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes" : [
    {
      "push_token_import" : false,
      "external_id": "example_external_id",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING"}
      ]
    }
  ]
}'

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    },

    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE_1": "YOUR_VALUE",
      "YOUR_CUSTOM_ATTRIBUTE_2": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    }
  ]
}'

iOS-Push-Token importieren

Beim Migrieren von iOS-Push-Token mit /users/track wird das Feld gateway am Push-Token nicht gesetzt. Braze geht davon aus, dass über die API importierte Token gültige Vordergrund-Push-Token sind, kann jedoch nicht feststellen, zu welcher APNs-Umgebung das Token gehört.

Ohne das Gateway-Feld verwendet Braze beim Senden von Push-Benachrichtigungen die konfigurierte Fallback-Umgebungseinstellung Ihrer App. Dies kann zu BadDeviceToken-Fehlern führen, wenn die tatsächliche Umgebung des Tokens von der konfigurierten Fallback-Umgebung abweicht. Zum Beispiel wird ein Entwicklungs-Token, das über das Produktions-Gateway gesendet wird, fehlschlagen.

Um Zustellungsprobleme zu vermeiden:

• Stellen Sie sicher, dass die Umgebungseinstellung Ihrer App im Braze-Dashboard mit den Token übereinstimmt, die Sie importieren.
• Importieren Sie für Produktions-Apps nur Produktions-Token.
• Überprüfen Sie bei Testumgebungen, dass sowohl Ihre App-Konfiguration als auch die importierten Token die Entwicklungsumgebung verwenden.

Hinweis

Token, die über das Braze SDK registriert werden, enthalten automatisch das Gateway-Feld, da das SDK die Umgebung aus den Berechtigungen Ihrer App erkennt.

Android-Push-Token importieren

Wichtig

Der folgende Hinweis gilt nur für Android-Apps. iOS-Apps erfordern diese Schritte nicht, da diese Plattform nur ein Framework zur Anzeige von Push bietet und Push-Benachrichtigungen sofort dargestellt werden, solange Braze die erforderlichen Push-Token und Zertifikate hat.

Wenn Sie Android-Push-Benachrichtigungen an Ihre Nutzer:innen senden müssen, bevor die Braze-SDK-Integration abgeschlossen ist, verwenden Sie Schlüssel-Wert-Paare, um Push-Benachrichtigungen zu validieren.

Sie benötigen einen Receiver, der Push-Payloads verarbeitet und anzeigt. Um den Receiver über das Push-Payload zu informieren, fügen Sie der Push-Campaign die erforderlichen Schlüssel-Wert-Paare hinzu. Die Werte dieser Paare hängen vom jeweiligen Push-Partner ab, den Sie vor Braze verwendet haben.

Hinweis

Bei einigen Push-Benachrichtigungsanbietern muss Braze die Schlüssel-Wert-Paare vereinfachen, damit sie korrekt interpretiert werden können. Um Schlüssel-Wert-Paare für eine bestimmte Android-App zu vereinfachen, wenden Sie sich an Ihren Customer-Success-Manager.

Häufig gestellte Fragen

Wie finde ich Nutzer:innen, die als Spam behandelt oder vom Messaging ausgeschlossen wurden?

Braze stellt keine dedizierte Spam-Liste im Dashboard bereit. Braze blockiert individuelle Nutzerprofile („Dummy-Nutzer:innen“) mit mehr als fünf Millionen Sessions, mehr als 20.000 verschiedenen angepassten Event-Namen oder mehr als 20.000 verschiedenen Produktnamen in Käufen und stoppt die Aufnahme aller eingehenden Daten für dieses Profil – sowohl von den SDKs als auch von der REST API. Wenn ein Bezeichner blockiert ist, kann /users/track den Fehler "provided external_id is blacklisted and disallowed" zurückgeben. Dieser Wortlaut stammt wörtlich aus der API-Antwort. Um Profile zu finden, die aufgrund übermäßiger Sessions blockiert wurden, erstellen Sie ein Segment mit dem Filter Session Count, der auf more than 5,000,000 gesetzt ist, exportieren Sie das Segment als CSV und gleichen Sie die Profilfelder unter Engagement > Search users oder mit dem Endpunkt /users/export/ids ab. Es gibt keinen entsprechenden Filter für verschiedene angepasste Event-Namen oder Produktnamen. Wenden Sie sich daher an Ihren Braze Account Manager, um Profile zu identifizieren, die aus diesen Gründen blockiert wurden. Weitere Informationen finden Sie unter Spam-Blockierung.