Apple 로그인 Add-on

iOS와 macOS에서 Apple의 ASAuthorizationController로 Apple 로그인 화면을 띄우고, Apple이 발급한 자격 증명을 가공하지 않고 반환하는 Add-on입니다. 반환된 사용자 식별자와 아이덴티티 토큰을 Auth 모듈의 LoginProviderAsync()에 넘겨 Hive Axyl 계정으로 로그인합니다.

모듈 정보

• 패키지: com.com2usplatform.hiveaxyl.auth.addon.apple
• 인터페이스: IAppleSignInPlugin
• 네임스페이스: Hive.Axyl.Auth.Addon.Apple
• 등록 메서드: AddAppleSignIn()
• 지원 플랫폼: iOS, macOS
• 최소 사양: iOS 17+, macOS 15+, Unity 6000.0+

사전 준비

이 Add-on을 설치하면 빌드할 때 생성되는 Xcode 프로젝트에 Sign in with Apple 엔타이틀먼트가 자동으로 추가됩니다. macOS에서는 Xcode 프로젝트를 생성하도록 빌드해야 엔타이틀먼트가 추가됩니다. 하지만 Apple Developer에서 App ID의 Sign in with Apple 기능을 활성화하고 그에 맞는 프로비저닝 프로파일을 발급하는 작업은 직접 해야 합니다. 이 작업 없이 서명한 빌드는 실행할 때 시스템이 거부합니다.

설정 방법은 iOS와 macOS용 App ID와 프로비저닝 프로파일 준비를 참조하세요.

등록과 획득

HiveBootstrap.Initialize의 등록 단계에서 등록한 뒤 HiveCore.TryResolve<T>()로 가져옵니다.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Auth.Addon.Apple;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

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

if (HiveCore.TryResolve<IAppleSignInPlugin>(out var apple))
{
    // iOS · macOS 빌드에서만 실행되는 코드
}

Unity 에디터에서는 등록되지 않습니다

이 Add-on은 iOS 또는 macOS로 빌드한 플레이어에서만 등록됩니다. Unity 에디터에서는 플랫폼이 맞아도 등록되지 않으므로, HiveCore.Resolve<T>()를 쓰면 RegistrationNotFoundException이 발생합니다. 반드시 TryResolve<T>()로 확인한 뒤 사용하세요.

패키지 설치와 등록 절차는 모듈 설치 및 초기화를 참조하세요.

메서드 요약

비동기 메서드는 마지막 파라미터로 CancellationToken ct = default를 받습니다. 호출 규약은 호출 컨텍스트를 참조하세요.

• LoginAsync(): Apple 로그인 화면 표시와 Apple이 발급한 자격 증명 수신
• CancelCurrentSession(): 코드에서 진행 중인 로그인 취소

메서드

LoginAsync

Apple 로그인 화면을 띄우고, Apple이 돌려준 사용자 식별자, 아이덴티티 토큰, 인가 코드, 이메일, 이름, 실사용자 판정 값을 가공하지 않고 반환합니다.

한 번에 하나의 로그인만 진행합니다. 로그인이 진행 중일 때 다시 호출하면 진행 중인 로그인은 그대로 두고 Code가 FailedPrecondition인 Failure를 바로 반환합니다.

Unity

Task<AppleSignInServiceLoginResult> LoginAsync(AppleSignInServiceLoginRequest request, CancellationToken ct = default)

• 요청: AppleSignInServiceLoginRequest
• 응답: AppleSignInServiceLoginResponse

결과 케이스 — AppleSignInServiceLoginResult

결과 케이스	와이어 코드	설명
Success	—	로그인에 성공했습니다. Data에 Apple 자격 증명이 담깁니다.
UserCanceled	user_canceled	앱 사용자가 Apple 로그인 화면을 닫았습니다. 앱 사용자에게 재시도를 안내할 수 있습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. Problem의 HiveError로 원인을 확인합니다.

UserCanceled는 IUserCanceledOutcome을 구현합니다.

사용자 취소와 코드 취소는 다릅니다

앱 사용자가 Apple 로그인 화면을 닫으면 UserCanceled입니다. 반면 CancellationToken이나 CancelCurrentSession()으로 코드에서 취소하면 Code가 Cancelled인 Failure가 됩니다.

발생 예외

• ArgumentNullException: request가 null인 경우
• ArgumentException: request.NonceHash가 null이거나 비어 있는 경우, 또는 request.RequestedScopes에 Unspecified가 들어 있는 경우

호출 예시

Unity

using Hive.Axyl.Auth.Addon.Apple;
using Hive.Axyl.Core;

var request = new AppleSignInServiceLoginRequest
{
    NonceHash = nonceHash,   // 앱이 만든 원본 nonce의 SHA256 값을 소문자 16진수로 표기한 문자열
    RequestedScopes = new[] { RequestedScope.Email, RequestedScope.FullName },
};

var result = await apple.LoginAsync(request);

switch (result)
{
    case AppleSignInServiceLoginResult.Success success:
        string providerUserId = success.Data.UserIdentifier;   // LoginProviderAsync의 ProviderUserId
        string providerToken = success.Data.IdentityToken;     // LoginProviderAsync의 ProviderToken
        break;

    case AppleSignInServiceLoginResult.UserCanceled:
        // 앱 사용자가 Apple 로그인 화면을 닫았습니다.
        break;

    case AppleSignInServiceLoginResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // 처리하지 않은 결과와 UnknownOutcome
        break;
}

