Google Play Games 로그인 Add-on

Android에서 Play Games Services v2의 GamesSignInClient로 Google Play Games 로그인을 처리하는 Add-on입니다. 인증 상태 조회, 로그인, 서버 교환용 인가 코드 발급을 서로 독립된 메서드로 제공합니다. 발급받은 인가 코드를 Auth 모듈의 ExchangeProviderTokenAsync()로 교환한 뒤 LoginProviderAsync()에 넘겨 로그인합니다.

모듈 정보

• 패키지: com.com2usplatform.hiveaxyl.auth.addon.gpg
• 인터페이스: IGooglePlayGamesPlugin
• 네임스페이스: Hive.Axyl.Auth.Addon.GPG
• 등록 메서드: AddGooglePlayGames()
• 지원 플랫폼: Android
• 최소 사양: Android API 29+, Unity 6000.0+

사전 준비

SDK는 Play Games 프로젝트 설정을 대신하지 않습니다. 앱이 Games services 프로젝트 ID를 Android 매니페스트의 com.google.android.gms.games.APP_ID 메타데이터로 직접 선언해야 합니다. 설정 방법은 Add-on 설치와 Android 설정을 참조하세요.

Play Games SDK 초기화 코드는 작성하지 않아도 됩니다. Play Games SDK가 자체 매니페스트에 포함한 PlayGamesInitProvider로 스스로 초기화하기 때문입니다. 이 프로바이더를 제거하고 PlayGamesSdk.initialize()도 호출하지 않으면 예외가 발생하지 않고 Code가 FailedPrecondition인 Failure가 반환됩니다.

서버 교환용 인가 코드를 발급받으려면 웹 애플리케이션 유형 OAuth 2.0 클라이언트를 준비해 Play Games Services에 연결해야 합니다. 준비 방법은 Google Play Games 로그인 인증 정보 확인을 참조하세요.

등록과 획득

HiveBootstrap.Initialize의 등록 단계에서 등록한 뒤 HiveCore.TryResolve<T>()로 가져옵니다.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Auth.Addon.GPG;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth()
           .AddToken()
           .AddGooglePlayGames();
});

if (HiveCore.TryResolve<IGooglePlayGamesPlugin>(out var gpg))
{
    // Android 빌드에서만 실행되는 코드
}

Unity 에디터에서는 등록되지 않습니다

이 Add-on은 Android로 빌드한 플레이어에서만 등록됩니다. Unity 에디터에서는 플랫폼을 Android로 바꿔도 등록되지 않으므로, HiveCore.Resolve<T>()를 쓰면 RegistrationNotFoundException이 발생합니다. 반드시 TryResolve<T>()로 확인한 뒤 사용하세요.

패키지 설치와 등록 절차는 모듈 설치 및 초기화를 참조하세요.

메서드 요약

비동기 메서드는 마지막 파라미터로 CancellationToken ct = default를 받습니다. 호출 규약은 호출 컨텍스트를 참조하세요.

• IsAuthenticatedAsync(): 화면 표시 없이 현재 Play Games 인증 상태 조회
• SignInAsync(): Play Games 계정 선택 화면 표시와 로그인
• RequestServerSideAccessAsync(): 서버 교환용 인가 코드 발급
• CancelCurrentSignIn(): 코드에서 진행 중인 로그인 취소

IsAuthenticatedAsync(), SignInAsync(), RequestServerSideAccessAsync()는 서로 독립된 호출입니다. SDK가 이 메서드들을 하나로 묶어 실행하지 않으므로, 필요한 순서대로 앱이 직접 호출하세요.

메서드

IsAuthenticatedAsync

GamesSignInClient.isAuthenticated()로 현재 Play Games 인증 상태를 조회합니다. 로그인 화면을 띄우지 않습니다.

어느 스레드에서 호출해도 안전하며, 동시에 여러 번 호출해도 됩니다.

Unity

Task<GooglePlayGamesServiceIsAuthenticatedResult> IsAuthenticatedAsync(IsAuthenticatedRequest request, CancellationToken ct = default)

• 요청: IsAuthenticatedRequest
• 응답: IsAuthenticatedResponse

결과 케이스 — GooglePlayGamesServiceIsAuthenticatedResult

결과 케이스	와이어 코드	설명
Success	—	인증된 상태입니다.
NotAuthenticated	not_authenticated	인증되지 않은 상태입니다. SignInAsync()로 로그인하세요.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. Problem의 HiveError로 원인을 확인합니다.

NotAuthenticated는 오류가 아닙니다

로그인되어 있지 않은 상태는 Failure가 아닌 NotAuthenticated로 반환됩니다. 오류 처리와 구분해 SignInAsync()로 로그인을 진행하세요.

발생 예외

• ArgumentNullException: request가 null인 경우

SignInAsync

GamesSignInClient.signIn()으로 Play Games 계정 선택 화면을 띄웁니다. 앱 사용자에게 기본 Play Games 계정이 이미 있으면 화면 없이 로그인을 마칩니다.

어느 스레드에서 호출해도 안전합니다. 한 번에 하나의 로그인만 진행하며, 로그인이 진행 중일 때 다시 호출하면 진행 중인 로그인은 그대로 두고 Code가 FailedPrecondition인 Failure를 바로 반환합니다.

Unity

Task<GooglePlayGamesServiceSignInResult> SignInAsync(SignInRequest request, CancellationToken ct = default)

• 요청: SignInRequest
• 응답: SignInResponse

결과 케이스 — GooglePlayGamesServiceSignInResult

