Apple 로그인 구현하기

레시피 코드로 Apple 로그인을 구현하려면 아래 절차를 순서대로 완료하세요.

시작하기 전에 공통 사전 준비를 마치세요.

각 단계에서 무엇을 설정하고 무엇을 호출하는지는 아래와 같습니다. iOS와 macOS에서는 네이티브 방식을, Android와 Windows에서는 브라우저 방식을 사용합니다.

순서	구분	하는 일	대상 방식
1	외부 콘솔	Apple Developer에서 인증 정보 발급	전체
2	Hive 콘솔	인증 정보 등록과 Apple 로그인 활성화	전체
3	Hive Axyl SDK	인증 모듈과 로그인 Add-on 설치	전체
4	Hive Axyl SDK	SDK 초기화와 모듈 등록	전체
5	레시피 코드	공통·방식별 레시피 폴더 복사	전체
6	앱 코드	`ClientId`와 `DeviceKey` 준비	전체
7	레시피 코드, 앱 코드	Apple 자격 증명 소스 준비와 Hive Axyl 중계 주소 연결	전체
8	레시피 코드	Apple 로그인 호출	전체
9	앱 코드	로그인 결과 처리	전체
10	앱 코드	동작 확인	전체

이메일과 이름은 첫 로그인에만 내려옵니다

네이티브 방식에서 Apple은 사용자가 이 앱에 처음 로그인할 때만 이메일과 이름을 내려 줍니다. 다음 로그인에서 다시 요청해도 받지 못하므로, 두 값을 사용한다면 첫 로그인 결과를 반드시 저장하세요.

외부 콘솔 Apple Developer에서 설정합니다.

상세 절차: 로그인 연동

Apple Developer에서 로그인에 사용할 인증 정보를 먼저 발급받으세요. Hive Axyl 인증 서버가 Apple이 발급한 토큰을 검증하려면 이 값이 필요합니다.

Service ID, Team ID, 로그인용 키를 발급받은 뒤, 방식에 따라 아래 항목을 준비하세요.

방식	준비할 항목	확인할 곳
네이티브 방식	빌드에 사용할 Apple App ID와 프로비저닝 프로파일. 이 App ID는 Apple이 발급하는 값이며, Hive 콘솔에서 만드는 App ID와 다릅니다.	iOS와 macOS용 App ID와 프로비저닝 프로파일 준비
브라우저 방식	Service ID의 Return URL과 도메인. Return URL에는 Hive Axyl이 운영하는 중계 주소 `https://core-api.hiveaxyl.com/auth/v1/provider/callback`을, 도메인에는 이 주소의 도메인 `core-api.hiveaxyl.com`을 등록합니다. 이 주소가 인증 결과를 앱으로 전달하는 방식은 7.3을 참조하세요.	Service ID의 Return URL 등록

Hive 콘솔 Hive 콘솔에서 설정하거나 확인합니다.

상세 절차: Apple 로그인 인증 정보, 로그인 수단 종류

발급받은 인증 정보를 Hive 콘솔에 등록하고 Apple 로그인을 활성화하세요. 로그인 수단이 비활성 상태이면 레시피 호출이 거절됩니다.

설정 항목	필수 여부	확인할 곳
Apple 로그인 인증 정보 등록	필수	Apple 로그인 인증 정보
Apple 로그인 활성화	필수	로그인 수단 종류
App ID별 로그인 설정	선택	App ID별 로그인 설정

여기서 등록한 설정은 프로젝트에 속한 모든 App ID에 함께 적용됩니다. 특정 App ID에서만 다른 로그인 수단을 노출하려면 App ID별 로그인 설정을 사용하세요.

Hive Axyl SDK Hive Axyl SDK를 앱에서 호출합니다.

상세 절차: 모듈 설치, Add-on 설치, 앱별 추가 구현

