사용자 및 범위가 지정된 사용자 ID

Roblox는 각 게임, 그룹 또는 앱의 각 사용자에 대해 하나의 유효한 사용자 ID를 노출합니다. 사용자의 해당 도메인에 대한 이력에 따라, 그들의 유효한 사용자 ID는 글로벌 사용자 ID이거나 범위가 지정된 사용자 ID입니다. 이 페이지에서는 유효한 사용자 ID가 어떻게 작동하는지와 게임 코드에서 User 유형을 사용하는 방법을 설명합니다.

사용자 식별에 중심이 되는 개념은 다음과 같습니다:

유효한 사용자 ID와 도메인

각 사용자는 특정 게임, 그룹, 또는 앱 내에서 하나의 유효한 사용자 ID를 가집니다. Roblox는 해당 도메인에서 동일한 사용자에 대해 별도의 글로벌 및 범위가 지정된 사용자 ID를 노출하지 않습니다:

• 사전 배포 사용자는 그들의 글로벌 사용자 ID를 유효한 사용자 ID로 가집니다.
• 배포 후 사용자는 범위가 지정된 사용자 ID를 유효한 사용자 ID로 가집니다. 그 ID는 해당 도메인 내에서만 의미가 있습니다.

게임 코드에서 Player.UserId와 Player.User.Id는 모두 이 유효한 사용자 ID를 반환하며 항상 동일한 숫자 값을 가집니다 (Player.User.Id는 Player.UserId와 같습니다), 따라서 코드에서 이들 간의 선택을 위한 분기 로직이 필요하지 않습니다.

Roblox는 사용자 신원을 세 가지 유형의 도메인에 걸쳐 범위 지정합니다:

유효한 사용자 ID 작동 방식

플레이어가 당신의 게임에 참여할 때, 그들은 해당 게임에 대해 하나의 유효한 사용자 ID를 가집니다. 배포 후 사용자의 유효한 사용자 ID는 해당 게임에 고유한 범위가 지정된 사용자 ID입니다. 그들은 또한 배포 후 사용자인 다른 게임, 그룹 또는 앱에서 다른 범위가 지정된 사용자 ID를 받습니다. 이는 다음을 의미합니다:

• 유효한 사용자 ID는 정수입니다, 글로벌이든 범위가 지정된 것이든.
• 유효한 사용자 ID는 동일한 도메인 내에서 세션 간에 안정적입니다.
• 범위가 지정된 사용자 ID는 기존의 글로벌 사용자 ID와 충돌하지 않습니다.
• 동일한 숫자 값이 서로 다른 사용자에 대해 서로 다른 도메인에서 나타날 수 있습니다. 고유한 키는 도메인(도메인 유형 및 도메인 ID)과 유효한 사용자 ID의 조합입니다.

예시 시나리오

다음 예시는 서로 다른 게임이 동일한 사용자를 참조하는 방법을 보여줍니다:

사전 배포 사용자

플레이어가 당신의 게임에서 사전 배포 사용자라면, 그들의 유효한 사용자 ID는 해당 게임에서 그들의 글로벌 사용자 ID로 유지됩니다. Player.UserId와 Player.User.Id는 그 글로벌 사용자 ID를 반환합니다. Roblox는 해당 게임에서 플레이어에 대해 두 번째 사용자 ID를 노출하지 않습니다. 이는 기존 데이터 저장소 키, 리더보드 및 인벤토리가 변경 없이 계속 작동하도록 보장합니다.

그룹 도메인

각 Roblox 그룹은 자체 도메인입니다. 사용자는 그룹 내에서 하나의 유효한 사용자 ID를 가지며, 이는 게임이나 OAuth 애플리케이션에서의 유효한 사용자 ID와는 별개입니다:

• 게임 내 그룹 확인은 변경되지 않음 — Player의 엔진 메서드인 Player:IsInGroupAsync(), Player:GetRankInGroupAsync(), Player:GetRoleInGroupAsync(), 및 GroupService:PromptJoinAsync()는 사용자 ID를 노출하지 않고 내부적으로 신원을 해결합니다.
• Open Cloud 그룹 API는 그룹의 도메인을 사용함 — 이는 그룹 멤버십 및 가입 요청을 나열하거나 관리하는 엔드포인트에 적용됩니다.

