Nutzer:innen-Attribute-Objekt

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

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

Body des Objekts

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

Hinweis

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

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

Verwenden Sie dieses Format, wenn Sie Objekte innerhalb eines bestehenden Arrays anhängen, entfernen oder aktualisieren möchten, ohne den restlichen Zustand des Arrays zu verändern. Vollständige Anfragebeispiele finden Sie unter API-Beispiel für ein Array von Objekten und SDK-Beispiel für ein Array von Objekten.

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.

Auflösung von Bezeichnern

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. Geben Sie nach Möglichkeit nur einen Bezeichner pro Objekt an, damit eindeutig ist, welches Nutzerprofil aktualisiert oder erstellt wird.

Beachten Sie bei der Verwendung von Bezeichnern Folgendes:

• external_id und user_alias schließen sich gegenseitig aus. Wenn beide im selben Nutzerattribut-Objekt enthalten sind, wird ein Fehler zurückgegeben. Um Nutzer:innen, die bereits eine external_id haben, einen Alias hinzuzufügen, verwenden Sie den Endpunkt /users/alias/new.
• email hat Vorrang vor phone. Wenn sowohl email als auch phone im selben Objekt enthalten sind, verwendet Braze email als Bezeichner. Die Attribute werden also auf das Nutzerprofil angewendet, 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 einzigen Bezeichner pro Nutzerattribut-Objekt. Wenn Sie mehrere Bezeichner angeben, die auf unterschiedliche Nutzerprofile verweisen, können Attribute auf das falsche Profil angewendet werden.

Nur bestehende Profile aktualisieren

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

Hinweis

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

Push-Token-Import

Bevor Sie Push-Token in Braze importieren, prüfen Sie, ob dies überhaupt nötig ist. Sobald die Braze SDKs implementiert sind, verarbeiten sie Push-Token automatisch, sodass ein Upload über die API nicht erforderlich ist.

Falls Sie die Token doch über die API hochladen müssen, können Sie dies entweder für identifizierte oder für anonyme Nutzer:innen tun. Es muss also entweder eine external_id vorhanden sein, oder bei anonymen Nutzer:innen muss das Flag push_token_import auf true gesetzt sein.

Hinweis

Beim Import von Push-Token aus anderen Systemen ist nicht immer eine external_id verfügbar. Um während Ihrer Umstellung auf Braze weiterhin mit diesen Nutzer:innen kommunizieren zu können, können Sie die bisherigen Token für anonyme Nutzer:innen ohne Angabe einer external_id importieren, indem Sie push_token_import auf true setzen.

Wenn Sie push_token_import auf true setzen:

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

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

Braze prüft einmal im Monat, ob es anonyme Profile mit dem Flag push_token_import gibt, die kein Push-Token haben. Hat ein anonymes Profil kein Push-Token mehr, löscht Braze das Profil. Besitzt das anonyme Profil dagegen noch ein Push-Token – was darauf hindeutet, dass sich die tatsächliche Person noch nicht auf dem Gerät mit diesem Push-Token angemeldet hat –, unternimmt Braze nichts.

Weitere Informationen finden Sie unter Migration von Push-Token.

Datentypen für angepasste Attribute

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

Tipp

Hinweise dazu, wann Sie ein angepasstes Event und wann ein angepasstes Attribut verwenden sollten, finden Sie unter Angepasste Events und Angepasste Attribute.

Beispiel für ein Array von Objekten

Mit diesem Array von Objekten können Sie Segmente auf Basis bestimmter Kriterien innerhalb der Aufenthalte erstellen und Ihre Nachrichten mit Liquid-Templates anhand der Daten jedes einzelnen Aufenthalts 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 API-Beispiel für ein Array von Objekten und SDK-Beispiel für ein Array von Objekten.

Braze-Nutzerprofilfelder

Wichtig

Bei den folgenden Nutzerprofilfeldern wird zwischen Groß- und Kleinschreibung unterschieden. Referenzieren Sie diese Felder daher unbedingt in Kleinbuchstaben.

Tipp

Eine kundenorientierte, nach Kategorien geordnete Referenz der Standardattribute mit Hinweisen zu 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.

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 selbst 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 die Push-Token Ihrer 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.

Hinweise 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

Bei der manuellen Push-Token-Migration importieren Sie diese zuvor erstellten Schlüssel über die API in Ihre Braze-Plattform.

Migrieren Sie iOS-Token (APNs) und Android-Token (FCM) programmatisch auf Ihre Plattform, indem Sie den Endpunkt users/track 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.

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 jeweilige Push-Token mit der richtigen App zu verknüpfen. Jede App (iOS, Android usw.) hat ihre eigene app_id, die Sie im Abschnitt Identifizierung auf der Seite API-Schlüssel finden. Achten Sie darauf, die app_id der richtigen Plattform zu verwenden.

Wichtig

Web-Push-Token können nicht über die API migriert werden, da sie 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 Ihren Token-Bestand 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

Bei der Migration von iOS-Push-Token mit /users/track wird das Feld gateway für das Push-Token nicht gesetzt. Braze geht davon aus, dass über die API importierte Token gültige Vordergrund-Push-Token sind, kann aber nicht bestimmen, zu welcher APNs-Umgebung das Token gehört.

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

So vermeiden Sie Probleme bei der Zustellung:

• Stellen Sie sicher, dass die Umgebungseinstellung Ihrer App im Braze-Dashboard mit den importierten Token übereinstimmt.
• 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

Über das Braze SDK registrierte Token enthalten das Gateway-Feld automatisch, da das SDK die Umgebung anhand der Entitlements 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 für die Anzeige von Push-Benachrichtigungen hat und Push-Benachrichtigungen sofort angezeigt 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, um Push-Benachrichtigungen zu validieren.

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

Hinweis

Bei einigen Anbietern von Push-Benachrichtigungen muss Braze die Schlüssel-Wert-Paare vereinfachen (flatten), damit sie korrekt interpretiert werden können. Wenden Sie sich an Ihren Customer-Success-Manager, um Schlüssel-Wert-Paare für eine bestimmte Android-App zu vereinfachen.

Häufig gestellte Fragen

Wie finde ich Nutzer:innen, die als Spam eingestuft oder für Messaging blockiert wurden?

Braze stellt im Dashboard keine eigene Spam-Liste bereit. Braze blockiert einzelne Nutzerprofile („Dummy-Nutzer:innen“) mit mehr als fünf Millionen Sitzungen, mehr als 20.000 unterschiedlichen Namen für angepasste Events oder mehr als 20.000 unterschiedlichen Produktnamen bei Käufen. Für ein solches Profil nimmt Braze keine eingehenden Daten mehr auf, weder über die SDKs noch ü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 unverändert aus der API-Antwort. Um Profile zu finden, die wegen zu vieler Sitzungen blockiert wurden, erstellen Sie ein Segment mit dem Filter Session Count, der auf more than 5,000,000 gesetzt ist. Exportieren Sie das Segment anschließend als CSV und gleichen Sie die Profilfelder unter Engagement > Search users oder über den Endpunkt /users/export/ids ab. Für unterschiedliche Namen angepasster Events 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.