인증 모듈과 지원할 방식의 Add-on을 Unity 프로젝트에 설치하세요. Add-on은 Apple 로그인 화면이나 브라우저 로그인 페이지를 여는 Hive Axyl SDK 확장 패키지이며, 7단계에서 준비하는 자격 증명 소스가 이 Add-on을 호출합니다.

패키지	필요 여부	역할
`com.com2usplatform.hiveaxyl.core`	필수	SDK 초기화와 로그인 세션 관리
`com.com2usplatform.hiveaxyl.auth`	필수	Apple 자격 증명으로 로그인, 토큰 발급
`com.com2usplatform.hiveaxyl.auth.addon.apple`	네이티브 방식에 필수	Apple 로그인 화면 표시
`com.com2usplatform.hiveaxyl.auth.addon.webauth`	브라우저 방식에 필수	브라우저 웹 로그인 세션 제공
`com.unity.nuget.newtonsoft-json`	브라우저 방식에 필수	`ProviderLogin.WebAuth/`의 JSON 처리
`com.com2usplatform.hiveaxyl.storage`	권장	`DeviceKey`와 세션 토큰의 암호화 저장

Add-on 패키지를 설치하지 않으면 그 Add-on을 사용하는 자격 증명 소스가 컴파일 대상에서 빠지므로 앱 코드에서 사용하지 못합니다. 두 방식을 모두 제공하면 두 Add-on을 모두 설치하세요.

네이티브 방식의 Apple 로그인 Add-on은 iOS 17.0 이상, macOS 15.0 이상에서 동작합니다. Unity 프로젝트의 최소 지원 OS 버전을 이 값 이상으로 설정하세요. 버전이 낮으면 빌드는 만들어지지만 실제 기기에서 로그인 화면이 뜨지 않습니다.

Hive Axyl SDK Hive Axyl SDK를 앱에서 호출합니다.

상세 절차: 모듈 초기화

앱 시작 지점에서 SDK를 한 번 초기화하고 인증, 토큰 모듈과 지원할 방식의 로그인 Add-on을 등록하세요. 레시피는 SDK를 초기화하지 않으므로, 초기화하지 않은 상태에서 호출하면 FailedPrecondition 오류로 실패합니다.

아래는 네이티브 방식과 브라우저 방식을 모두 지원하는 초기화 예제 코드입니다.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Auth.Addon.Apple;
using Hive.Axyl.Auth.Addon.WebAuth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;
using Hive.Axyl.Storage;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder
        .AddAuth()
        .AddToken()
        .AddSecureStorage()
        .AddAppleSignIn()
        .AddWebAuth();
});

{appId}에는 Hive 콘솔에서 만든 App ID를 입력하세요. 한 방식만 지원하면 사용하지 않는 Add-on의 using 구문과 등록 메서드를 함께 제거하세요.

AddAppleSignIn()은 iOS와 macOS에서만 실제로 등록되고, AddWebAuth()는 Android·iOS·macOS·Windows에서 모듈을 등록합니다. 두 메서드 모두 Unity 에디터에서는 등록을 건너뛰고 어느 OS에서 호출해도 오류가 나지 않으므로 분기 없이 등록해도 됩니다.

앱에서 이미 안전한 저장소를 사용한다면 AddSecureStorage()는 등록하지 않아도 됩니다. 이 경우에도 DeviceKey와 세션 토큰을 앱 재시작 뒤에 다시 읽을 수 있어야 합니다.

레시피 코드 레시피 코드를 프로젝트에 복사합니다.

레시피는 패키지가 아니라 프로젝트에 복사해서 사용하는 소스 코드입니다. axyl-samples-unity 저장소에서 아래 항목을 Unity 프로젝트의 Assets/Recipes/ 아래로 복사하세요.

복사할 항목과 역할은 아래와 같습니다.

