콘텐츠로 이동

외부 인증 제공자 연동 활용 가이드

외부 인증 제공자 연동은 이미 로그인한 사용자의 계정에 로그인 수단을 추가로 연결하는 작업입니다. 외부 인증 제공자는 Google, Apple처럼 사용자를 대신 인증해 주는 서비스이며, 사용자는 이를 로그인 수단으로 사용합니다. 연결이 끝나면 사용자는 연결된 로그인 수단 중 무엇으로 로그인해도 같은 Player ID로 로그인해 같은 플레이 데이터를 계속 이용합니다.

구현하려면 Hive 콘솔 설정, Hive Axyl SDK 호출, 레시피 코드 호출, 앱 코드를 조합해야 합니다. 레시피 코드를 사용하면 연결할 계정의 인증과 연동 호출이 메서드 하나로 줄어듭니다.

외부 인증 제공자 연동을 구현하는 데 필요한 작업은 Hive 콘솔에 연결할 로그인 수단을 등록하는 것에서 시작해, 연동 결과에 맞는 화면을 띄우는 것으로 끝납니다.

각 단계의 작업은 아래 다섯 가지 구분 중 하나에 해당합니다.

구분 담당 내용
Hive 콘솔 앱 운영자 Hive 콘솔에서 수행하는 설정입니다.
Hive Axyl SDK 앱 개발자 앱에서 호출하는 Hive Axyl SDK 메서드입니다.
Add-on 앱 개발자 외부 인증 제공자의 인증 화면을 띄우는 Hive Axyl SDK 확장 패키지입니다.
레시피 코드 앱 개발자 앱에서 호출하는 레시피 메서드입니다.
앱 코드 앱 개발자 Hive Axyl을 거치지 않고 앱이 직접 구현하는 부분입니다.

외부 인증 제공자 연동에는 Hive Axyl 서버 API 호출이 없습니다. Add-on은 앱이 직접 호출하지 않고 레시피가 대신 호출하므로, 단계 구분이 아니라 레시피가 내부에서 수행하는 작업 목록에 나타납니다. 파라미터의 의미와 응답 필드는 각 단계에서 연결한 상세 절차를 참조하세요.

게스트 계정은 기기에 저장한 자격 증명으로만 복원되므로, 사용자가 앱을 지우거나 기기를 바꾸면 계정을 잃습니다. 게스트 계정에 로그인 수단을 연동하면 사용자는 그 로그인 수단으로 어느 기기에서든 같은 Player ID에 로그인합니다.

첫 연동이 끝나면 Hive Axyl 인증 서버는 그 Player ID의 게스트 토큰을 무효로 만듭니다. 연동 이후에는 게스트 자격 증명이 아니라 연동한 로그인 수단이 그 계정으로 들어가는 길이 됩니다. 앱은 게스트 자격 증명 저장소 준비에서 만든 저장소의 값을 지워야 하며, 처리 방법은 게스트 자격 증명 정리에서 설명합니다.

Hive Axyl SDK는 연동 메서드 LinkProviderAsync() 하나를 제공하지만, 호출하기 전에 연결할 계정의 사용자 식별자와 인증 결과를 앱이 먼저 확보해야 합니다. 그 값을 받는 방법은 로그인 수단마다 다르고, 인증 화면을 띄우는 동안 로그인 세션이 바뀌지 않았는지도 앱이 직접 확인해야 합니다.

레시피는 그 조합을 미리 완성해 둔 소스 코드입니다. 패키지가 아니라 프로젝트에 복사해서 사용합니다.

구분 위치 성격
Hive Axyl SDK Unity 패키지 com.com2usplatform.hiveaxyl.* 설치해서 사용합니다. 인증 기능을 세분화된 메서드로 제공합니다.
레시피 Assets/Recipes/LinkProvider/ 복사해서 사용합니다. SDK 호출을 목적 단위로 묶은 순수 C# 코드입니다.
사용 예제 Assets/RecipeExamples/Authentication/LinkProviderExample.cs 읽고 참고하는 코드입니다. 레시피 호출 순서와 결과별로 앱이 구현해야 할 부분을 주석으로 설명합니다.
레시피는 복사해서 사용하는 코드입니다

