커스텀 계정 연동

현재 로그인한 Player ID에 커스텀 계정을 추가로 연결합니다. 연결한 뒤에는 사용자가 기존 로그인 수단과 커스텀 계정 중 어느 쪽으로 로그인해도 같은 Player ID로 로그인해 같은 플레이 데이터를 계속 이용합니다.

커스텀 계정 연동도 커스텀 계정으로 로그인과 마찬가지로 앱 서버가 발급받은 grant key를 사용합니다. 앱 클라이언트는 커스텀 인증 제공자의 인증 정보를 직접 다루지 않습니다.

1. 커스텀 계정 연동 흐름

커스텀 계정 연동은 앱 서버와 앱 클라이언트가 나누어 처리합니다.

앱 클라이언트가 사용자를 앱 서버 또는 앱이 사용하는 인증 시스템으로 인증합니다.
앱 서버가 사전 인가 키 발급으로 Hive Axyl 서버에 연동용 grant key 발급을 요청합니다. 이때 커스텀 인증 제공자 식별자, 그 제공자의 사용자 식별자, 연동 대상 Player ID를 함께 전달합니다.
앱 서버가 발급받은 grant key를 앱 클라이언트에 전달합니다.
앱 클라이언트가 grant key로 LinkCustomProviderAsync()를 호출합니다.
Hive Axyl 인증 서버가 현재 로그인된 Player ID에 커스텀 계정을 연결합니다.

grant key는 발급 후 60초 동안만 유효하고 한 번만 사용할 수 있습니다. grant key의 개념과 앱 서버가 처리할 내용은 추가 보안 적용을 참조하세요.

호출하기 전에 사용자가 로그인하여 세션이 활성화된 상태여야 합니다. 연동은 현재 세션의 Player ID를 기준으로 처리됩니다.

2. 커스텀 계정 연동

LinkCustomProviderAsync

LinkCustomProviderAsync()를 호출해 현재 로그인된 Player ID에 커스텀 계정을 연결합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	CustomLinkRequest	Required	커스텀 계정 연동 요청
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

CustomLinkRequest

필드명	타입	필수 여부	설명
`GrantKey`	string	Required	앱 서버가 연동용으로 발급받아 전달한 사전 인증 키

호출 예시

요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

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

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

var result = await auth.LinkCustomProviderAsync(new CustomLinkRequest {
    GrantKey = customLinkGrantKey,
});

switch (result)
{
    case AuthLinkCustomProviderResult.Success success:
        Debug.Log($"커스텀 계정 연동 완료: PlayerId={success.Data.PlayerId}");
        break;

    case AuthLinkCustomProviderResult.InvalidGrantKey:
        // grant key가 만료되었거나 이미 사용됨 → 앱 서버에서 새로 발급받아 재시도
        break;

    case AuthLinkCustomProviderResult.PlayerIdDoesNotMatch:
        // grant key의 연동 대상과 현재 세션의 Player ID가 다름
        break;

    case AuthLinkCustomProviderResult.ProviderOwnedByOther:
        // 이 커스텀 계정이 다른 Player ID에 이미 연동됨 → 계정 충돌 처리
        break;

    case AuthLinkCustomProviderResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

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

응답 데이터

성공 시 AuthLinkCustomProviderResult.Success의 Data(ProviderLinkResponseData)에 연결된 커스텀 계정 정보가 담깁니다.

필드명	타입	필수 여부	설명
`Data.PlayerId`	long	Required	커스텀 계정이 연결된 Player ID
`Data.ProviderId`	`Provider`	Required	연결된 로그인 수단. 커스텀 계정은 `CustomProvider`입니다.
`Data.ProviderUserId`	string	Required	커스텀 인증 제공자의 사용자 식별자
`Data.ProviderIndex`	int	Required	연결된 로그인 수단을 나타내는 숫자 식별자

응답 예시