Recipes.asmdef: 레시피 공통 어셈블리 정의
AssemblyInfo.cs: 내부 헬퍼를 다른 레시피 어셈블리에 공개하는 설정
Helper/: 여러 레시피가 함께 사용하는 공통 코드
ProviderLogin/: ProviderLoginRecipe, 결과 유형, 자격 증명 소스 계약
ProviderLogin.Apple/: 네이티브 방식의 AppleCredentialSource, AppleSignInOptions
ProviderLogin.WebAuth/: 브라우저 방식의 AppleWebCredentialSource와 브라우저 로그인 공통 코드

앱 코드에서 레시피를 호출하려면 앱 쪽 어셈블리 정의의 references에 아래 어셈블리를 추가하세요. 아래는 두 방식을 모두 지원하는 예입니다. 원본 Recipes.asmdef의 autoReferenced 값이 false이므로 앱 어셈블리가 자동으로 참조하지 않습니다.

MyApp.asmdef

{
  "name": "MyApp",
  "references": [
    "Hive.Axyl.Core",
    "Hive.Axyl.Auth",
    "Hive.Axyl.Auth.Addon.Apple",
    "Hive.Axyl.Auth.Addon.WebAuth",
    "Hive.Axyl.Storage",
    "Hive.Axyl.Samples.Recipes",
    "Hive.Axyl.Samples.Recipes.ProviderLogin",
    "Hive.Axyl.Samples.Recipes.ProviderLogin.Apple",
    "Hive.Axyl.Samples.Recipes.ProviderLogin.WebAuth"
  ]
}

MyApp은 앱에서 사용하는 어셈블리 이름으로 바꾸고, 기존 설정과 참조는 유지하세요. Unity 어셈블리는 참조를 전이하지 않으므로 앱 코드가 직접 사용하는 어셈블리를 모두 여기에 적어야 합니다. Hive.Axyl.Core에는 CoreConfig와 HiveError가, Hive.Axyl.Auth에는 AddAuth()와 AddToken()이, Hive.Axyl.Auth.Addon.Apple에는 AddAppleSignIn()이, Hive.Axyl.Auth.Addon.WebAuth에는 AddWebAuth()가, Hive.Axyl.Storage에는 AddSecureStorage()가 들어 있습니다. 한 방식만 사용하면 사용하지 않는 Add-on과 레시피 어셈블리 참조를 빼도 되고, AddSecureStorage()를 등록하지 않는다면 Hive.Axyl.Storage는 적지 않아도 됩니다.

방식별 레시피 폴더만 복사하면 컴파일되지 않습니다

AppleCredentialSource와 AppleWebCredentialSource는 ProviderLogin/의 자격 증명 소스 계약을 구현하고, ProviderLoginRecipe는 Helper/의 PKCE 생성 코드와 세션 준비 코드를 사용합니다. Helper/, Recipes.asmdef, AssemblyInfo.cs, ProviderLogin/을 방식별 폴더와 함께 복사하세요.

앱 코드 앱에서 직접 구현합니다.

상세 절차: Client ID, deviceKey

ProviderLoginRecipe의 생성자는 ClientId와 DeviceKey를 받습니다. ClientId는 공통 사전 준비에서 확인한 값으로, Hive 콘솔이 프로젝트마다 발급합니다. DeviceKey는 Hive Axyl 인증 서버가 로그인 세션을 기기 단위로 구분하는 값이며, 앱이 직접 만들어 보관합니다.

레시피는 DeviceKey를 만들거나 저장하지 않으므로, 아래 조건에 맞게 만들고 관리하세요.

기기마다 다른 값. UUID 같은 난수 권장
최초 실행 때 한 번 만들어 저장하고, 이후 모든 로그인에서 재사용하는 값
22자 이상 64자 이하의 길이
공백과 제어 문자를 제외한 ASCII 문자로만 이루어진 값

저장소를 읽지 못했다고 새 DeviceKey로 덮어쓰지 마세요

