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-Aktualisierungen mit $new_object.

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 mit dieser E-Mail-Adresse verknüpfte Nutzerprofil angewendet werden, auch 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 Body Ihrer Anfrage übergeben. Wird dieser Wert weggelassen, erstellt Braze ein neues Nutzerprofil, falls die external_id noch nicht existiert.

Hinweis

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

Push-Token-Import

Bevor Sie Push-Token in Braze importieren, prüfen Sie, ob dies tatsächlich erforderlich ist. Wenn die Braze SDKs eingebunden sind, verwalten sie Push-Token automatisch, ohne dass ein Upload über die API nötig ist.

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 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 diese Personen weiterhin kontaktieren können

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

Braze prüft einmal im Monat, ob anonyme Profile mit dem Flag push_token_import vorhanden sind, die kein Push-Token mehr haben. 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 die tatsächliche Person noch nicht auf dem Gerät mit dem betreffenden Push-Token angemeldet hat – 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 im Vergleich zu 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 mithilfe der Daten aus jedem Aufenthalt 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 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 sind case-sensitiv. 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 vor der Integration von Braze bereits Push-Benachrichtigungen versendet haben – entweder eigenständig oder über einen anderen Anbieter –, können Sie mit der Push-Token-Migration weiterhin Push-Benachrichtigungen an Ihre Nutzer:innen mit registrierten Push-Token senden.

Automatische Migration über das SDK

Nachdem Sie das Braze SDK integriert haben, werden Push-Token für Ihre Nutzer:innen mit Opt-in 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 wieder zu erreichen.

Überlegungen zu Web-Token

Aufgrund der Besonderheiten 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 zugeordneten 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 richtigen App zuzuordnen. Jede App (iOS, Android usw.) hat eine eigene app_id, die im Abschnitt Identifikation auf der Seite API-Schlüssel zu finden ist. Stellen Sie sicher, dass Sie die app_id der richtigen Plattform verwenden.

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, 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 fehlt

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 bestimmen, zu welcher APNs-Umgebung das Token gehört.

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

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 das Gateway-Feld automatisch, da das SDK die Umgebung aus den Berechtigungen Ihrer App erkennt.

Android-Push-Token importieren

Wichtig

Die folgende Überlegung gilt nur für Android-Apps. iOS-Apps erfordern 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 Braze-SDK-Integration abgeschlossen ist, verwenden Sie Schlüssel-Wert-Paare zur Validierung von Push-Benachrichtigungen.

Sie benötigen einen Receiver, der Push-Payloads verarbeitet und anzeigt. Um den Receiver über das 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 vom Messaging ausgeschlossen wurden?

Braze stellt im Dashboard keine dedizierte Spam-Liste bereit. Braze blockiert einzelne Nutzerprofile („Dummy-Nutzer:innen“) mit mehr als fünf Millionen Sessions, 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 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 wegen übermäßiger Sessions blockiert wurden, erstellen Sie ein Segment mit dem Filter Session Count, der auf mehr als 5.000.000 eingestellt ist, exportieren Sie das Segment als CSV und gleichen Sie die Profilfelder unter Engagement > Nutzer:innen suchen oder mit dem Endpunkt /users/export/ids ab. Für unterschiedliche angepasste Event-Namen oder Produktnamen gibt es keinen entsprechenden Filter. 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.