사용자 유형 작업하기

User는 게임 코드에서 사용자를 식별하는 표준 방법입니다. User 값은 유효한 사용자 ID와 함께 도메인 유형 및 도메인 ID를 포함하므로, 신원 컨텍스트가 항상 식별자와 함께 전달됩니다. 전체 API 세부정보는 User 참조를 참조하십시오.

플레이어에서 사용자 가져오기

User를 얻는 주요 방법은 연결된 Player를 통해 Player.User를 사용하는 것입니다:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local user = player.User
    print("유효한 사용자 ID:", user.Id) -- 항상 player.UserId와 일치
    print("도메인 유형:", user.DomainType)
    print("도메인 ID:", user.DomainId)
end)

ID로 사용자 구성하기

현재 게임 내에서 알려진 유효한 사용자 ID로부터 User를 생성하려면 User.fromId()를 사용하십시오:

local user = User.fromId(knownUserId)

엔진 API와 사용자 사용하기

사용자 ID 매개변수를 수용하는 엔진 API는 User 값을 직접 수용합니다. User 사용을 권장합니다:

-- 두 형태 모두 작동합니다:
BadgeService:AwardBadge(player.User, badgeId)    -- 권장
BadgeService:AwardBadge(player.UserId, badgeId)

-- 두 형태 모두 작동합니다:
local target = Players:GetPlayerByUserId(player.User) -- 권장
local target = Players:GetPlayerByUserId(someUserId)

숫자 사용자 ID가 사용자 ID를 수용하는 엔진 API에 전달되면, 내부적으로 자동으로 User로 래핑됩니다.

사용자 ID를 반환하는 엔진 API

숫자 사용자 ID를 반환하는 엔진 API는 사용자의 유효한 사용자 ID를 반환합니다:

• 사전 배포 사용자 — API는 사용자의 글로벌 사용자 ID를 반환합니다.
• 배포 후 사용자 — API는 사용자의 범위가 지정된 사용자 ID를 반환합니다.

Player.UserId, Player.User.Id, 및 기타 엔진 API는 모두 게임 내 사용자의 동일한 유효한 사용자 ID를 반환하므로, 숫자 사용자 ID 필드를 읽는 기존 코드가 분기 로직 없이 계속 작동합니다.

Open Cloud 요청 및 응답은 대상 도메인에 대해 동일한 유효한 사용자 ID를 사용합니다. 그들은 해당 도메인에서 동일한 사용자에 대해 두 번째 사용자 ID를 노출하지 않습니다.

사용자 신원 저장하기

숫자 유효한 사용자 ID는 단일 도메인 내에서 사용자 식별에만 사용하십시오. 한 게임의 데이터 저장소 키는 user.Id를 직접 사용할 수 있습니다:

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

다른 도메인이 저장된 신원을 읽을 때, 예를 들어 사용자를 조정하는 OAuth 앱이 있을 경우, ToString()에서 문자열을 저장하십시오. 이 문자열은 유효한 사용자 ID와 함께 도메인 컨텍스트를 인코딩합니다. 정수만 사용하면 동일한 숫자가 다른 도메인에서 다른 사용자로 식별될 때 잘못된 사용자에게 작업이 적용될 수 있습니다.

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

-- 나중에 문자열에서 복원
local user = User.fromString(encoded)

직렬화 보장에 대한 자세한 내용은 User 참조를 참조하십시오.

모범 사례

• 새로운 코드에서 표준 식별자로 Player.User를 사용하십시오.
• 숫자 유효한 사용자 ID는 단일 도메인 내에서만 사용하십시오, 예를 들어 한 게임의 데이터 저장소 키.
• 다른 도메인이 저장된 신원을 읽을 때 ToString() 및 fromString()을 사용하십시오.

사용자 또는 플레이어 사용 시기

• 서버 내 작업을 위해 Player를 사용하십시오: 캐릭터 이동, GUI, 텔레포트, 채팅, 인벤토리.
• 세션을 초월하는 신원을 위해 User를 사용하십시오: 데이터 저장소, Open Cloud 도구, 크로스 게임 참조.