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 Array-basierte angepasste Attribute add und remove (ohne $).

Für Arrays von Objekten (verschachtelte angepasste Attribute) verwenden Sie $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 In-Place-Aktualisierungen mit $new_object unterstützen.

Verwenden Sie dieses Format, wenn Sie Objekte innerhalb eines bestehenden Arrays anhängen, entfernen oder aktualisieren müssen, während der restliche Array-Zustand erhalten bleibt. 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 entfernt werden, nachdem sie einem Nutzerprofil hinzugefügt wurden.

Bezeichner-Auflö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 einem Nutzer, der bereits eine external_id hat, einen Alias hinzuzufügen, 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 auf das Nutzerprofil angewendet 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 zugewiesen werden.

Nur bestehende Profile aktualisieren

Wenn Sie nur bestehende Nutzerprofile in Braze aktualisieren möchten, sollten Sie den Schlüssel _update_existing_only mit dem Wert true im Anfragekörper übergeben. Wenn dieser Wert ausgelassen wird, erstellt Braze ein neues Nutzerprofil, falls die external_id noch nicht existiert.

Hinweis

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

Push-Token-Import

Bevor Sie Push-Token in Braze importieren, prüfen Sie, ob dies erforderlich ist. Wenn die Braze SDKs eingebunden sind, verwalten sie Push-Token automatisch, ohne dass diese über die API hochgeladen werden müssen.

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 Ihrer Umstellung auf Braze aufrechtzuerhalten, können Sie die Legacy-Token für anonyme Nutzer:innen ohne Angabe einer external_id importieren, indem Sie push_token_import auf true setzen.

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 diesen Personen weiterhin Nachrichten senden können

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

Braze prüft einmal im Monat, ob ein anonymes Profil mit dem Flag push_token_import existiert, das kein Push-Token mehr besitzt. Wenn das anonyme 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 der tatsächliche Nutzer noch nicht auf dem Gerät mit diesem Push-Token angemeldet hat –, unternimmt Braze nichts.

Weitere Informationen finden Sie unter Push-Token migrieren.

Datentypen angepasster Attribute

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

Tipp

Hinweise dazu, wann Sie ein angepasstes Event statt eines angepassten Attributs verwenden sollten, 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 mithilfe der Daten jedes Aufenthalts mit 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 Arrays von Objekten, die $add, $remove und $update verwenden, finden Sie unter Array von Objekten – API-Beispiel und Array von Objekten – SDK-Beispiel.

Braze-Nutzerprofilfelder

Wichtig

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

Tipp

Eine kundenorientierte Referenz der Standardattribute, die nach Kategorie organisiert ist und Hinweise für SDK, API, CSV und Cloud Data Ingestion enthält, 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.

Beispielanfrage 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 bereits vor der Integration von Braze Push-Benachrichtigungen versendet haben – entweder 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 die Push-Token Ihrer angemeldeten Nutzer:innen automatisch beim nächsten Öffnen Ihrer App migriert. 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 wieder anzusprechen.

Hinweise zu Web-Token

Aufgrund der Beschaffenheit von Web-Push-Token sollten Sie bei der Implementierung von Push für das 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 zugehörigen externen ID) als auch anonyme Nutzer:innen (Nutzer:innen ohne externe ID) migrieren.

Geben Sie die app_id Ihrer App während der Push-Token-Migration an, um das entsprechende Push-Token der entsprechenden App zuzuordnen. Jede App (iOS, Android usw.) hat eine eigene app_id, die im Bereich Identification auf der Seite API-Schlüssel zu finden ist. Achten Sie darauf, die korrekte app_id der jeweiligen Plattform zu verwenden.

Wichtig

Es ist nicht möglich, Web-Push-Token über die API zu migrieren. Der Grund dafür ist, dass Web-Push-Token nicht dem gleichen Schema wie andere Plattformen entsprechen.

Wenn Sie versuchen, Web-Push-Token programmatisch zu migrieren, erhalten Sie möglicherweise einen Fehler wie den folgenden: 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 nicht am Push-Token gesetzt. Braze geht davon aus, dass über die API importierte Token gültige Vordergrund-Push-Token sind, kann jedoch nicht bestimmen, zu welcher APNs-Umgebung das Token gehört.

Ohne das Gateway-Feld verwendet Braze beim Versenden 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. Beispielsweise 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 für Testumgebungen, dass sowohl Ihre App-Konfiguration als auch die importierten Token die Entwicklungsumgebung verwenden.

Hinweis

Token, die über das Braze SDK registriert werden, enthalten das Gateway-Feld automatisch, 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 benötigen diese Schritte nicht, da diese Plattform nur ein Framework zur Anzeige von Push hat und Push-Benachrichtigungen sofort dargestellt werden, solange Braze über die erforderlichen Push-Token und Zertifikate verfügt.

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

Sie benötigen einen Empfänger, der Push-Payloads verarbeitet und anzeigt. Um den Empfänger über den Push-Payload zu informieren, fügen Sie die erforderlichen Schlüssel-Wert-Paare zur Push-Campaign 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 von Nachrichten ausgeschlossen werden?

Braze stellt im Dashboard keine eigene Spamliste bereit. Braze blockiert einzelne Nutzerprofile („Dummy-Nutzer:innen“) mit mehr als fünf Millionen Sitzungen, mehr als 20.000 unterschiedlichen angepassten Event-Namen oder mehr als 20.000 unterschiedlichen Produktnamen in Käufen und stoppt die Aufnahme aller eingehenden Daten für dieses Profil – sowohl über die SDKs als auch über die REST API. Wenn ein Bezeichner blockiert ist, gibt /users/track möglicherweise den Fehler "provided external_id is blacklisted and disallowed" zurück. Dieser Wortlaut stammt wortwörtlich aus der API-Antwort. Um Profile zu finden, die wegen übermäßiger Sitzungen blockiert wurden, erstellen Sie ein Segment mit dem Filter Session Count, der auf more than 5,000,000 eingestellt 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 unterschiedliche 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.