결과 케이스	와이어 코드	설명
Success	—	로그인에 성공했습니다.
UserCanceled	user_canceled	앱 사용자가 로그인 화면을 닫았습니다.
NotAuthenticated	not_authenticated	호출은 끝났지만 여전히 인증되지 않은 상태입니다. 드물게 발생합니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. Problem의 HiveError로 원인을 확인합니다.

UserCanceled는 IUserCanceledOutcome을 구현합니다.

사용자 취소와 코드 취소는 다릅니다

앱 사용자가 로그인 화면을 닫으면 UserCanceled입니다. 반면 CancellationToken이나 CancelCurrentSignIn()으로 코드에서 취소하면 Code가 Cancelled인 Failure가 됩니다.

발생 예외

• ArgumentNullException: request가 null인 경우

RequestServerSideAccessAsync

GamesSignInClient.requestServerSideAccess()로 서버 교환용 인가 코드를 발급받습니다. Play Games에 로그인된 상태에서만 발급되며, 로그인되어 있지 않으면 NotAuthenticated를 반환합니다.

어느 스레드에서 호출해도 안전하며, 동시에 여러 번 호출해도 됩니다.

Unity

Task<GooglePlayGamesServiceRequestServerSideAccessResult> RequestServerSideAccessAsync(RequestServerSideAccessRequest request, CancellationToken ct = default)

• 요청: RequestServerSideAccessRequest
• 응답: RequestServerSideAccessResponse

결과 케이스 — GooglePlayGamesServiceRequestServerSideAccessResult

결과 케이스	와이어 코드	설명
Success	—	인가 코드를 발급받았습니다. Data.ServerAuthCode에 인가 코드가 담깁니다.
NotAuthenticated	not_authenticated	인증되지 않은 상태입니다. SignInAsync()로 로그인한 뒤 다시 호출하세요.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. Problem의 HiveError로 원인을 확인합니다.

발생 예외

• ArgumentNullException: request가 null인 경우
• ArgumentException: request.WebClientId가 null이거나 비어 있는 경우

호출 예시

Unity

using Hive.Axyl.Auth.Addon.GPG;

// 1. 인증 상태를 확인하고, 인증되지 않았다면 로그인합니다.
var authState = await gpg.IsAuthenticatedAsync(new IsAuthenticatedRequest());

if (authState is GooglePlayGamesServiceIsAuthenticatedResult.NotAuthenticated)
{
    var signIn = await gpg.SignInAsync(new SignInRequest());

    if (signIn is not GooglePlayGamesServiceSignInResult.Success)
    {
        return;
    }
}

// 2. 서버 교환용 인가 코드를 발급받습니다.
var access = await gpg.RequestServerSideAccessAsync(new RequestServerSideAccessRequest
{
    WebClientId = "{webClientId}",
    ForceRefreshToken = true,
});

if (access is GooglePlayGamesServiceRequestServerSideAccessResult.Success success)
{
    string serverAuthCode = success.Data.ServerAuthCode;   // ExchangeProviderTokenAsync의 ProviderCode
}

인가 코드를 발급받으면 ProviderCode로 넣어 ExchangeProviderTokenAsync()로 교환하고, 교환 결과로 LoginProviderAsync()를 호출합니다. 구현 절차는 Google Play Games 자격 증명 획득을 참조하세요.

CancelCurrentSignIn

진행 중인 로그인을 코드에서 취소합니다. 대기 중이던 SignInAsync()는 Code가 Cancelled인 Failure로 끝납니다. 진행 중인 로그인이 없으면 아무 동작도 하지 않습니다.

화면을 띄우지 않는 IsAuthenticatedAsync()와 RequestServerSideAccessAsync()는 이 메서드의 영향을 받지 않습니다. 어느 스레드에서 호출해도 안전합니다.

Unity

void CancelCurrentSignIn()

데이터 타입

IsAuthenticatedRequest

필드가 없습니다. null 대신 빈 인스턴스를 전달하세요.

IsAuthenticatedResponse

필드가 없습니다. Success 결과 자체가 인증된 상태를 뜻합니다.

RequestServerSideAccessRequest

필드	타입	필수 여부	설명
WebClientId	string	Required	인가 코드를 Google 토큰 엔드포인트에서 교환할 때 사용하는 웹 애플리케이션 유형 OAuth 2.0 클라이언트 ID입니다. 발급 방법은 Google Play Games 로그인 인증 정보 확인을 참조하세요. 비어 있으면 ArgumentException이 발생합니다.
ForceRefreshToken	bool	Required	리프레시 토큰을 새로 요청할지 여부입니다. true이면 Google이 리프레시 토큰을 새로 발급하고, false이면 기존의 유효한 리프레시 토큰을 재사용할 수 있습니다. 처음 서버 교환을 하거나 이전의 서버 측 토큰 갱신이 실패한 뒤에는 true를 권장합니다.

RequestServerSideAccessResponse

필드	타입	필수 여부	설명
ServerAuthCode	string	Required	수명이 짧은 서버 교환용 인가 코드입니다. 변환하지 않고 ExchangeProviderTokenAsync() 요청의 ProviderCode에 그대로 넣으세요. 한 번만 사용할 수 있으며, 유효 기간은 Google 정책을 따릅니다.

인가 코드를 로그에 남기지 마세요

ServerAuthCode는 Google 토큰 엔드포인트에서 액세스 토큰과 리프레시 토큰으로 교환되는 민감한 값입니다. 로그, 크래시 리포트, 분석 이벤트에 기록하지 마세요.

SignInRequest

필드가 없습니다. null 대신 빈 인스턴스를 전달하세요.

SignInResponse

필드가 없습니다. Success 결과 자체가 인증된 상태를 뜻합니다.