값이 사라진 것이 아니라 읽기에만 실패했을 수 있습니다. 먼저 저장소 접근 문제를 해결하거나 다시 읽기를 시도하세요.

PKCE 값과 nonce는 준비하지 않아도 됩니다. 레시피가 호출할 때마다 Hive Axyl 인증 서버용 PKCE 값 한 쌍을 만들어 로그인 호출과 토큰 발급 호출에 나누어 전달하고, 네이티브 방식의 nonce는 자격 증명 소스가 만듭니다. 브라우저 방식의 Apple 인가 요청에는 PKCE를 넣지 않으며, 콜백이 이번 로그인 요청의 응답인지 확인하는 state 값도 자격 증명 소스가 직접 만들고 검증합니다.

빈 값을 전달하면 예외가 발생합니다

ClientId나 DeviceKey가 비어 있으면 레시피는 결과를 반환하지 않고 ArgumentException을 던집니다. 자격 증명 소스를 null로 전달할 때도 ArgumentNullException을 던집니다. 저장소에서 읽은 값을 그대로 넘기기 전에 비어 있는지 먼저 확인하세요.

레시피 코드 레시피 코드를 앱에서 호출합니다.

앱 코드 앱에서 직접 구현합니다.

상세 절차: Apple 자격 증명 획득

레시피에 로그인할 외부 인증 제공자를 알려 주려면 자격 증명 소스를 만들어 전달해야 합니다. 자격 증명 소스는 Apple 로그인 화면이나 브라우저 로그인 페이지를 열어 사용자 식별자와 인증 결과를 받아오는 객체이며, 실행 중인 OS에 맞는 소스를 골라 만드세요.

iOS와 macOS에서는 AppleCredentialSource를 사용합니다. AppleSignInOptions로 Apple에 무엇을 요청할지 지정하며, 아래 예제 코드는 이메일과 이름을 함께 요청합니다.

Unity

using Hive.Axyl.Samples.Recipes;

var appleOptions = new AppleSignInOptions
{
    RequestEmail = true,
    RequestFullName = true,
};

IProviderCredentialSource source = new AppleCredentialSource(appleOptions);

식별자만 필요하다면 new AppleCredentialSource()로 만드세요. 인자를 생략하면 이메일과 이름을 요청하지 않습니다. 이메일과 이름을 요청했다면 첫 로그인 결과를 앱이 저장해 두세요.

Android와 Windows에서는 AppleWebCredentialSource를 사용합니다. 이 소스는 웹 로그인 세션으로 Apple 로그인 페이지를 열고, 7.3의 Hive Axyl 중계 주소가 전달한 인가 코드를 Hive Axyl 인증 서버에서 Apple 자격 증명으로 교환합니다. 아래 값으로 WebAuthOptions와 소스를 만드세요.

값	넣는 곳	준비 방법
Apple 인가 엔드포인트	`WebAuthOptions.Create()`의 `authorizeEndpoint`	`https://appleid.apple.com/auth/authorize`입니다. Apple의 Request an authorization to the Sign in with Apple server를 참조하세요.
Service ID	`WebAuthOptions.Create()`의 `clientId`	1단계에서 발급받은 값
Hive Axyl 중계 주소	`WebAuthOptions.Create()`의 `redirectUri`	1단계에서 Service ID의 Return URL로 등록한 `https://core-api.hiveaxyl.com/auth/v1/provider/callback`
앱 콜백 주소	`AppleWebCredentialSource`의 두 번째 인자	Android에서만 전달합니다. `{appId}://oauth-callback` 형식이며, `{appId}`에는 Android 패키지 이름이 아니라 Hive 콘솔에서 만든 App ID를 넣습니다. Windows에서는 레시피가 로컬 주소를 직접 예약하므로 생략합니다.

Unity

using Hive.Axyl.Samples.Recipes;