로그인에 성공하면 UserIdentifier를 ProviderUserId로, IdentityToken을 ProviderToken으로 넣어 LoginProviderAsync()를 호출합니다. 구현 절차는 iOS와 macOS에서 Apple 자격 증명 획득을 참조하세요.

CancelCurrentSession

진행 중인 로그인을 코드에서 취소합니다. 대기 중이던 LoginAsync()는 Code가 Cancelled인 Failure로 끝납니다. 진행 중인 로그인이 없으면 아무 동작도 하지 않습니다.

Unity

void CancelCurrentSession()

데이터 타입

AppleSignInServiceLoginRequest

필드	타입	필수 여부	설명
NonceHash	string	Required	앱이 만든 원본 nonce의 SHA256 값을 소문자 16진수로 표기한 문자열입니다. Add-on은 이 값을 Apple 로그인 요청의 nonce로 그대로 전달할 뿐 값을 만들거나 검증하지 않으므로, 로그인할 때마다 원본 nonce를 새로 만드세요.
RequestedScopes	IReadOnlyList<RequestedScope>	Required	Apple에 요청할 사용자 정보 범위입니다. 빈 목록을 넘기면 사용자 식별자만 반환됩니다.

이메일과 이름은 첫 로그인에서만 반환됩니다

Apple 정책에 따라 이메일과 이름은 해당 Apple 계정으로 이 앱에 처음 로그인할 때만 반환됩니다. 이후 로그인에서는 범위를 요청해도 빈 문자열이 반환되므로, 첫 로그인에서 받은 값을 앱이 직접 저장하세요.

AppleSignInServiceLoginResponse

Apple이 발급한 자격 증명입니다.

필드	타입	필수 여부	설명
UserIdentifier	string	Required	Apple 사용자 식별자입니다. 같은 Apple Developer 팀에 속한 모든 앱에서 같은 값을 가집니다. LoginProviderAsync() 요청의 ProviderUserId로 사용합니다.
IdentityToken	string	Required	JSON Web Token(JWT) 형식의 Apple 아이덴티티 토큰입니다. LoginProviderAsync() 요청의 ProviderToken으로 사용합니다.
AuthorizationCode	string	Required	약 5분 동안 유효한 인가 코드입니다. Apple이 값을 주지 않으면 빈 문자열입니다. 이 Add-on으로 로그인할 때는 IdentityToken으로 바로 로그인하므로 이 값을 사용하지 않습니다.
Email	string	Required	앱 사용자의 이메일 주소입니다. 첫 로그인에서만 값이 담기고 이후에는 빈 문자열입니다. 앱 사용자가 나의 이메일 가리기를 선택했다면 @privaterelay.appleid.com으로 끝나는 Apple의 비공개 전달 주소일 수 있습니다.
UserName	AppleUserName	Required	앱 사용자의 이름입니다. 첫 로그인에서만 값이 담기고, 이후에는 모든 필드가 빈 문자열입니다.
RealUserStatus	RealUserStatus	Required	로그인한 계정이 실제 사람인지에 대해 Apple이 사기 방지용으로 제공하는 판정 값입니다.

AppleUserName

Apple PersonNameComponents의 일부 요소입니다. 경칭, 접미사, 별명처럼 잘 쓰지 않는 요소는 포함하지 않습니다.

필드	타입	필수 여부	설명
GivenName	string	Required	PersonNameComponents.givenName 값인 이름입니다. Apple이 값을 주지 않으면 빈 문자열입니다.
FamilyName	string	Required	PersonNameComponents.familyName 값인 성입니다. Apple이 값을 주지 않으면 빈 문자열입니다.
MiddleName	string	Required	PersonNameComponents.middleName 값인 중간 이름입니다. Apple이 값을 주지 않으면 빈 문자열입니다.

열거형

Add-on 열거형은 C# 멤버 이름으로 지정합니다. 표의 '값'은 직렬화에 사용하는 정수입니다.

RealUserStatus

계정이 실제 사람일 가능성에 대한 Apple의 판정 값입니다. Apple의 ASUserDetectionStatus에 대응합니다.

C# 멤버	값	설명
Unspecified	0	Apple이 판정 값을 제공하지 않았습니다.
LikelyReal	1	실제 사람일 가능성이 높다고 Apple이 판정했습니다.
Unknown	2	실제 사람인지 Apple이 판정하지 못했습니다.
Unsupported	3	이 OS 버전이나 플랫폼에서는 실사용자 판정을 지원하지 않습니다.

RequestedScope

Apple에 요청할 사용자 정보 범위입니다. Apple은 요청한 범위와 관계없이 첫 로그인에서만 해당 정보를 반환합니다.

C# 멤버	값	설명
Unspecified	0	범위를 지정하지 않은 기본값입니다. RequestedScopes에 넣으면 ArgumentException이 발생합니다.
Email	1	이메일 주소를 요청합니다. 응답의 Email에 담깁니다.
FullName	2	이름을 요청합니다. 응답의 UserName에 담깁니다.