Google 로그인 활용 가이드
Google 로그인은 사용자가 자신의 Google 계정으로 앱에 로그인하도록 하는 기능입니다. Google은 사용자를 인증하고, 앱은 인증 결과로 Hive Axyl 로그인 세션을 얻습니다. 세션이 활성화되면 Hive Axyl SDK가 로그인한 사용자를 식별할 수 있습니다.
구현하려면 Google 외부 콘솔 설정, Hive 콘솔 설정, Hive Axyl SDK와 로그인 Add-on 설치, 레시피 코드 호출, 앱 코드를 순서대로 구성해야 합니다. 레시피를 사용하면 Google 자격 증명 획득부터 Hive Axyl 로그인 세션 활성화까지의 호출을 하나로 묶을 수 있습니다.
Android에서는 Google 계정 선택 화면을 제공하는 Credential Manager 방식을 사용하고, iOS·macOS·Windows에서는 브라우저를 사용하는 웹 로그인 세션 방식을 사용합니다.
구현 범위
Google 로그인을 구현하는 데 필요한 작업은 Google Cloud Console에서 인증 정보를 준비하는 것에서 시작해, 앱에서 로그인 결과를 처리하는 것으로 끝납니다.
각 단계의 작업은 아래 여섯 가지 구분 중 하나에 해당합니다.
| 구분 | 담당 | 내용 |
|---|---|---|
| 외부 콘솔 | 앱 운영자 | Google Cloud Console에서 수행하는 설정입니다. |
| Hive 콘솔 | 앱 운영자 | Hive 콘솔에서 Google 로그인을 활성화하고 인증 정보를 등록하는 설정입니다. |
| Hive Axyl SDK | 앱 개발자 | 인증, 토큰, 세션 모듈을 설치하고 초기화하는 작업과 로그인에 사용하는 SDK 메서드입니다. |
| Add-on | 앱 개발자 | Android 계정 선택 화면과 브라우저 인증 세션을 제공하는 Hive Axyl SDK 확장 패키지입니다. |
| 레시피 코드 | 앱 개발자 | Google 자격 증명 획득부터 세션 활성화까지의 호출을 묶은 소스 코드입니다. |
| 앱 코드 | 앱 개발자 | 로그인 화면, OS별 소스 선택, 설정값 보관, 결과별 화면 처리를 직접 구현하는 부분입니다. |
이 활용 가이드에는 Hive Axyl Server API를 직접 호출하는 단계가 없습니다. 브라우저 방식에서 WebAuthOptions의 tokenEndpoint를 비워 두면 레시피가 Hive Axyl SDK의 ExchangeProviderTokenAsync()를 호출하고, 값을 지정하면 레시피가 Google의 토큰 엔드포인트와 직접 통신합니다. 두 방식 모두 앱이 Hive Axyl Server API 엔드포인트를 직접 호출하지 않습니다.
레시피
Hive Axyl SDK는 Google 자격 증명 획득, 외부 인증 코드 교환, Hive Axyl 로그인, 토큰 발급, 세션 활성화를 각각 다른 호출로 제공합니다. 레시피는 이 순서를 조합해 LoginWithProviderAsync() 한 번으로 실행합니다.
레시피는 패키지가 아니라 프로젝트에 복사해서 사용하는 순수 C# 소스 코드입니다. Google 로그인에는 Android 네이티브 방식과 브라우저 방식이 있으므로 앱이 지원할 방식의 자격 증명 소스만 함께 복사하세요.
| 구분 | 위치 | 성격 |
|---|---|---|
| Hive Axyl SDK | Unity 패키지 com.com2usplatform.hiveaxyl.* | 설치해서 사용합니다. 인증 기능을 세분화된 메서드로 제공합니다. |
| 공통 레시피 | Assets/Recipes/ProviderLogin/ | ProviderLoginRecipe와 결과 유형, 자격 증명 소스를 사용하는 공통 코드를 제공합니다. |
| Android 레시피 | Assets/Recipes/ProviderLogin.CredentialManager/ | GoogleCredentialManagerCredentialSource를 제공합니다. |
| 브라우저 레시피 | Assets/Recipes/ProviderLogin.WebAuth/ | GoogleCredentialSource와 웹 로그인 세션 공통 코드를 제공합니다. |
| 사용 예제 | Assets/RecipeExamples/Authentication/ProviderLoginExample.cs | 읽고 참고하는 코드입니다. 모든 외부 인증 제공자에 공통인 로그인 흐름과 결과별로 앱이 구현해야 할 부분을 주석으로 설명합니다. |
Google 로그인은 두 자격 증명 소스를 제공합니다
GoogleCredentialManagerCredentialSource는 Android Credential Manager에서 id_token을 받아 오므로 외부 인증 코드 교환이 필요하지 않습니다. GoogleCredentialSource는 브라우저 콜백의 인가 코드를 처리한 뒤 Google 자격 증명을 만들어 줍니다. 앱은 실행 환경과 배포 정책에 맞는 소스를 선택해 ProviderLoginRecipe에 전달하세요.
레시피 지원 OS
Google 로그인은 OS에 따라 자격 증명을 얻는 방법이 다릅니다. Android에서는 Credential Manager 방식을, 그 밖의 지원 OS에서는 웹 로그인 세션 방식을 사용하세요.
| OS | 인증 방식 | 자격 증명 소스 | 구현 방법 |
|---|---|---|---|
| Android | Android Credential Manager 계정 선택 화면 | GoogleCredentialManagerCredentialSource | 이 가이드의 Android 절차를 따릅니다. |
| iOS, macOS, Windows | 브라우저 웹 로그인 세션 | GoogleCredentialSource | 이 가이드의 브라우저 절차를 따릅니다. |
Android에서 브라우저 방식만 제공하려면 Credential Manager Add-on을 설치하지 않고 GoogleCredentialSource를 사용할 수 있습니다. 이 경우에도 WebAuth Add-on과 플랫폼별 리다이렉트 URI 설정이 필요합니다.
앱이 직접 구현하는 부분
레시피는 자격 증명 획득부터 세션 활성화까지만 대신합니다. 아래 항목은 앱에서 구현하세요.
- 로그인 화면과 로그인 후 화면 전환
- 실행 환경에 맞는 Google 자격 증명 소스 선택
- Google OAuth 클라이언트 ID, 인가 엔드포인트, Scope, 리다이렉트 URI 보관
- 브라우저 방식에서 OS별 리다이렉트 URI 준비
DeviceKey의 생성과 보관- 로그인으로 받은 세션 토큰의 보관
- 로그인 결과에 따른 재시도와 사용자 안내
Android Credential Manager 방식에서 사용하는 웹 애플리케이션 유형 OAuth 클라이언트 ID와 브라우저 방식에서 WebAuthOptions.ClientId에 넣는 제공자 클라이언트 ID는 용도가 다를 수 있습니다. Hive Axyl SDK의 ClientId와도 다른 값이므로 각 값을 섞지 마세요.
공통 사전 준비
구현을 시작하기 전에 아래 항목을 먼저 준비하세요.
| 준비 항목 | 필수 여부 | 구분 | 확인할 곳 |
|---|---|---|---|
| Google Cloud Console의 OAuth 클라이언트 | 필수 | 외부 콘솔 | Google 로그인 인증 정보 확인 |
| 프로젝트 생성 | 필수 | Hive 콘솔 | 프로젝트 생성 |
| App ID 생성 | 필수 | Hive 콘솔 | App ID 생성 |
| Google 로그인 인증 정보 등록과 활성화 | 필수 | Hive 콘솔 | Google 로그인 인증 정보, 로그인 수단 종류 |
| Client ID 확인 | 필수 | Hive 콘솔 | 보안 키 획득 |
| Unity 프로젝트에 SDK 연결 | 필수 | Hive Axyl SDK | Unity 프로젝트에 SDK 연결 |
Google Cloud Console에서는 브라우저 교환에 사용할 웹 애플리케이션 유형 OAuth 클라이언트와 Android 앱의 패키지 이름·서명을 확인하는 Android 유형 OAuth 클라이언트를 준비하세요. Android Credential Manager 레시피에는 웹 애플리케이션 유형 클라이언트 ID를 전달합니다. Client Secret은 앱에 포함하지 않습니다.
App ID는 SDK를 초기화할 때 사용하고 Hive Axyl Client ID는 레시피를 만들 때 사용합니다. Google OAuth 클라이언트 ID는 Google에서 발급받아 자격 증명 소스에 전달하는 별도 값입니다.
다음 단계
사전 준비를 마쳤다면 Google 로그인 구현하기를 시작하세요.