var appleWebOptions = WebAuthOptions.Create(
    "https://appleid.apple.com/auth/authorize",
    "{appleServiceId}",
    "https://core-api.hiveaxyl.com/auth/v1/provider/callback");

// Android: 앱 콜백 주소를 함께 전달합니다.
IProviderCredentialSource source =
    new AppleWebCredentialSource(appleWebOptions, "{appId}://oauth-callback");

// Windows: 앱 콜백 주소를 생략합니다.
// IProviderCredentialSource source = new AppleWebCredentialSource(appleWebOptions);

Apple의 인가 코드는 Hive Axyl 인증 서버가 교환하므로 tokenEndpoint는 지정하지 마세요. tokenEndpoint를 지정했거나, redirectUri가 HTTPS 주소가 아니거나 로컬 주소이거나 # 조각을 포함하면 AppleWebCredentialSource 생성자가 ArgumentException을 발생시킵니다. 앱 콜백 주소가 절대 URI가 아니거나 #나 | 문자를 포함해도, WebAuthOptions.Create()에 빈 값을 넣어도 ArgumentException이 발생합니다. 이 예제는 Scope를 지정하지 않으므로 이메일과 이름을 요청하지 않습니다.

브라우저 방식에서 Apple은 인증 결과를 HTTP POST 요청으로 Return URL에 보내므로, 앱이 이 결과를 직접 받을 수 없습니다. 그래서 1단계에서 Return URL로 등록한 Hive Axyl 중계 주소가 결과를 받아 앱에 전달하고, 인가 코드 교환에 필요한 client secret은 Hive Axyl 인증 서버가 2단계에서 등록한 Private Key로 만듭니다. 앱 서버에서 인증 결과를 중계하거나 client secret을 만들지 않아도 됩니다. Private Key는 Hive 콘솔에만 등록하고 앱이나 앱 서버에 두지 마세요. Apple 인가 요청부터 인가 코드 교환까지의 순서는 아래와 같습니다.

레시피가 결과를 돌려받을 곳을 state 앞에 접두사로 붙여 Apple 인가를 요청합니다. Android에서는 <앱 콜백 주소>|를, Windows에서는 레시피가 예약한 로컬 주소의 <포트>:를 붙입니다.
Apple이 Hive Axyl 중계 주소로 code 또는 error와 state를 보냅니다.
Hive Axyl 중계 주소가 접두사에서 전달할 곳을 찾고, 접두사를 뺀 state와 code 또는 error를 쿼리 파라미터로 붙여 앱 콜백 주소나 로컬 주소로 전달합니다.
레시피가 돌아온 state가 이번 요청의 값과 같은지 확인한 뒤 인가 코드를 교환합니다. 이때 인가 요청에 사용한 Hive Axyl 중계 주소를 리다이렉트 URI로 함께 보냅니다.

Android에서는 앱 콜백 주소의 스킴인 App ID를 WebAuth Add-on의 콜백 화면이 받도록 앱에 등록하세요. 등록하지 않으면 Hive Axyl 중계 주소가 보낸 결과가 앱에 도착하지 않아 로그인이 끝나지 않습니다. 등록 방법은 Android 리다이렉트 URI 준비를 참조하고, 다른 로그인 수단이 이미 다른 스킴을 사용한다면 여러 스킴 등록에 따라 두 스킴을 모두 등록하세요. Windows에서는 레시피가 로컬 주소를 직접 예약하므로 등록하지 않아도 됩니다.

두 방식을 모두 지원한다면 조건부 컴파일로 실행 OS에 맞는 소스를 고르세요. appleOptions는 7.1에서, appleWebOptions는 7.2에서 만든 값입니다.

Unity

using Hive.Axyl.Samples.Recipes;

IProviderCredentialSource source;

#if UNITY_IOS || UNITY_STANDALONE_OSX
source = new AppleCredentialSource(appleOptions);
#elif UNITY_ANDROID
source = new AppleWebCredentialSource(appleWebOptions, "{appId}://oauth-callback");
#else
source = new AppleWebCredentialSource(appleWebOptions);
#endif

