Créer un nouvel alias d’utilisateur

Utilisez cet endpoint pour ajouter de nouveaux alias d’utilisateur à des 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 à un utilisateur existant nécessite d’inclure un external_id 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’external_id, un utilisateur sera tout de même créé, mais il devra être identifié ultérieurement. Pour ce faire, utilisez la fonctionnalité « Identification des utilisateurs » et l’endpoint users/identify.

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

Vous pouvez envoyer des campagnes déclenchées par API aux utilisateurs par user_alias à l’aide de l’endpoint /campaigns/trigger/send.

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 (qu’il s’agisse du même utilisateur ou d’un autre), l’endpoint renvoie tout de même une réponse indiquant un succès (par exemple, "aliases_processed": 1, "message": "success"). Dans ce cas, aucun nouvel alias n’est ajouté à l’utilisateur de la requête. La paire alias_label et alias_name étant 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.

Résolution des problèmes

Pourquoi mes attributs ne sont-ils pas mis à jour après la création d’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 des attributs par alias. La requête de suivi peut être traitée avant que Braze ne puisse associer de manière fiable la nouvelle paire alias_label et alias_name à un profil : les attributs ne sont alors 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 via un alias qui existe déjà. Dans le tableau attributes, placez user_alias et vos champs de profil dans le même objet d’attributs utilisateur afin que Braze identifie l’utilisateur et applique la mise à jour en une seule étape.

Définissez _update_existing_only sur false lorsque vous pourriez avoir besoin de créer un profil alias uniquement à partir de cet objet. Si vous l’omettez en utilisant user_alias, Braze applique par défaut un comportement de mise à jour seule et ne crée pas le profil alias uniquement. Si l’alias existe déjà pour un utilisateur de 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 d’attributs utilisateur, external_id et user_alias s’excluent mutuellement. Pour ajouter un alias à un utilisateur identifié, appelez d’abord /users/alias/new. Une fois l’alias associé, vous pouvez mettre à jour ce profil avec /users/track via l’external_id ou via l’alias existant.

Par exemple, le corps de requête /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"
    }
  ]
}

Vous pouvez télécharger le document OpenAPI et l’utiliser pour valider des schémas. Pour savoir comment procéder, consultez Utiliser les schémas OpenAPI pour la validation des requêtes.