Nutzer:innen zusammenführen

Verwenden Sie diesen Endpunkt, um eine Nutzer:in mit einer anderen Nutzer:in zusammenzuführen.

Pro Anfrage können bis zu 50 Zusammenführungen angegeben werden. Dieser Endpunkt ist asynchron.

Voraussetzungen

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

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/identify 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
{
  "merge_updates" : (required, array of objects)
}

Anfrageparameter

Zusammenführungsverhalten

Das unten dokumentierte Verhalten gilt für alle Braze-Features, die nicht von Snowflake unterstützt werden. Zusammenführungen von Nutzer:innen werden auf dem Tab Messaging-Verlauf, in Segmenterweiterungen, im Abfrage-Builder und in Currents nicht widergespiegelt.

Wichtig

Der Endpunkt garantiert nicht die Reihenfolge, in der merge_updates-Objekte aktualisiert werden.

Dieser Endpunkt führt die folgenden Felder zusammen, wenn sie bei der Zielnutzer:in nicht gefunden werden.

• Vorname
• Nachname
• E-Mail-Adressen (es sei denn, sie sind verschlüsselt)
• Geschlecht
• Geburtsdatum
• Telefonnummer
• Zeitzone
• Wohnort
• Land
• Sprache
• Geräteinformationen
• Anzahl der Sitzungen (die Summe der Sitzungen aus beiden Profilen)
• Datum der ersten Sitzung (Braze wählt das frühere der beiden Daten)
• Datum der letzten Sitzung (Braze wählt das spätere der beiden Daten)
• Angepasste Attribute (Braze behält vorhandene angepasste Attribute im Zielprofil bei und fügt angepasste Attribute hinzu, die im Zielprofil nicht vorhanden waren)
• Angepasste Event- und Kauf-Event-Daten
• Angepasste Event- und Kauf-Event-Eigenschaften für die Segmentierung „X-mal in Y Tagen“ (wobei X<=50 und Y<=30)
• Segmentierbare Zusammenfassung angepasster Events
  • Event-Anzahl (die Summe aus beiden Profilen)
  • Event erstmals aufgetreten (Braze wählt das frühere der beiden Daten)
  • Event zuletzt aufgetreten (Braze wählt das spätere der beiden Daten)
• In-App-Käufe insgesamt in Cent (die Summe aus beiden Profilen)
• Gesamtzahl der Käufe (die Summe aus beiden Profilen)
• Datum des ersten Kaufs (Braze wählt das frühere der beiden Daten)
• Datum des letzten Kaufs (Braze wählt das spätere der beiden Daten)
• App-Zusammenfassungen
• Last_X_at-Felder (Braze aktualisiert die Felder, wenn die verwaisten Profilfelder aktueller sind)
• Campaign-Interaktionsdaten (Braze wählt die aktuellsten Datumsfelder)
• Workflow-Zusammenfassungen (Braze wählt die aktuellsten Datumsfelder)
• Nachrichten- und Nachrichten-Engagement-Verlauf
• Braze führt Sitzungsdaten nur zusammen, wenn die App in beiden Nutzerprofilen vorhanden ist.

Hinweis

Bei der Zusammenführung von Nutzer:innen funktioniert die Verwendung des Endpunkts /users/merge genauso wie die Verwendung der changeUser()-Methode.

Braze behandelt drei Nutzertypen bei der Zusammenführung unterschiedlich: zur Löschung markierte Nutzer:innen, Testnutzer:innen und Nutzer:innen der globalen Kontrollgruppe. Weitere Details finden Sie unter Verhalten bei der Zusammenführung von Nutzer:innen.

Verhalten bei angepasstem Event-Datum und Kauf-Event-Datum

Diese zusammengeführten Felder aktualisieren die Filter „für X Events in Y Tagen“. Bei Kauf-Events umfassen diese Filter „Anzahl der Käufe in Y Tagen“ und „Geldausgaben in den letzten Y Tagen“.

Zusammenführung von Nutzer:innen per E-Mail oder Telefonnummer

Wenn email oder phone als Bezeichner angegeben wird, müssen Sie einen zusätzlichen prioritization-Wert im Bezeichner angeben. prioritization sollte ein geordnetes Array sein, das angibt, welche Nutzer:in zusammengeführt werden soll, wenn mehrere Nutzer:innen gefunden werden. Das bedeutet, dass bei mehreren übereinstimmenden Nutzer:innen aus einer Priorisierung keine Zusammenführung erfolgt.

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

Wichtig

Wenn beide Profile ungültige Telefonnummern haben, führt Braze sie nicht zusammen. Ungültige Nummern werden nicht im E.164-Format gespeichert, und der Zusammenführungsjob kombiniert diese Profile nicht. Der Endpunkt gibt dennoch 202 Accepted mit einer Erfolgsmeldung zurück, sodass die HTTP-Antwort nicht darauf hinweist, dass die Zusammenführung übersprungen wurde. Korrigieren Sie die Telefonnummern in einem oder beiden Profilen, bevor Sie die Zusammenführung durchführen.

Beispielanfragen

Einfache Anfrage