한 방식만 지원한다면 그쪽 소스만 만들면 됩니다.

레시피 코드 레시피 코드를 앱에서 호출합니다.

준비한 자격 증명 소스를 LoginWithProviderAsync()에 전달하세요. 레시피가 Apple 로그인 화면이나 브라우저 로그인 페이지를 열어 자격 증명을 받고, 그 자격 증명으로 로그인해 세션까지 활성화합니다.

사용자가 화면을 닫거나 로그인을 취소할 때 기다리기를 멈출 수 있도록 CancellationTokenSource를 함께 준비하세요.

Unity

using System.Threading;
using Hive.Axyl.Samples.Recipes;

var recipe = new ProviderLoginRecipe(clientId, deviceKey);

var cancellation = new CancellationTokenSource();
CancellationToken token = cancellation.Token;

LoginWithProviderOutcome outcome = await recipe.LoginWithProviderAsync(source, token);

화면을 닫거나 사용자가 취소를 선택할 때 cancellation.Cancel()을 호출하고, 호출이 끝나면 cancellation.Dispose()로 정리하세요.

Windows 브라우저 방식에서는 외부 브라우저를 사용하므로 사용자가 브라우저를 닫아도 레시피가 이를 감지하지 못하고 계속 기다립니다. 로그인 화면에 취소 버튼을 두어 cancellation.Cancel()을 호출하거나, new CancellationTokenSource(TimeSpan.FromMinutes(5))처럼 제한 시간을 지정하세요. TimeSpan을 사용하려면 using System;을 추가하세요.

레시피가 내부에서 수행하는 작업은 아래와 같습니다.

구분	호출	확인할 곳
레시피 코드	인증, 토큰, 세션 모듈이 등록되었는지 확인	없음
Add-on	네이티브 방식: `nonce`를 만들어 Apple 로그인 화면을 띄우고 `ProviderUserId`와 `ProviderToken` 확보	iOS와 macOS
Add-on	Windows 브라우저 방식: `AllocateLoopbackRedirectUriAsync()`로 콜백을 받을 로컬 주소 예약	리다이렉트 URI 준비
레시피 코드	브라우저 방식: `state`를 만들고 7.3의 접두사를 붙여 Apple 인가 URL 구성	iOS와 macOS 외 OS
Add-on	브라우저 방식: `OpenAsync()`로 Apple 로그인 페이지를 열고 Hive Axyl 중계 주소가 전달한 콜백 수신	웹 로그인 세션 열기
레시피 코드	브라우저 방식: 콜백의 `state`를 검증하고 인가 코드 확보	iOS와 macOS 외 OS
Hive Axyl SDK	브라우저 방식: `ExchangeProviderTokenAsync()`로 인가 코드를 `ProviderUserId`와 `ProviderToken`으로 교환. `RedirectUri`에는 인가 요청에 사용한 Hive Axyl 중계 주소를 넣고 `CodeVerifier`는 보내지 않음	외부 인증 코드 교환
레시피 코드	PKCE 값 한 쌍을 만들어 로그인 호출과 토큰 발급 호출에 나눠 전달	호출 파라미터값 준비
Hive Axyl SDK	`LoginProviderAsync()`로 Apple 자격 증명을 전달하고 인가 코드 수신	외부 인증 제공자 로그인
Hive Axyl SDK	`IssueTokenAsync()`로 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환	토큰 발급과 세션 활성화
Hive Axyl SDK	`SetSession()`으로 로그인 세션 활성화	토큰 발급과 세션 활성화

위 표의 상세 절차는 Hive Axyl SDK 메서드를 직접 호출할 때를 기준으로 쓰여 있습니다. nonce, state, PKCE 값을 만드는 작업처럼 레시피가 대신하는 단계는 앱에서 다시 구현하지 마세요. 각 호출이 무엇을 주고받는지 확인할 때만 참조하세요.

