Nutzer:innen identifizieren

Verwenden Sie diesen Endpunkt, um nicht identifizierte Nutzer:innen (nur Alias, nur E-Mail oder nur Telefonnummer) anhand der angegebenen externen ID zu identifizieren.

Funktionsweise

Der Aufruf von /users/identify kombiniert ein Nutzerprofil, das durch einen Alias (Nur-Alias-Profil), eine E-Mail-Adresse (Nur-E-Mail-Profil) oder eine Telefonnummer (Nur-Telefonnummer-Profil) identifiziert wird, mit einem Nutzerprofil, das über eine external_id (identifiziertes Profil) verfügt, und entfernt dann das Nur-Alias-Profil.

Die Identifizierung von Nutzer:innen erfordert eine external_id in den folgenden Objekten:

• aliases_to_identify
• emails_to_identify
• phone_numbers_to_identify

Wenn keine Nutzer:in mit dieser external_id vorhanden ist, wird die external_id zum Datensatz der Alias-Nutzer:in hinzugefügt, und die Nutzer:in gilt als identifiziert. Nutzer:innen können nur einen Alias für ein bestimmtes Label haben. Wenn bereits eine Nutzer:in mit der external_id existiert und einen bestehenden Alias mit dem gleichen Label wie das Nur-Alias-Profil hat, werden die Nutzerprofile nicht zusammengeführt.

Tipp

Um unerwartete Datenverluste bei der Identifizierung von Nutzer:innen zu vermeiden, empfehlen wir Ihnen dringend, zunächst die Best Practices für die Datenerfassung zu lesen, um zu erfahren, wie Sie Nutzerdaten erfassen können, wenn bereits Nur-Alias-Nutzerinformationen vorhanden sind.

Verhalten bei der Zusammenführung

Standardmäßig führt dieser Endpunkt die folgenden Felder, die ausschließlich bei anonymen Nutzer:innen vorhanden sind, mit denen der identifizierten Nutzer:in zusammen.

Voraussetzungen

Um diesen Endpunkt zu verwenden, benötigen Sie einen API-Schlüssel mit der Berechtigung users.identify.

Rate-Limit

Wir wenden ein gemeinsames Rate-Limit von 20.000 Anfragen pro Minute auf diesen Endpunkt an. Dieses Rate-Limit wird mit den Endpunkten /users/delete, /users/alias/new, /users/merge und /users/alias/update geteilt, wie in API-Rate-Limits dokumentiert.

Anfragetext

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
{
   "aliases_to_identify" : (required, array of alias to identify objects),
   "emails_to_identify": (optional, array of alias to identify objects) User emails to identify,
   "phone_numbers_to_identify": (optional, array of alias to identify objects) User phone numbers to identify,
},

Anfrageparameter

Sie können pro Anfrage bis zu 50 Nutzer-Aliase hinzufügen. Sie können mehrere zusätzliche Nutzer-Aliase mit einer einzigen external_id verknüpfen.

Wichtig

Eine der folgenden Angaben ist pro Anfrage erforderlich: aliases_to_identify, emails_to_identify oder phone_numbers_to_identify. Sie können diesen Endpunkt zum Beispiel verwenden, um Nutzer:innen per E-Mail zu identifizieren, indem Sie emails_to_identify in Ihrer Anfrage verwenden.

Identifizierung von Nutzer:innen anhand von E-Mail-Adressen und Telefonnummern

Wenn eine E-Mail-Adresse oder Telefonnummer als Bezeichner angegeben wird, müssen Sie auch prioritization im Bezeichner angeben.

prioritization muss ein Array sein, das angibt, welche Nutzer:in zusammengeführt werden soll, wenn mehrere Nutzer:innen gefunden werden. prioritization ist ein geordnetes Array – wenn also mehr als eine Nutzer:in aus einer Priorisierung übereinstimmt, findet keine Zusammenführung statt.

Die zulässigen Werte für das Array sind:

• identified
• unidentified
• most_recently_updated (bezieht sich auf die Priorisierung der zuletzt aktualisierten Nutzer:in)
• least_recently_updated (bezieht sich auf die Priorisierung der am längsten nicht aktualisierten Nutzer:in)

Es kann jeweils nur eine der folgenden Optionen im Priorisierungs-Array vorhanden sein:

• identified bezieht sich auf die Priorisierung einer Nutzer:in mit einer external_id
• unidentified bezieht sich auf die Priorisierung einer Nutzer:in ohne eine external_id

Hinweis

Eine Zusammenführung findet nicht statt, wenn die E-Mail-Adresse oder Telefonnummer mit mehreren Nutzer:innen übereinstimmt. Dies schließt Fälle ein, in denen eine dieser Nutzer:innen die gleiche external_id hat wie die in der Anfrage angegebene. In diesen Fällen gibt der Endpunkt "message": "success" zurück, aber die Nutzerprofile werden nicht zusammengeführt. Um dies zu vermeiden, stellen Sie sicher, dass die E-Mail-Adresse oder Telefonnummer nur mit nicht identifizierten Nutzer:innen verknüpft ist, bevor Sie diesen Endpunkt aufrufen.

Beispiel für eine Anfrage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
curl --location --request POST 'https://rest.iad-01.braze.com/users/identify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "aliases_to_identify": [
    {
      "external_id": "external_identifier",
      "user_alias": {
          "alias_name": "example_alias",
          "alias_label": "example_label"
      }
    }
  ],
  "emails_to_identify": [
    {
      "external_id": "external_identifier_2",
      "email": "[email protected]",
      "prioritization": ["unidentified", "most_recently_updated"]
    }
  ]
}'

Groß-/Kleinschreibung

Das Feld alias_name unterscheidet zwischen Groß- und Kleinschreibung. Eine Anfrage, die einen 201-Statuscode zurückgibt, bestätigt nur, dass die Anfrage-Syntax gültig war – sie bestätigt nicht, dass der Alias zugeordnet wurde. Wenn die Groß-/Kleinschreibung von alias_name in Ihrer Anfrage nicht exakt mit dem im Nutzerprofil gespeicherten Alias übereinstimmt, schlägt der Vorgang stillschweigend fehl und die external_id wird nicht zugewiesen. Wenn der gespeicherte Alias beispielsweise [email protected] lautet, gibt eine Anfrage mit [email protected] zwar Erfolg zurück, erzeugt aber kein Ergebnis.

Tipp

Weitere Informationen zu alias_name und alias_label finden Sie in unserer Dokumentation zu Nutzer-Aliase.

Antwort

1
2
3
4
{
    "aliases_processed": 1,
    "message": "success"
}