Dies ist ein einfacher Anfragetext, der das Muster der Anfrage zeigt.

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
31
32
33
34
35
36
37
38
39
curl --location --request POST 'https://rest.iad-01.braze.com/users/merge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "merge_updates": [
    {
      "identifier_to_merge": {
        "external_id": "old-user1"
      },
      "identifier_to_keep": {
        "external_id": "current-user1"
      }
    },
    {
      "identifier_to_merge": {
        "email": "[email protected]",
        "prioritization": ["unidentified", "most_recently_updated"]
      },
      "identifier_to_keep":  {
        "email": "[email protected]",
        "prioritization": ["identified", "most_recently_updated"]
      }
    },
    {
      "identifier_to_merge": {
        "user_alias": {
          "alias_name": "[email protected]",
          "alias_label": "email"
        }
      },
      "identifier_to_keep": {
        "user_alias": {
          "alias_name": "[email protected]",
          "alias_label": "email"
        }
      }
    }
  ]
}'

Zusammenführung einer nicht identifizierten Nutzer:in

Die folgende Anfrage würde die zuletzt aktualisierte nicht identifizierte Nutzer:in mit der E-Mail-Adresse [email protected] mit der Nutzer:in mit der externen ID john zusammenführen. In diesem Beispiel filtert most_recently_updated die Abfrage auf eine nicht identifizierte Nutzer:in. Wenn es also zwei nicht identifizierte Nutzer:innen mit dieser E-Mail-Adresse gäbe, würde nur eine mit der Nutzer:in zusammengeführt, die die externe ID john hat.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --location --request POST 'https://rest.iad-01.braze.com/users/merge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "merge_updates": [
    {
      "identifier_to_merge": {
        "email": "[email protected]",
        "prioritization": ["unidentified", "most_recently_updated"]
      },
      "identifier_to_keep": {
        "external_id": "john"
      }
    }
  ]
}'

Zusammenführung einer nicht identifizierten Nutzer:in in eine identifizierte Nutzer:in

Das folgende Beispiel führt die zuletzt aktualisierte nicht identifizierte Nutzer:in mit der E-Mail-Adresse [email protected] mit der zuletzt aktualisierten identifizierten Nutzer:in mit der E-Mail-Adresse [email protected] zusammen.

Die Verwendung von most_recently_updated filtert die Abfragen auf jeweils eine Nutzer:in (eine nicht identifizierte Nutzer:in für identifier_to_merge und eine identifizierte Nutzer:in für identifier_to_keep).

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/merge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "merge_updates": [
    {
      "identifier_to_merge": {
        "email": "[email protected]",
        "prioritization": ["unidentified", "most_recently_updated"]
      },
      "identifier_to_keep": {
        "email": "[email protected]",
        "prioritization": ["identified", "most_recently_updated"]
      }
    }
  ]
}'

Zusammenführung einer nicht identifizierten Nutzer:in ohne die most_recently_updated-Priorisierung

Wenn es zwei nicht identifizierte Nutzer:innen mit der E-Mail-Adresse [email protected] gibt, führt diese Beispielanfrage keine Nutzer:innen zusammen, da es zwei nicht identifizierte Nutzer:innen mit dieser E-Mail-Adresse gibt. Diese Anfrage funktioniert nur, wenn es lediglich eine nicht identifizierte Nutzer:in mit der E-Mail-Adresse [email protected] gibt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --location --request POST 'https://rest.iad-01.braze.com/users/merge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "merge_updates": [
    {
      "identifier_to_merge": {
        "email": "[email protected]",
        "prioritization": ["unidentified"]
      },
      "identifier_to_keep": {
        "external_id": "john"
      }
    }
  ]
}'

Antwort

Für diesen Endpunkt gibt es zwei Statuscode-Antworten: 202 und 400.

Beispiel für eine erfolgreiche Antwort

Der Statuscode 202 könnte den folgenden Antworttext zurückgeben.

1
2
3
{
  "message": "success"
}

Beispiel für eine Fehlerantwort

Der Statuscode 400 könnte den folgenden Antworttext zurückgeben. Weitere Informationen zu Fehlern, die auftreten können, finden Sie unter Fehlerbehebung.

1
2
3
{
  "message": "'merge_updates' must be an array of objects"
}

Fehlerbehebung

Eine erfolgreiche Antwort wurde zurückgegeben, aber die zusammengeführte Nutzer:in ist weiterhin auffindbar

Eine erfolgreiche Antwort bestätigt, dass die Anfrage akzeptiert wurde, aber der Zusammenführungsvorgang umfasst zwei Schritte: das Zusammenführen der Profile und anschließend das Entfernen des Quellprofils. Aus diesem Grund kann das identifier_to_merge-Profil nach einer erfolgreichen Antwort noch für kurze Zeit im Dashboard auffindbar sein. Dies ist erwartetes Verhalten – warten Sie einige Minuten und überprüfen Sie dann, ob die Zusammenführung abgeschlossen ist.

Wenn die zusammengeführte Nutzer:in nach mehreren Minuten noch existiert, überprüfen Sie, ob die Bezeichner in Ihrer Anfrage korrekt sind und zu Nutzer:innen im selben Workspace gehören wie der für die Anfrage verwendete API-Schlüssel.

Fehlerreferenz

Die folgende Tabelle listet mögliche Fehlermeldungen auf, die auftreten können.