모듈이 등록되어 있지 않으면 첫 단계에서 FailedPrecondition 오류로 멈춥니다. Success가 반환되면 세션까지 준비된 상태이므로 토큰 발급이나 세션 활성화 코드를 따로 호출하지 마세요. 세션은 사용할 수 있는 토큰을 받은 뒤에만 활성화되므로, 실패한 시도는 이미 열려 있던 세션을 건드리지 않습니다.

앱 코드 앱에서 직접 구현합니다.

상세 절차: HiveError 정보

LoginWithProviderOutcome은 Status로 로그인 결과를 알려 줍니다. FailedStep은 진단용 값이므로 앱의 정상 흐름을 분기하는 기준으로 사용하지 마세요.

`Status`	확인할 값	앱 처리
`Success`	`PlayerId`, `IsBlocked`	이용 제한 상태가 아니면 로그인 후 화면으로 이동합니다.
`BusinessOutcome`	`BusinessOutcome`, `UnknownOutcomeCode`	거절 사유에 맞게 분기하고, 모르는 값은 실패로 처리해 기록합니다.
`UserCanceled`	없음	사용자가 Apple 로그인 화면을 닫거나 동의를 거부했거나, Android에서 브라우저 로그인 페이지를 닫은 상태이므로 이전 화면으로 돌아갑니다.
`Failure`	`Error.Code`, `Error.TraceId`	기술 문제를 기록하고 재시도 흐름을 제공합니다.

IsBlocked가 true이면 로그인은 성공했지만 이용이 제한된 계정입니다. 제한 종류와 안내 방법은 이용 제한을 참조하세요.

PlayerId는 Hive Axyl이 사용자 한 명에게 부여하는 고유 식별자입니다. 같은 Apple 계정으로 다시 로그인하면 같은 값이 돌아오므로, 앱은 이 값으로 사용자의 플레이 데이터를 구분합니다.

오류를 기록할 때는 FailedStep을 함께 남기세요. 값은 None, Resolve, AcquireCredential, LoginProvider, SessionSetup 다섯 가지이며, 어느 단계에서 멈췄는지 알려 줍니다.

BusinessOutcome 값은 Hive Axyl 인증 서버가 로그인을 거절한 사유이므로, 값마다 사용자에게 보여 줄 안내가 다릅니다. 레시피는 로그인 호출, 토큰 발급 호출, 브라우저 방식의 외부 인증 코드 교환 호출에서 나온 거절 사유를 하나의 값으로 묶어 돌려주므로 해당하는 곳을 모두 확인하세요.

ExchangeProviderTokenAsync(): 외부 인증 코드 교환 응답 상태. 브라우저 방식에서만 호출
LoginProviderAsync(): 외부 인증 제공자 로그인 응답 상태
IssueTokenAsync(): 액세스 토큰과 리프레시 토큰 발급

레시피는 상세 절차에 적힌 이름을 아래와 같이 바꿔 돌려줍니다.

TerminateService: ServiceTerminated
InvalidClientId: InvalidClient
InvalidGrant: InvalidAuthorizationCode
InvalidGrantExpired: ExpiredAuthorizationCode
InvalidGrantCodeChallenge: CodeChallengeMismatch
InvalidGrantRefreshToken: InvalidRefreshToken

TemporarilyUnavailable은 다시 시도하면 성공할 수 있는 유일한 거절 사유입니다. 곧바로 반복하지 말고 1초, 3초, 6초처럼 간격을 늘려 가며 재시도하세요.

취소와 미지원 환경은 로그인이 거절된 것이 아니므로 실패로 안내하지 마세요. 상황별 레시피 결과와 앱 처리는 아래와 같습니다.

