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" : "Jon",
  "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 die Schlüssel add und remove (ohne $).

Für Objekt-Arrays (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 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, während der Rest des Array-Zustands erhalten bleibt. Vollständige Anfragebeispiele finden Sie unter Objekt-Array – API-Beispiel und Objekt-Array – 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.

Bezeichner-Auflösung

Sofern Sie keinen anonymen Push-Token-Import durchführen, muss jedes Nutzer:innen-Attribute-Objekt mindestens einen Bezeichner enthalten: external_id, user_alias, braze_id, email oder phone. Fügen Sie nach Möglichkeit nur einen Bezeichner pro Objekt hinzu, um Unklarheiten darüber zu vermeiden, 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 in dasselbe Nutzer:innen-Attribute-Objekt aufgenommen werden, wird ein Fehler zurückgegeben. Um einer Nutzer:in, die bereits über eine external_id verfügt, 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 Nutzer:innen-Attribute-Objekt. Die Angabe mehrerer Bezeichner, die auf unterschiedliche Nutzerprofile verweisen, kann dazu führen, dass Attribute auf das falsche Profil angewendet 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 Hauptteil Ihrer Anfrage übergeben. Wenn dieser Wert weggelassen wird, erstellt Braze ein neues Nutzerprofil, sofern die external_id noch nicht vorhanden ist.

Hinweis

Wenn Sie ein Nutzerprofil nur mit Alias über den /users/track-Endpunkt erstellen, müssen Sie _update_existing_only auf false setzen. Wenn Sie diesen Wert weglassen, erstellt Braze kein Profil, das nur aus einem Alias besteht.

Push-Token-Import

Bevor Sie Push-Tokens nach Braze importieren, überprüfen Sie, ob dies wirklich erforderlich ist. Wenn die Braze SDKs eingerichtet sind, verarbeiten sie Push-Tokens automatisch, ohne dass sie über die API hochgeladen werden müssen.

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

Hinweis

Beim Importieren von Push-Tokens aus anderen Systemen ist nicht immer eine external_id verfügbar. Um die Kommunikation mit diesen Nutzer:innen während der Umstellung auf Braze aufrechtzuerhalten, können Sie die Legacy-Tokens für anonyme Nutzer:innen importieren, ohne external_id anzugeben, indem Sie push_token_import als true angeben.

Wenn Sie push_token_import als true angeben:

• external_id und braze_id sollten nicht angegeben werden
• Das Attribut-Objekt muss ein Push-Token enthalten
• Wenn das Token bereits in Braze vorhanden ist, 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 automatisch das importierte Push-Token in das Braze-Nutzerprofil, sobald die jeweilige Nutzer:in die Braze-fähige Version Ihrer App startet, und bereinigt das temporäre Profil.

Braze überprüft einmal im Monat, ob es anonyme Profile mit dem push_token_import-Flag gibt, die keinen Push-Token haben. Wenn das anonyme Profil keinen Push-Token mehr aufweist, wird das Profil von Braze gelöscht. Wenn das anonyme Profil jedoch weiterhin über einen Push-Token verfügt – was darauf hindeutet, dass sich die tatsächliche Nutzer:in noch nicht mit diesem Push-Token beim Gerät angemeldet hat –, unternimmt Braze keine Maßnahmen.

Weitere Informationen finden Sie unter Migration von Push-Tokens.

Angepasste Attribut-Datentypen

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

Tipp

Informationen dazu, wann ein angepasstes Event und wann ein angepasstes Attribut verwendet werden sollte, finden Sie unter Angepasste Events und Angepasste Attribute.

Beispiel für ein Objekt-Array

Mit diesem Objekt-Array können Sie Segmente auf der Grundlage bestimmter Kriterien innerhalb der Aufenthalte erstellen und Ihre Nachrichten anhand der Daten der einzelnen Aufenthalte mit Liquid-Templates 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 }
]}

Für Objekt-Array-Beispiele, die $add, $remove und $update verwenden, siehe Objekt-Array – API-Beispiel und Objekt-Array – SDK-Beispiel.

Braze-Nutzerprofilfelder

Wichtig

Bei den folgenden Nutzerprofilfeldern wird zwischen Groß- und Kleinschreibung unterschieden. Achten Sie daher darauf, diese Felder in Kleinbuchstaben zu referenzieren.

Tipp

Eine kund:innenorientierte Referenz der Standardattribute, die nach Kategorien geordnet ist und Hinweise für SDK, API, CSV und Cloud-Datenaufnahme enthält, finden Sie unter Standardattribute.

Sprachwerte, die explizit über diese API festgelegt werden, haben Vorrang vor den Gebietsschemainformationen, die Braze automatisch vom Gerät erhält.

Beispiel für eine Nutzer:innen-Attribut-Anfrage

Dieses Beispiel enthält vier Nutzer:innen-Attribute-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" : "Jon",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Jill",
      "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" : "Alice",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

Migration von Push-Tokens

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

Automatische Migration über SDK

Nach der Integration des Braze SDK werden die Push-Tokens für Ihre Opt-in-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-Tokens auch manuell migrieren, was eine schnellere erneute Interaktion mit Ihren Nutzer:innen ermöglicht.

Überlegungen zu Web-Tokens

Aufgrund der Natur von Web-Push-Tokens sollten Sie bei der Implementierung von Push für das Web Folgendes beachten:

Manuelle Migration über API

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

Migrieren Sie iOS- (APNs) und Android- (FCM) Tokens programmatisch auf Ihre Plattform mithilfe des users/track-Endpunkts. 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 während der Push-Token-Migration die app_id Ihrer App an, um das entsprechende Push-Token mit der entsprechenden App zu verknüpfen. Jede App (iOS, Android usw.) hat ihre eigene app_id, die Sie im Abschnitt Identification auf der Seite API-Schlüssel finden. Achten Sie darauf, dass Sie die richtige app_id der jeweiligen Plattform verwenden.

Wichtig

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

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

Als Alternative zur API-Migration empfehlen wir Ihnen, das SDK zu integrieren und Ihre Token-Basis auf natürliche Weise neu aufbauen zu lassen.

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

Importieren von iOS-Push-Tokens

Beim Migrieren von iOS-Push-Tokens mit /users/track wird das Feld gateway nicht auf dem Push-Token gesetzt. Braze geht davon aus, dass über die API importierte Tokens gültige Vordergrund-Push-Tokens 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-Umgebung 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 Tokens übereinstimmt, die Sie importieren.
• Importieren Sie für Produktions-Apps nur Produktions-Tokens.
• Überprüfen Sie bei Testumgebungen, dass sowohl Ihre App-Konfiguration als auch die importierten Tokens die Entwicklungsumgebung verwenden.

Hinweis

Tokens, die über das Braze SDK registriert werden, enthalten das Gateway-Feld automatisch, da das SDK die Umgebung anhand der Berechtigungen Ihrer App erkennt.

Importieren von Android-Push-Tokens

Wichtig

Die folgenden Überlegungen gelten nur für Android-Apps. iOS-Apps erfordern diese Schritte nicht, da diese Plattform nur über ein Framework für die Anzeige von Push-Benachrichtigungen verfügt und Push-Benachrichtigungen sofort gerendert werden, solange Braze über die erforderlichen Push-Tokens 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, um Push-Benachrichtigungen zu validieren.

Sie müssen über einen Empfänger verfügen, der Push-Payloads verarbeiten und anzeigen kann. Um den Empfänger über den 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 Push-Partner ab, den Sie vor Braze verwendet haben.

Hinweis

Bei einigen Anbietern von Push-Benachrichtigungen 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 bitte an Ihren Customer-Success-Manager.