Utilisateurs et identifiants d'utilisateur spécifiques au domaine

Roblox attribue à chaque utilisateur un identifiant d'utilisateur spécifique au domaine unique par jeu ou application avec lesquels ils interagissent. Cette page explique comment fonctionne l'identification spécifique au domaine et comment utiliser le type User dans le code de votre jeu.

Les concepts suivants sont centraux pour l'identification des utilisateurs :

Identifiants d'utilisateur spécifiques au domaine

Un identifiant d'utilisateur spécifique au domaine est un identifiant unique attribué à un utilisateur dans un jeu ou application spécifique. Contrairement à un identifiant d'utilisateur global, un identifiant d'utilisateur spécifique au domaine n'a de signification que dans le domaine qui l'a émis, donc le même utilisateur a un identifiant d'utilisateur spécifique au domaine différent dans chaque jeu ou application avec lesquels il interagit. Les joueurs qui ont rejoint votre jeu avant le déploiement de l'identifiant spécifique conservent leur identifiant d'utilisateur global d'origine dans ce jeu (voir Joueurs de retour).

Les types de domaine sont représentés par Enum.DomainType :

Comment fonctionnent les identifiants spécifiques au domaine

Lorsqu'un joueur rejoint votre jeu, il reçoit un identifiant d'utilisateur spécifique au domaine qui est unique à ce jeu. Le même joueur rejoignant un autre jeu reçoit un identifiant d'utilisateur spécifique au domaine différent. Cela signifie :

• Les identifiants d'utilisateur spécifiques au domaine sont des entiers, semblables aux identifiants d'utilisateur globaux existants.
• Un identifiant d'utilisateur spécifique au domaine ne se chevauche pas avec un identifiant d'utilisateur global existant.
• La même valeur numérique peut apparaître dans différents domaines pour différents utilisateurs. La clé unique est la combinaison du type de domaine, de l'ID de domaine et de l'identifiant d'utilisateur spécifique au domaine.

Scénario d'exemple

L'exemple suivant démontre comment différents jeux font référence au même utilisateur :

Joueurs de retour

Si un joueur a déjà rejoint votre jeu avant le déploiement de l'identifiant d'utilisateur spécifique, il conserve son identifiant d'utilisateur global d'origine dans ce jeu. Cela garantit que les clés de stockage de données existantes, les classements et les inventaires continuent de fonctionner sans aucune modification.

Travailler avec le type Utilisateur

User est la méthode standard pour identifier les utilisateurs dans le code du jeu. Une valeur User transporte l'identifiant d'utilisateur spécifique au domaine ainsi que le type de domaine et l'ID de domaine, donc le contexte d'identité accompagne toujours l'identifiant. Pour plus de détails sur l'API, consultez la référence User.

Obtenir un utilisateur à partir d'un joueur

La principale façon d'obtenir un User est à partir d'un Player connecté via Player.User :

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local user = player.User
    print("Identifiant utilisateur de domaine :", user.Id)
    print("Type de domaine :", user.DomainType)
    print("ID de domaine :", user.DomainId)
end)

Construire un utilisateur à partir d'un ID

Pour créer un User à partir d'un identifiant d'utilisateur connu dans le jeu actuel, utilisez User.fromId() :

local user = User.fromId(knownUserId)

Utiliser l'utilisateur avec les APIs moteur

Les APIs moteur qui acceptent un paramètre d'identifiant d'utilisateur acceptent également les valeurs User directement. L'utilisation de User est recommandée :

-- Les deux formes fonctionnent :
BadgeService:AwardBadge(player.User, badgeId)    -- Recommandé
BadgeService:AwardBadge(player.UserId, badgeId)

-- Les deux formes fonctionnent :
local target = Players:GetPlayerByUserId(player.User) -- Recommandé
local target = Players:GetPlayerByUserId(someUserId)

Lorsqu'un identifiant utilisateur numérique est passé à une API moteur qui accepte des identifiants utilisateurs, il est automatiquement enveloppé dans un User en interne.

APIs moteur qui retournent des IDs utilisateurs

Les APIs moteur qui retournent des identifiants d'utilisateur numériques continuent d'utiliser les mêmes noms de champ et types. Chaque ID retourné est soit un ID global soit un identifiant d'utilisateur spécifique au domaine, selon que l'utilisateur a rejoint le jeu avant ou après le déploiement de l'identifiant spécifique :

• Joueurs de retour (première connexion avant le lancement des ID spécifiques) — l'API retourne l'identifiant d'utilisateur global de l'utilisateur.
• Nouveaux joueurs (première connexion après le lancement des ID spécifiques) — l'API retourne l'identifiant d'utilisateur spécifique au domaine de l'utilisateur.

Les identifiants d'utilisateur globaux et spécifiques au domaine sont des entiers standards qui ne se chevauchent pas, donc le code existant qui lit ces champs numériques continue de fonctionner.

Stocker l'identité de l'utilisateur

Pour les clés de stockage de données dans un seul jeu, utilisez directement user.Id :

local key = ("player_%d"):format(player.User.Id)
PlayerDataStore:SetAsync(key, data)

Pour des valeurs qui peuvent être lues par d'autres systèmes ou qui nécessitent un contexte de domaine complet, sérialisez le User avec ToString() :

local encoded = player.User:ToString()
SomeDataStore:SetAsync("support_ticket_user", encoded)

-- Plus tard, restaurez à partir de la chaîne
local user = User.fromString(encoded)

Pour plus de détails sur les garanties de sérialisation, consultez la référence User.

Meilleures pratiques

• Utilisez Player.User comme identifiant standard dans le nouveau code.
• Utilisez ToString() et fromString() lors de la persistance ou de la transmission d'une valeur User.
• N'utilisez pas un identifiant utilisateur numérique d'un domaine pour identifier un utilisateur dans un autre domaine.

Quand utiliser Utilisateur ou Joueur

• Utilisez Player pour les actions en serveur : mouvement de personnage, interface utilisateur, téléportation, chat, inventaire.
• Utilisez User pour l'identité qui survit à une session : magasins de données, outils Open Cloud, références entre jeux.