상황	레시피 결과	앱 처리
사용자가 Apple 로그인 화면을 닫거나 동의를 거부함	`UserCanceled`	이전 화면으로 돌아감
Android에서 사용자가 브라우저 로그인 페이지를 닫음	`UserCanceled`	이전 화면으로 돌아감
사용자가 브라우저 로그인 페이지에서 취소를 선택함	`Failure`와 `Internal`	로그인 화면을 유지하고 다시 시도할 수 있게 함
Windows에서 사용자가 브라우저를 닫음	결과가 돌아오지 않음	8단계의 취소 버튼이나 제한 시간으로 대기 종료
앱이 `CancellationToken`으로 대기를 취소함	`Failure`와 `Cancelled`	진행 중인 로그인 화면을 정리하고 로그인 화면 유지
방식에 필요한 Add-on이 등록되지 않은 OS에서 호출함	`Failure`와 `Unavailable`	다른 로그인 수단 제시
Android에서 앱 콜백 주소 없이 브라우저 방식을 호출함	`Failure`와 `FailedPrecondition`	7.2의 앱 콜백 주소 전달 확인
콜백의 `state`가 현재 로그인 요청과 다름	`Failure`와 `PermissionDenied`	이번 로그인에서 시작하지 않은 콜백이므로 로그인 화면을 유지하고 다시 시도할 수 있게 함

UnknownOutcomeCode와 RawJson은 사용자에게 표시하지 마세요. 앱 오류 기록이 필요한 경우에만 사용하고, 모르는 결과를 이미 아는 결과로 추정하지 마세요.

앱 코드 앱에서 동작을 확인합니다.

지원하는 OS의 실제 기기와 빌드에서 Apple 로그인을 확인하세요. 네이티브 방식은 iOS나 macOS에서, 브라우저 방식은 Android나 Windows에서 확인합니다. Unity 에디터에서는 두 Add-on 모두 등록되지 않아 Unavailable 오류가 반환되므로 로그인 화면부터 검증할 수 없습니다.

앱을 실행하고 Apple 로그인을 실행하세요.
Apple 로그인 화면이나 브라우저 로그인 페이지가 뜨는지 확인하고 로그인을 완료하세요. Android에서 로그인을 마친 뒤 앱으로 돌아오지 않으면 7.3의 앱 콜백 스킴 등록을 확인하세요.
Success와 PlayerId를 확인하고 로그인 후 화면으로 넘어가는지 확인하세요.
앱을 완전히 종료한 뒤 다시 실행해 같은 Apple 계정으로 로그인하고, PlayerId가 같은지 확인하세요.
네이티브 방식에서는 Apple 로그인 화면을 닫아, Android에서는 브라우저 로그인 페이지를 닫아 UserCanceled가 반환되는지 확인하세요. Windows에서는 취소 버튼이나 제한 시간으로 Failure와 Cancelled가 반환되는지 확인하세요.

로그인한 사용자가 앱을 다시 실행할 때 로그인 화면을 건너뛰도록 하려면 자동 로그인을 참조하세요.

이미 로그인한 계정에 다른 로그인 수단을 추가로 연결하려면 외부 인증 제공자 연동 활용 가이드를 참조하세요.

로그인한 계정에서 빠져나와 다른 계정으로 로그인하도록 하려면 로그아웃 활용 가이드를 참조하세요.

Apple 로그인 구현하기

전체 흐름

1. Apple Developer 설정

2. Hive 콘솔 설정

3. SDK 모듈과 Add-on 설치

4. SDK 초기화

5. 레시피 코드 설치

6. ClientId와 DeviceKey 준비

7. Apple 자격 증명 소스 준비

7.1. 네이티브 방식

7.2. 브라우저 방식

7.3. Hive Axyl 중계 주소

7.4. 방식에 따라 소스 고르기

8. Apple 로그인 호출

9. 로그인 결과 처리

9.1. 거절 사유 처리

9.2. 취소와 미지원 환경 처리

10. 동작 확인

다음 단계