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