계정 연동 처리 및 조회

LinkProviderAsync

Player ID는 로그인한 사용자를 식별하는 값입니다. 현재 로그인한 Player ID에 로그인 수단을 추가로 연결하려면 LinkProviderAsync()를 호출하세요. 연결이 끝나면 사용자는 연결된 로그인 수단 중 무엇으로 로그인해도 같은 Player ID로 로그인해 같은 플레이 데이터를 계속 이용합니다.

계정 연동에는 아래 정책이 적용됩니다.

로그인한 상태에서만 연동 가능
Player ID당 같은 종류의 로그인 수단 하나
게스트 연동 불가
서로 다른 두 계정의 병합 불가

같은 종류의 로그인 수단이 이미 연결되어 있으면 연동 요청이 거부됩니다. 다른 계정으로 바꾸려면 계정 연동 해제로 기존 연결을 먼저 끊은 뒤 새 계정을 연동하세요. 연동하려는 계정이 이미 다른 Player ID에 연결되어 있으면 계정 연동 충돌이 발생하며, 이때의 처리 방법은 계정 연동 시 충돌 처리를 참조하세요.

게스트로 시작한 계정에 로그인 수단을 처음 연동하면 Hive Axyl 인증 서버가 그 Player ID의 게스트 토큰을 무효로 만듭니다. 게스트 토큰은 게스트 계정 생성에서 발급받아 기기에 보관해 둔 재로그인용 자격 증명입니다. 연동 이후에는 연동한 로그인 수단이 그 계정으로 들어가는 길이 되므로, 보관해 둔 게스트 토큰은 연동에 성공한 시점에 지우세요. 그대로 두면 다음 실행에서 더 이상 쓸 수 없는 값으로 게스트 로그인을 시도해 InvalidGuestToken으로 거절됩니다.

커스텀 계정은 앱 서버가 발급받은 grant key로 연동하므로 이 메서드를 사용하지 않습니다. 커스텀 계정 연동을 참조하세요.

계정 연동 처리

연결할 로그인 수단의 인증 정보 확보

LinkProviderAsync()는 연결하려는 계정이 실제로 그 사용자의 것인지 Hive Axyl 인증 서버가 검증할 수 있도록 사용자 식별자와 인증 결과를 요구합니다. 따라서 이 메서드를 호출하기 전에 연결할 로그인 수단으로 먼저 인증해 두 값을 받아 두어야 합니다.

외부 인증 제공자 계정

Google, Apple, Google Play Games, Steam, X 계정은 로그인 수단별 Add-on 또는 웹 로그인 세션으로 인증해 ProviderUserId와 ProviderToken을 받습니다. 로그인 수단별 인증 방법은 외부 인증 제공자 로그인을 참조하세요.

유저네임 계정

사용자가 입력한 유저네임은 ProviderUserId에 넣고, 비밀번호는 SHA256(raw_password)로 변환한 64자 16진수 문자열을 ProviderToken에 넣습니다. Hive Axyl SDK는 비밀번호를 해싱하지 않으므로 앱 클라이언트에서 직접 변환하세요. 평문 비밀번호는 전송하지 마세요.

유저네임을 연동할 때 Hive Axyl 인증 서버는 입력한 유저네임의 상태에 따라 처리를 나눕니다. 같은 유저네임이 없으면 입력한 값으로 유저네임 계정을 새로 만들어 현재 Player ID에 연결합니다. 이미 다른 Player ID가 쓰고 있는 유저네임이면 UsernameAlreadyExists로 거부합니다. 예전에 만들어졌지만 지금은 어떤 Player ID에도 연결되어 있지 않은 유저네임이면 비밀번호를 검증한 뒤 현재 Player ID에 연결합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	`ProviderLinkRequest`	Required	연결할 로그인 수단 정보
context	`ApiCallContext`	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

ProviderLinkRequest

필드명	타입	필수 여부	설명
`ProviderId`	`Provider`	Required	연결할 로그인 수단입니다. `Google`, `SigninApple`, `GooglePlayGames`, `Steam`, `X`, `Username` 중 하나입니다. `Guest`는 사용할 수 없으며, `Guest`를 지정하면 `Failure`가 반환되고 `Failure.Problem.ExternalCode`에 `invalid_parameter`가 담깁니다.
`ProviderUserId`	string	Required	연결할 계정의 사용자 식별자입니다. 유저네임을 연동할 때는 유저네임 문자열입니다.
`ProviderToken`	string	Required	연결할 계정의 인증 결과입니다. 유저네임을 연동할 때는 비밀번호의 `SHA256(raw_password)` 값입니다. 민감 정보이므로 로그에 남기지 마세요.

호출 예시

LinkProviderAsync()의 반환 객체 AuthLinkProviderResult는 성공, 기능별 결과인 Outcome, 호출을 마치지 못한 Failure로 나뉩니다. 이 메서드는 예외를 던지지 않고 모든 처리 결과를 반환 객체로 전달하므로, try/catch 대신 switch 구문으로 분기해 처리하세요.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using UnityEngine;

IAuthService auth = HiveCore.Resolve<IAuthService>();

// googleUserId·googleIdToken은 Google 로그인 Add-on으로 먼저 받아 둔 값입니다.
var result = await auth.LinkProviderAsync(new ProviderLinkRequest {
    ProviderId     = Provider.Google,
    ProviderUserId = googleUserId,
    ProviderToken  = googleIdToken,
});

