Apple 로그인 활용 가이드
Apple 로그인은 사용자가 자신의 Apple 계정으로 앱에 로그인하도록 하는 기능입니다. Apple은 사용자를 대신 인증해 주는 외부 인증 제공자이며, 사용자는 Apple이 그려 주는 로그인 화면에서 인증하고 앱은 그 결과로 Hive Axyl 로그인 세션을 얻습니다. 세션은 로그인을 마쳐 Hive Axyl SDK가 사용자를 식별하고 있는 상태를 뜻합니다.
구현하려면 Apple Developer 설정, Hive 콘솔 설정, Hive Axyl SDK 호출, 레시피 코드 호출, 앱 코드를 조합해야 합니다. 레시피 코드를 사용하면 자격 증명 획득부터 세션 활성화까지 필요한 호출이 메서드 하나로 줄어듭니다.
구현 범위
Apple 로그인을 구현하는 데 필요한 작업은 Apple Developer에서 인증 정보를 발급받는 것에서 시작해, 로그인 결과에 맞는 화면을 띄우는 것으로 끝납니다.
각 단계의 작업은 아래 여섯 가지 구분 중 하나에 해당합니다.
| 구분 | 담당 | 내용 |
|---|---|---|
| 외부 콘솔 | 앱 운영자 | Apple Developer에서 수행하는 설정입니다. |
| Hive 콘솔 | 앱 운영자 | Hive 콘솔에서 수행하는 설정입니다. |
| Hive Axyl SDK | 앱 개발자 | 앱에서 호출하는 Hive Axyl SDK 메서드입니다. |
| Add-on | 앱 개발자 | Apple 로그인 화면이나 브라우저 로그인 페이지를 여는 Hive Axyl SDK 확장 패키지입니다. |
| 레시피 코드 | 앱 개발자 | 앱에서 호출하는 레시피 메서드입니다. |
| 앱 코드 | 앱 개발자 | Hive Axyl을 거치지 않고 앱이 직접 구현하는 부분입니다. |
Apple 로그인에는 Hive Axyl 서버 API 호출이 없습니다. Add-on은 앱이 직접 호출하지 않고 레시피가 대신 호출하므로, 단계 구분이 아니라 레시피가 내부에서 수행하는 작업 목록에 나타납니다. 파라미터의 의미와 응답 필드는 각 단계에서 연결한 상세 절차를 참조하세요.
레시피
Hive Axyl SDK는 로그인 기능을 세분화된 메서드로 제공합니다. Apple에서 자격 증명을 받는 Add-on 호출, 브라우저 방식에서 인가 코드를 자격 증명으로 바꾸는 메서드, 그 자격 증명으로 로그인하는 메서드, 토큰을 발급하는 메서드, 세션을 활성화하는 메서드가 각각 따로 있습니다. 사용자 한 명을 로그인시키는 데에도 호출 순서와 중간 실패 처리를 앱이 직접 조합해야 합니다.
레시피는 그 조합을 미리 완성해 둔 소스 코드입니다. 패키지가 아니라 프로젝트에 복사해서 사용합니다.
| 구분 | 위치 | 성격 |
|---|---|---|
| Hive Axyl SDK | Unity 패키지 com.com2usplatform.hiveaxyl.* | 설치해서 사용합니다. 인증 기능을 세분화된 메서드로 제공합니다. |
| 공통 레시피 | Assets/Recipes/ProviderLogin/ | 복사해서 사용합니다. ProviderLoginRecipe와 결과 유형, 자격 증명 소스를 사용하는 공통 코드를 제공합니다. |
| 네이티브 레시피 | Assets/Recipes/ProviderLogin.Apple/ | iOS와 macOS에서 사용하는 AppleCredentialSource를 제공합니다. |
| 브라우저 레시피 | Assets/Recipes/ProviderLogin.WebAuth/ | Android와 Windows에서 사용하는 AppleWebCredentialSource와 브라우저 로그인 공통 코드를 제공합니다. |
| 사용 예제 | Assets/RecipeExamples/Authentication/ProviderLoginExample.cs | 읽고 참고하는 코드입니다. 모든 외부 인증 제공자에 공통인 로그인 흐름과 결과별로 앱이 구현해야 할 부분을 주석으로 설명합니다. |
레시피는 복사해서 사용하는 코드입니다
레시피는 앱에 복사되어 앱의 코드가 됩니다. 그대로 사용해도 되고 앱 정책에 맞게 수정해서 사용해도 됩니다.
로그인 레시피는 외부 인증 제공자 하나에 종속되지 않습니다. Apple 자격 증명을 받아 오는 부분만 ProviderLogin.Apple/과 ProviderLogin.WebAuth/가 담당하고, 그 뒤 과정은 Google이나 Steam 로그인과 같은 코드를 사용합니다.
레시피 지원 OS
Apple 로그인은 OS에 따라 자격 증명을 얻는 방법이 다르므로, 앱이 실행 중인 OS에 맞는 자격 증명 소스를 골라 레시피에 전달합니다. 자격 증명 소스는 Apple 로그인 화면이나 브라우저 로그인 페이지를 열어 사용자 식별자와 인증 결과를 받아오는 객체입니다.
| OS | 인증 방식 | 자격 증명 소스 | 구현 방법 |
|---|---|---|---|
| iOS, macOS | Apple이 그리는 네이티브 로그인 화면 | AppleCredentialSource | 네이티브 방식 |
| Android, Windows | 브라우저에서 여는 Apple 로그인 페이지 | AppleWebCredentialSource | 브라우저 방식 |
브라우저 방식에서는 Apple이 인증 결과를 앱이 아니라 Apple Developer에 등록한 HTTPS 주소로 보냅니다. 이 HTTPS 주소에는 Hive Axyl이 운영하는 중계 주소를 등록합니다. 중계 주소는 받은 결과를 앱으로 전달합니다. 방식에 필요한 Add-on이 등록되지 않은 OS에서 소스를 호출하면 Unavailable 오류를 반환하며, 이는 로그인이 거절된 것이 아니라 그 환경에서 해당 방식으로 Apple 로그인을 실행하지 못한다는 뜻입니다.
앱이 직접 구현하는 부분
레시피는 자격 증명 획득부터 세션 활성화까지만 대신합니다. 아래 항목은 레시피 밖에서 앱이 구현합니다.
- 로그인 화면과 로그인 후 화면 전환
- OS에 맞는 자격 증명 소스 선택
- Android 브라우저 방식에서 결과를 받을 앱 콜백 스킴 등록
DeviceKey의 생성과 보관- 로그인으로 받은 세션 토큰의 보관
- 네이티브 방식에서 Apple이 첫 로그인에만 내려 주는 이메일과 이름의 보관
- 실패했을 때의 재시도 정책과 사용자 안내 메시지
공통 사전 준비
구현을 시작하기 전에 아래 항목을 먼저 준비하세요.
| 준비 항목 | 필수 여부 | 구분 | 확인할 곳 |
|---|---|---|---|
| 프로젝트 생성 | 필수 | Hive 콘솔 | 프로젝트 생성 |
| App ID 생성 | 필수 | Hive 콘솔 | App ID 생성 |
| Store App ID 등록 | 필수 | Hive 콘솔 | Store App ID 등록 |
| Client ID 확인 | 필수 | Hive 콘솔 | 보안 키 획득 |
| Unity 프로젝트에 SDK 연결 | 필수 | Hive Axyl SDK | Unity 프로젝트에 SDK 연결 |
App ID는 SDK를 초기화할 때 입력하고 Client ID는 로그인할 때 입력하므로 둘 다 먼저 확인해야 합니다. Store App ID는 Hive Axyl이 App Store와 연동할 때 기준으로 삼는 값이므로 Apple Developer 설정보다 먼저 등록해야 합니다. SDK를 연결해 두어야 이어지는 단계에서 인증 모듈과 Add-on을 설치합니다.
다음 단계
사전 준비를 마쳤다면 Apple 로그인 구현하기를 시작하세요.