레시피는 앱에 복사되어 앱의 코드가 됩니다. 그대로 사용해도 되고 앱 정책에 맞게 수정해서 사용해도 됩니다.

연동 레시피는 외부 인증 제공자로 로그인할 때 사용하는 인증 코드를 그대로 재사용합니다. 앱이 이미 제공하는 로그인 수단은 추가 구현 없이 연동 대상이 됩니다.

연동 해제에는 레시피가 없습니다. 연결한 로그인 수단을 끊으려면 Hive Axyl SDK 메서드를 직접 호출해야 하므로 계정 연동 해제를 참조하세요.

레시피가 연동하는 로그인 수단은 Google, Apple, Google Play Games, Steam, X 다섯 가지입니다. Google, Apple, Steam은 인증 방식이 두 가지이므로 앱이 지원할 OS에 맞게 고르세요. 하나의 Player ID에는 같은 종류의 로그인 수단을 하나만 연결합니다.

로그인 수단 인증 방식 사용하는 OS
Google Android 네이티브 계정 선택 화면 Android
Google 브라우저 로그인 Android, iOS, macOS, Windows
Apple Apple 네이티브 로그인 화면 iOS, macOS
Apple 브라우저 로그인 Android, Windows
Google Play Games Google Play Games 로그인 Android
Steam Steamworks 인증 티켓 Windows, macOS
Steam 브라우저 로그인 Android, iOS
X 브라우저 로그인 Android, iOS, macOS, Windows

유저네임 계정은 이 레시피로 연동하지 않습니다. 유저네임을 연동하려면 Hive Axyl SDK 메서드를 직접 호출해야 하므로 계정 연동 처리 및 조회를 참조하세요. 커스텀 계정은 앱 서버가 발급받은 grant key로 연동합니다. grant key는 앱 서버가 사용자를 인증했음을 증명하는 사전 인증 키이며, 사용 방법은 커스텀 계정 연동을 참조하세요. 게스트는 연동 대상이 아닙니다.

레시피는 연결할 계정의 인증과 연동 호출까지만 대신합니다. 아래 항목은 레시피 밖에서 앱이 구현합니다.

  • 연동 버튼과 연동된 로그인 수단 목록 화면
  • 연동 중 다른 계정 작업이 겹치지 않도록 하는 제어
  • 충돌이 생겼을 때 사용자에게 선택을 요청하는 화면
  • 저장해 둔 게스트 자격 증명의 삭제
  • 실패했을 때의 재시도 정책과 사용자 안내 메시지

레시피는 사용자를 대신해 계정을 고르지 않습니다. 다른 계정으로 로그인하거나 이미 연결된 로그인 수단을 끊는 동작은 사용자가 선택한 뒤에 앱이 실행합니다.

구현을 시작하기 전에 아래 항목을 먼저 준비하세요.

준비 항목 필수 여부 구분 확인할 곳
프로젝트 생성 필수 Hive 콘솔 프로젝트 생성
App ID 생성 필수 Hive 콘솔 App ID 생성
Unity 프로젝트에 SDK 연결 필수 Hive Axyl SDK Unity 프로젝트에 SDK 연결
로그인한 사용자 필수 레시피 코드 게스트 로그인 활용 가이드, 유저네임 로그인 활용 가이드, 커스텀 계정 로그인 활용 가이드

레시피는 활성 세션이 있을 때만 동작합니다. 활성 세션은 로그인을 마쳐 Hive Axyl SDK가 사용자를 식별하고 있는 상태를 뜻합니다. 로그인하지 않은 상태에서 호출하면 FailedPrecondition 오류로 실패하므로, 연동 버튼은 로그인한 사용자에게만 표시하세요.

사전 준비를 마쳤다면 외부 인증 제공자 연동 구현하기를 시작하세요.