Créer un nouvel alias utilisateur

Utilisez cet endpoint pour ajouter de nouveaux alias d’utilisateur pour les utilisateurs identifiés existants, ou pour créer de nouveaux utilisateurs non identifiés.

Vous pouvez spécifier jusqu’à 50 alias d’utilisateur par requête.

L’ajout d’un alias d’utilisateur pour un utilisateur existant nécessite qu’un external_id soit inclus dans le nouvel objet alias d’utilisateur. Si l’external_id est présent dans l’objet mais qu’aucun utilisateur ne possède cet external_id, l’alias ne sera ajouté à aucun utilisateur. En l’absence d’un external_id, un utilisateur sera tout de même créé, mais il devra être identifié ultérieurement. Vous pouvez le faire en utilisant la fonctionnalité « Identification des utilisateurs » et l’endpoint users/identify.

La création d’un nouvel utilisateur alias uniquement nécessite que l’external_id soit omis du nouvel objet alias d’utilisateur. Une fois l’utilisateur créé, utilisez l’endpoint /users/track pour associer l’utilisateur alias uniquement à des attributs, des événements et des achats, et l’endpoint /users/identify pour identifier l’utilisateur avec un external_id.

Lorsque alias_label et alias_name existent déjà

La combinaison de alias_label et alias_name doit être unique dans l’ensemble de votre base d’utilisateurs. Pour plus d’informations, consultez Alias d’utilisateur.

Si vous envoyez une requête dans laquelle la paire alias_label et alias_name existe déjà pour un utilisateur (que ce soit le même utilisateur ou un autre), l’endpoint renvoie tout de même une réponse de succès (par exemple, "aliases_processed": 1, "message": "success"). Dans ce cas, aucun nouvel alias n’est ajouté à l’utilisateur de la requête. Étant donné que la paire alias_label et alias_name est déjà utilisée, la requête n’effectue aucune modification, et il peut sembler que l’alias n’a jamais été ajouté à l’utilisateur en question.

Conditions préalables

Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation users.alias.new.

Limite de débit

Nous appliquons une limite de débit partagée de 20 000 requêtes par minute à cet endpoint. Cette limite de débit est partagée avec les endpoints /users/delete, /users/identify, /users/merge et /users/alias/update, comme documenté dans Limites de débit de l’API.

Corps de la requête

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

1
2
3
{
  "user_aliases" : (required, array of new user alias object)
}

Paramètres de requête

Corps de requête de l’endpoint avec spécification de l’objet nouvel alias d’utilisateur

1
2
3
4
5
{
  "external_id" : (optional, string),
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

Exemple de requête

1
2
3
4
5
6
7
8
9
10
11
12
curl --location --request POST 'https://rest.iad-01.braze.com/users/alias/new' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "user_aliases" :[
    {
      "external_id": "external_identifier",
      "alias_name" : "example_name",
      "alias_label" : "example_label"
    }
  ]
}'

Réponse

Lorsqu’un alias est ignoré parce que la même combinaison alias_label et alias_name existe déjà pour un utilisateur, le corps de la réponse peut tout de même indiquer un succès. Consultez Lorsque alias_label et alias_name existent déjà pour plus de détails.

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

Résolution des problèmes

Pourquoi mes attributs ne se mettent-ils pas à jour après avoir créé un alias d’utilisateur avec cet endpoint ?

Cela se produit généralement lorsque /users/alias/new est suivi d’une requête /users/track distincte qui tente de mettre à jour les attributs par alias. La requête track peut être traitée avant que Braze ne puisse résoudre de manière cohérente la nouvelle paire alias_label et alias_name vers un profil, de sorte que les attributs ne sont pas appliqués à l’utilisateur attendu.

Approche recommandée : Utilisez un seul appel /users/track uniquement lorsque vous souhaitez créer un profil alias uniquement ou mettre à jour un profil par un alias qui existe déjà. Dans le tableau attributes, placez user_alias et vos champs de profil dans le même objet attributs d’utilisateur afin que Braze résolve l’utilisateur et applique la mise à jour en une seule étape.

Définissez _update_existing_only sur false lorsque vous devez éventuellement créer un profil alias uniquement à partir de cet objet. Si vous l’omettez tout en utilisant user_alias, Braze adopte par défaut un comportement de mise à jour uniquement et ne crée pas le profil alias uniquement. Si l’alias existe déjà pour un utilisateur dans votre espace de travail, la même requête met à jour ce profil avec vos nouveaux attributs.

Vous ne pouvez pas utiliser /users/track pour ajouter un nouvel alias à un utilisateur existant identifié par external_id. Dans un objet attributs d’utilisateur, external_id et user_alias sont mutuellement exclusifs. Pour ajouter un alias à un utilisateur identifié, appelez d’abord /users/alias/new. Une fois l’alias rattaché, vous pouvez mettre à jour ce profil avec /users/track en utilisant l’external_id ou l’alias existant.

Par exemple, le corps /users/track suivant crée un profil alias uniquement si l’alias n’existe pas encore, ou met à jour le profil existant qui possède déjà cet alias :

1
2
3
4
5
6
7
8
9
10
11
12
{
  "attributes": [
    {
      "user_alias": {
        "alias_name": "[email protected]",
        "alias_label": "email"
      },
      "_update_existing_only": false,
      "string_attribute": "test_alias_only_update"
    }
  ]
}