Identifier les utilisateurs
/users/identify
Utilisez cet endpoint pour identifier un utilisateur non identifié (alias uniquement, e-mail uniquement ou numéro de téléphone uniquement) à l’aide de l’ID externe fourni.
Fonctionnement
L’appel à /users/identify
combine un profil utilisateur identifié par un alias (profil alias seul), une adresse e-mail (profil e-mail seul) ou un numéro de téléphone (profil numéro de téléphone seul) avec un profil utilisateur possédant un external_id
(profil identifié), puis supprime le profil alias seul.
L’identification d’un utilisateur nécessite qu’un external_id
soit inclus dans l’objet aliases_to_identify
ou emails_to_identify
ou phone_numbers_to_identify
. S’il n’existe pas d’utilisateur possédant cette adresse external_id
, l’adresse external_id
sera ajoutée à l’enregistrement de l’utilisateur aliasé et l’utilisateur sera considéré comme identifié.
Notez ce qui suit :
- Lorsque ces associations ultérieures sont effectuées avec le champ
merge_behavior
défini surnone
, seuls les jetons de notification push et l’historique des messages associés à l’alias d’utilisateur sont conservés. Tous les attributs, événements ou achats deviendront « orphelins » et non disponibles pour l’utilisateur identifié. Une solution consiste à exporter les données de l’utilisateur aliasé avant l’identification à l’aide de l’ endpoint/users/export/ids
, puis à réassocier les attributs, les événements et les achats à l’utilisateur identifié. - Lorsque des associations sont faites avec le champ
merge_behavior
défini surmerge
, cet endpoint fusionnera les champs spécifiques trouvés sur l’utilisateur anonyme avec ceux de l’utilisateur identifié. - Les utilisateurs ne peuvent avoir qu’un seul alias pour un libellé donné. Si un utilisateur existe déjà sur le site
external_id
et qu’il dispose d’un alias existant avec le même libellé que le profil alias uniquement, les profils utilisateurs ne seront pas combinés.
Pour éviter toute perte inattendue de données lors de l’identification des utilisateurs, nous vous recommandons vivement de vous reporter d’abord aux meilleures pratiques en matière de collecte de données pour savoir comment capturer les données des utilisateurs lorsque des informations sur les utilisateurs sous forme d’alias seulement sont déjà présentes.
Conditions préalables
Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation users.identify
.
Limite de débit
We apply a shared rate limit of 20,000 requests per minute to this endpoint. This rate limit is shared with the /users/delete
, /users/alias/new
, /users/merge
, and /users/alias/update
endpoints, as documented in API rate limits.
Corps de la demande
1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
5
6
{
"aliases_to_identify" : (required, array of alias to identify objects),
"emails_to_identify": (optional, array of string) User emails to identify,
"phone_numbers_to_identify": (optional, array of string) User phone numbers to identify,
"merge_behavior": (optional, string) one of 'none' or 'merge' is expected
}
Paramètres de demande
Vous pouvez ajouter jusqu’à 50 alias utilisateur par demande. Vous pouvez associer plusieurs alias utilisateur supplémentaires à un seul external_id
.
Paramètre | Requis | Type de données | Description |
---|---|---|---|
aliases_to_identify |
Requis | Tableau d’alias pour identifier l’objet | Voir alias pour identifier l’objet et alias d’utilisateur. |
emails_to_identify |
Requis | Tableau d’alias pour identifier l’objet | Adresses e-mail pour identifier les utilisateurs. Voir Identification des utilisateurs par e-mail. |
phone_numbers_to_identify |
Requis | Tableau d’alias pour identifier l’objet | Numéros de téléphone pour identifier les utilisateurs. |
merge_behavior |
Facultatif | Chaîne de caractères | none ou merge est attendu. |
Champ Merge_behavior
En attribuant la valeur merge
au champ merge_behavior
, l’endpoint fusionne avec l’utilisateur anonyme la liste suivante de champs trouvés exclusivement sur l’utilisateur identifié. Configurer le champ sur none
ne fusionnera aucune donnée utilisateur avec le profil utilisateur identifié. Par défaut, ce champ est défini sur merge
.
Liste des champs qui sont fusionnés
- Prénom
- Nom
- Genre
- Date de naissance
- Numéro de téléphone
- Fuseau horaire
- Ville d’origine
- Pays
- Langue
- Décompte des sessions (la somme des sessions des deux profils)
- Date de la première session (Braze choisira la date la plus ancienne parmi les deux)
- Date de la dernière session (Braze choisira la date la plus récente parmi les deux)
- Attributs personnalisés
- Données d’événements personnalisés et d’événements d’achat
- Propriétés de l’événement d’achat et personnalisées pour la segmentation « X fois en Y jours » (où X <= 50 et Y <= 30)
- Résumé des événements personnalisés pouvant être segmentés
- Nombre d’événements (la somme des deux profils)
- Événement survenu pour la première fois (Braze choisira la date la plus ancienne parmi les deux)
- Événement survenu pour la dernière fois (Braze choisira la date la plus récente parmi les deux)
- Total des achats intégrés à l’application en centimes (la somme des deux profils)
- Nombre total d’achats (la somme des deux profils)
- Date du premier achat (Braze choisira la date la plus ancienne parmi les deux)
- Date du dernier achat (Braze choisira la date la plus récente parmi les deux)
- Résumés des applications
- Champs Last_X_at (Braze mettra à jour les champs si les champs du profil orphelins sont plus récents).
- Résumés de campagne (Braze choisira les champs de date les plus récents)
- Résumés du flux de travail (Braze choisira les champs de date les plus récents)
- Message et historique d’engagement du message
- Nombre d’événements d’achats et personnalisés, ainsi que les horodatages correspondant à la première et dernière dates
- Ces champs fusionnés mettront à jour les filtres « pour X événements en Y jours ». Pour les événements d’achat, ces filtres incluent « nombre d’achats en Y jours » et « argent dépensé au cours des Y derniers jours ».
- Données de session si l’application existe sur les deux profils utilisateurs.
- Par exemple, si votre utilisateur cible ne dispose pas d’un résumé d’application pour « ABCApp », mais que votre utilisateur d’origine l’a, l’utilisateur cible disposera du résumé d’application pour « ABCApp » sur son profil après la fusion.
Identifier les utilisateurs par e-mail
Si un email
est spécifié comme identifiant, vous devez également inclure prioritization
dans l’identifiant. prioritization
doit être un tableau spécifiant l’utilisateur à fusionner si plusieurs utilisateurs ont été trouvés. prioritization
est un tableau ordonné, ce qui signifie que si plus d’un utilisateur correspond à un ordre de priorité, la fusion n’aura pas lieu.
Les valeurs autorisées pour le tableau sont les suivantes :
identified
unidentified
most_recently_updated
(priorité à l’utilisateur le plus récemment mis à jour)least_recently_updated
(Priorité à l’utilisateur le moins récemment mis à jour)
Une seule des options suivantes peut exister à la fois dans le tableau de priorisation :
identified
Il s’agit de donner la priorité à un utilisateur ayant uneexternal_id
unidentified
Il s’agit de donner la priorité à un utilisateur qui n’a pas deexternal_id
Si vous indiquez identified
dans le tableau, cela signifie que l’utilisateur doit avoir un external_id
pour être inscrit dans le Canvas. Si vous souhaitez que les utilisateurs disposant d’une adresse e-mail entrent dans le message, qu’ils soient identifiés ou non, utilisez plutôt le paramètre most_recently_updated
ou least_recently_updated
.
Exemple de demande
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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"]
}
]
"merge_behavior": "merge"
}'
Pour plus d’informations sur alias_name
et alias_label
, consultez notre documentation sur les alias utilisateurs.
Réponse
1
2
3
4
5
6
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
"aliases_processed": 1,
"message": "success"
}