switch (result)
{
    case AuthLinkProviderResult.Success success:
        // 연동 완료 → 화면의 연동 목록을 갱신합니다.
        Debug.Log($"연동 완료: {success.Data.ProviderId} (PlayerId={success.Data.PlayerId})");
        break;

    case AuthLinkProviderResult.ProviderOwnedByOther:
        // 다른 Player ID가 이미 쓰고 있는 계정 → 충돌 처리 흐름으로 이동합니다.
        ShowLinkConflictPopup();
        break;

    case AuthLinkProviderResult.ProviderTypeAlreadyExists:
        // 같은 종류의 로그인 수단이 이미 연결된 상태 → 기존 연결 해제를 안내합니다.
        Debug.LogWarning("이미 같은 종류의 로그인 수단이 연결되어 있습니다.");
        break;

    // 공통 실패 처리 (네트워크·서버 오류)
    case AuthLinkProviderResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 AuthLinkProviderResult.Success의 Data에 방금 연결한 로그인 수단 정보가 담깁니다.

변수명	타입	필수 여부	설명
`Data.PlayerId`	long	Required	로그인 수단을 연결한 Player ID
`Data.ProviderId`	`Provider`	Required	연결된 로그인 수단
`Data.ProviderUserId`	string	Required	연결된 계정의 사용자 식별자
`Data.ProviderIndex`	int	Required	연결된 로그인 수단을 나타내는 숫자 식별자

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.PlayerId       = 10000021454
// success.Data.ProviderId     = Provider.Google
// success.Data.ProviderUserId = "104839..."
// success.Data.ProviderIndex  = 2

응답 상태

반환 객체 AuthLinkProviderResult는 아래 케이스 중 하나로 분기됩니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	연동 성공. `Data`에 연결된 로그인 수단 정보가 담깁니다.	연동 목록 갱신
`ProviderTypeAlreadyExists`	같은 종류의 로그인 수단이 이미 연결된 경우	기존 연결을 해제한 뒤 다시 시도하도록 안내
`ProviderOwnedByOther`	연동하려는 계정이 다른 Player ID에 이미 연결된 경우	계정 연동 시 충돌 처리 참조
`ProviderAlreadyConnected`	이미 이 Player ID에 연결된 계정인 경우	연동 완료 상태로 화면 갱신
`ProviderTokenError`	로그인 수단의 인증 결과 검증에 실패한 경우	해당 로그인 수단으로 다시 인증하도록 안내
`ProviderRequestFailed`	Hive Axyl 인증 서버가 외부 인증 제공자에 보낸 요청이 실패한 경우	재시도 또는 오류 안내
`InvalidUsernameFormat` · `InvalidPasswordFormat`	유저네임 또는 비밀번호가 형식 규격에 맞지 않는 경우	입력값과 해시 변환 결과 점검
`UsernameVerifyFailed`	소유자가 없는 유저네임에 연동하려 했으나 비밀번호가 일치하지 않는 경우	비밀번호 재입력 안내
`UsernameAlreadyExists`	다른 Player ID가 이미 쓰고 있는 유저네임인 경우	다른 유저네임 입력 안내
`IpBlocked`	접속 IP가 차단된 경우	정책 안내
`PlayerNotFound`	로그인한 Player 정보를 찾을 수 없는 경우	재로그인 유도
`AppNotFound` · `TerminateService`	앱 정보를 찾을 수 없거나 서비스가 종료된 앱인 경우	콘솔의 App ID 등록 상태와 서비스 운영 상태 확인
`ProviderConfigNotFound` · `ProviderClientInfoNotExists`	콘솔에 이 로그인 수단의 설정이나 클라이언트 정보가 없는 경우	콘솔의 로그인 설정 확인
`AppIdMismatch` · `InvalidGatewayContext`	요청의 App ID가 인증 토큰의 프로젝트와 다르거나 인증 컨텍스트가 유효하지 않은 경우	SDK 초기화에 사용한 App ID와 세션 상태 확인
`UnknownOutcome`	이 SDK 버전이 알지 못하는 신규 결과	로깅 후 보수적으로 처리
`Failure`	공통 Failure입니다. 필수 파라미터 누락·형식 오류(`invalid_parameter`), 필수 필드 누락(`missing_field`), `X-App-Id` 헤더 누락(`missing_app_id`)도 여기로 분기하며 원인은 `Failure.Problem.ExternalCode`에 담깁니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

연동된 로그인 수단 조회

현재 Player ID에 연결된 로그인 수단 목록만 따로 조회하는 메서드는 없습니다. 로그인 응답에 담겨 오는 Data.ProviderList로 확인합니다. 로그인 응답 데이터 구조는 외부 인증 제공자 로그인을 참조하세요.

ProviderInfo

Data.ProviderList의 각 항목은 아래 값을 가집니다.

변수명	타입	필수 여부	설명
`ProviderUserId`	string	Required	연결된 계정의 사용자 식별자
`ProviderId`	`Provider`	Required	연결된 로그인 수단
`ProviderIndex`	int	Required	연결된 로그인 수단을 나타내는 숫자 식별자

로그인 이후에 연동하거나 해제하면 이 목록은 다시 내려오지 않습니다. LinkProviderAsync() 성공 응답의 Data로 항목을 추가하고, UnlinkProviderAsync() 성공 시 해제한 항목을 제거해 화면의 연동 목록을 앱 클라이언트에서 직접 갱신하세요.

지원하는 로그인 수단 조회가 반환하는 목록은 이 앱에서 사용할 수 있는 로그인 수단이고, Data.ProviderList는 이 계정에 실제로 연결된 로그인 수단입니다. 두 목록은 서로 다릅니다.

연관 문서

계정 연동 해제: 연결된 로그인 수단 끊기
계정 연동 시 충돌 처리: 다른 Player ID가 쓰고 있는 계정을 연동할 때의 처리
사용 예시: 연동과 해제를 화면 흐름에 적용한 예시