IPushService

원격 푸시 알림을 받을 디바이스 토큰을 Hive Axyl 서버에서 관리하는 서비스입니다. 디바이스 토큰 등록, 토큰의 언어와 푸시 알림 수신 동의 변경, 토큰과 사용자의 연결 해제를 제공합니다. 디바이스 토큰 발급처럼 기기에서 Firebase Cloud Messaging이나 Apple의 알림 프레임워크를 직접 호출하는 작업은 푸시 알림 Add-on이 담당합니다. 역할 구분은 푸시 알림 Add-on과의 관계를 참조하세요.

항목	값
인터페이스	IPushService
네임스페이스	Hive.Axyl.Push
패키지	com.com2usplatform.hiveaxyl.push

등록과 획득

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Push;

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddPush();
});

IPushService push = HiveCore.Resolve<IPushService>();

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

메서드	인증	설명
UpsertTokenAsync	세션 필요	디바이스 토큰을 로그인한 사용자와 연결해 등록합니다. 이미 등록된 토큰이면 토큰 정보 전체를 갱신합니다.
PatchTokenLanguageAsync	세션 필요	등록한 디바이스 토큰의 언어를 변경합니다.
PatchTokenAgreementAsync	세션 필요	등록한 디바이스 토큰의 푸시 알림 수신 동의 설정을 변경합니다.
DetachTokenIdentifierAsync	세션 필요	디바이스 토큰과 사용자의 연결을 해제합니다.

모든 메서드의 요청은 서버가 접수한 뒤 비동기로 처리합니다. 따라서 Success는 서버가 요청을 접수했다는 뜻이며, 응답으로 받는 데이터는 없습니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

모든 메서드는 요청 본문을 request 파라미터로 받으며, request는 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

발생 예외

예외	발생 조건
ArgumentNullException	request가 null인 경우

공통 Failure 코드

아래 코드는 서버가 코드로 응답하지만 기능 관점의 결과가 아니므로 Outcome이 아닌 Failure로 분기합니다. 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. 결과 갈래와 분기 방법은 Core 결과 모델을 참조하세요.

와이어 코드	의미
bad_request	잘못된 요청입니다.
invalid_parameter	요청 파라미터가 형식에 맞지 않습니다.
missing_field	필수 필드나 필수 헤더 자체가 누락됐습니다. X-App-Id 헤더를 보내지 않은 경우가 여기에 해당합니다.
missing_app_id	X-App-Id 헤더는 보냈지만 값이 비어 있습니다.
unauthorized	인증 토큰이 없거나 유효하지 않습니다.
token_expired	인증 토큰이 만료됐습니다.
forbidden	요청 권한이 없습니다.
resource_not_found	요청한 리소스가 없습니다.
method_not_allowed	허용되지 않은 요청 방식입니다.
resource_conflict	리소스 상태가 요청과 충돌합니다.
unprocessable_content	처리할 수 없는 요청 내용입니다.
rate_limit_exceeded	요청 빈도가 허용 한도를 초과했습니다.
internal_error	서버 내부 오류가 발생했습니다.
service_unavailable	서비스가 일시적으로 중단됐습니다.

메서드

UpsertTokenAsync

디바이스 토큰을 로그인한 사용자와 연결해 Hive Axyl 서버에 등록합니다. 요청한 Token이 서버에 이미 있으면 요청 값 전체로 토큰 정보를 갱신하고, 없으면 새로 등록합니다. 사용자 식별자는 요청에 넣지 않습니다. 서버가 로그인 세션의 인증 토큰에서 Player ID를 가져와 토큰과 연결합니다.

요청 값 전체로 토큰 정보를 갱신하므로, 이미 등록한 토큰을 다시 등록할 때도 앱 사용자의 현재 수신 동의 설정과 언어를 지정하세요. Agreement에 지정하지 않은 동의 항목은 false로 바뀝니다.

등록하거나 갱신할 때마다 서버에 저장된 토큰의 유효 기간이 1년으로 갱신됩니다. 같은 요청을 여러 번 보내도 결과가 같으므로, 응답을 받지 못했다면 같은 요청을 다시 보내도 됩니다.

디바이스 토큰은 Android에서는 Firebase Cloud Messaging 푸시 알림 Add-on의 GetTokenAsync()로, iOS와 macOS에서는 Apple Push Notification service 푸시 알림 Add-on의 GetTokenAsync()로 받습니다. 두 Add-on은 토큰이 새로 발급되면 TokenRefreshed 이벤트를 발생시키지만 토큰을 Hive Axyl 서버에 자동으로 등록하지 않습니다. 이벤트로 받은 새 토큰도 이 메서드로 다시 등록하세요.

Unity

Task<PushUpsertTokenResult> UpsertTokenAsync(UpsertTokenRequest request, ApiCallContext? context = null);

항목	값
요청	UpsertTokenRequest
응답	없음
인증	세션 필요

결과 케이스 — PushUpsertTokenResult

결과 케이스	와이어 코드	설명
Success	—	서버가 등록 요청을 접수했습니다.
ResourceNotInScope	resource_not_in_scope	요청한 리소스가 인증된 프로젝트 범위에 속하지 않습니다.
InvalidSubject	invalid_subject	이 메서드가 허용하지 않는 종류의 인증 토큰으로 호출했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

호출 예시

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Push;

var result = await push.UpsertTokenAsync(new UpsertTokenRequest
{
    Token        = deviceToken,                          // 푸시 알림 Add-on의 GetTokenAsync()로 받은 토큰
    ProviderType = UpsertTokenRequestProviderType.Fcm,   // Android 기준. iOS와 macOS는 Apns 또는 ApnsSandbox
    TimezoneId   = "Asia/Seoul",
    Country      = "KR",
    Language     = LanguageCode.Ko,
    Agreement    = new Agreement
    {
        Info      = true,
        Advertise = true,
        Night     = false,
    },
});

switch (result)
{
    case PushUpsertTokenResult.Success:
        // 서버가 등록 요청을 접수했습니다.
        break;

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

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

---

PatchTokenLanguageAsync

등록한 디바이스 토큰의 언어만 변경합니다. 서버는 Token과 일치하면서 로그인한 사용자와 연결된 토큰을 찾아 언어를 바꿉니다. 토큰의 언어는 푸시 알림 메시지의 언어를 정할 때 참조합니다.

Unity

Task<PushPatchTokenLanguageResult> PatchTokenLanguageAsync(PatchTokenLanguageRequest request, ApiCallContext? context = null);

항목	값
요청	PatchTokenLanguageRequest
응답	없음
인증	세션 필요

결과 케이스 — PushPatchTokenLanguageResult

결과 케이스	와이어 코드	설명
Success	—	서버가 언어 변경 요청을 접수했습니다.
ResourceNotInScope	resource_not_in_scope	요청한 리소스가 인증된 프로젝트 범위에 속하지 않습니다.
InvalidSubject	invalid_subject	이 메서드가 허용하지 않는 종류의 인증 토큰으로 호출했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

---

PatchTokenAgreementAsync

등록한 디바이스 토큰의 푸시 알림 수신 동의 설정을 요청한 값 전체로 변경합니다. 서버는 Token과 일치하면서 로그인한 사용자와 연결된 토큰을 찾아 수신 동의 설정을 바꿉니다.

동의 항목 하나만 바꿀 때도 Agreement의 Info, Advertise, Night를 모두 지정하세요. 지정하지 않은 항목은 false로 전송되므로, 앱 사용자가 동의한 항목이 동의하지 않은 상태로 바뀝니다.

Unity

Task<PushPatchTokenAgreementResult> PatchTokenAgreementAsync(PatchTokenAgreementRequest request, ApiCallContext? context = null);

항목	값
요청	PatchTokenAgreementRequest
응답	없음
인증	세션 필요

결과 케이스 — PushPatchTokenAgreementResult

결과 케이스	와이어 코드	설명
Success	—	서버가 수신 동의 변경 요청을 접수했습니다.
ResourceNotInScope	resource_not_in_scope	요청한 리소스가 인증된 프로젝트 범위에 속하지 않습니다.
InvalidSubject	invalid_subject	이 메서드가 허용하지 않는 종류의 인증 토큰으로 호출했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

---

DetachTokenIdentifierAsync

디바이스 토큰과 사용자의 연결을 해제합니다. 서버에 저장된 토큰 데이터는 삭제하지 않고, 토큰에 연결된 Player ID만 해제합니다. 로그아웃할 때 호출하세요.

이 메서드도 로그인 세션으로 사용자를 확인하므로, LogoutPlayerAsync로 세션을 폐기하기 전에 호출해야 합니다.

Unity

Task<PushDetachTokenIdentifierResult> DetachTokenIdentifierAsync(DetachTokenIdentifierRequest request, ApiCallContext? context = null);

항목	값
요청	DetachTokenIdentifierRequest
응답	없음
인증	세션 필요

결과 케이스 — PushDetachTokenIdentifierResult

결과 케이스	와이어 코드	설명
Success	—	서버가 연결 해제 요청을 접수했습니다.
ResourceNotInScope	resource_not_in_scope	요청한 리소스가 인증된 프로젝트 범위에 속하지 않습니다.
InvalidSubject	invalid_subject	이 메서드가 허용하지 않는 종류의 인증 토큰으로 호출했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

데이터 타입

여러 요청 타입이 공유하는 필드는 의미가 같습니다.

공유 필드	의미
Token	푸시 서비스가 발급한 디바이스 토큰입니다. Android에서는 Firebase Cloud Messaging 푸시 알림 Add-on, iOS와 macOS에서는 Apple Push Notification service 푸시 알림 Add-on의 GetTokenAsync()로 받습니다. 언어 변경, 수신 동의 변경, 연결 해제 요청에는 UpsertTokenAsync로 등록한 값과 같은 값을 넣습니다.
Language	토큰의 언어 코드입니다. 푸시 알림 메시지의 언어를 정할 때 참조합니다. 지정할 수 있는 값은 LanguageCode를 참조하세요.

Agreement

푸시 알림 수신 동의 설정입니다. 세 필드의 기본값은 모두 false이며, 요청을 보낼 때 세 값이 항상 함께 전송됩니다.

앱 서버가 리모트 푸시 전송으로 알림을 보내면 알림 유형과 이 설정에 따라 알림을 받을 기기가 정해집니다. category가 INFO인 정보성 알림은 Info가 true인 기기에 전달되고, ADVERTISE인 광고성 알림은 Advertise와 Night가 모두 true인 기기에 전달됩니다.

필드	타입	필수 여부	설명
Advertise	bool	Required	광고성 푸시 알림 수신 동의 여부입니다.
Info	bool	Required	정보성 푸시 알림 수신 동의 여부입니다.
Night	bool	Required	야간 광고성 푸시 알림 수신 동의 여부입니다. Advertise가 false이면 true로 지정할 수 없습니다.

DetachTokenIdentifierRequest

디바이스 토큰과 사용자의 연결 해제 요청입니다.

필드	타입	필수 여부	설명
Token	string	Required	사용자와의 연결을 해제할 디바이스 토큰입니다.

PatchTokenAgreementRequest

디바이스 토큰의 푸시 알림 수신 동의 변경 요청입니다.

필드	타입	필수 여부	설명
Agreement	Agreement	Required	새로 적용할 수신 동의 설정 전체입니다.
Token	string	Required	수신 동의 설정을 변경할 디바이스 토큰입니다.

PatchTokenLanguageRequest

디바이스 토큰의 언어 변경 요청입니다.

필드	타입	필수 여부	설명
Language	LanguageCode	Required	새로 적용할 언어 코드입니다.
Token	string	Required	언어를 변경할 디바이스 토큰입니다.

UpsertTokenRequest

디바이스 토큰 등록 요청입니다. 이미 등록된 토큰이면 이 요청의 값 전체로 토큰 정보를 갱신합니다.

필드	타입	필수 여부	설명
Agreement	Agreement	Required	푸시 알림 수신 동의 설정입니다. 세 항목을 모두 지정하며, 지정하지 않은 항목은 false로 전송됩니다.
AppVersion	string?	Optional	앱 버전입니다. 최대 32자입니다.
Country	string	Required	기기의 ISO 3166-1 두 글자 국가 코드입니다. 예약 발송 푸시 알림인 푸시 캠페인에서 국가별로 발송 대상을 거를 때 참조합니다. 예: KR
EventType	string?	Optional	토큰 등록을 일으킨 이벤트 유형입니다. 기록용으로 저장되며 최대 32자입니다. 예: LOGIN
Language	LanguageCode	Required	토큰의 언어 코드입니다.
ProviderType	UpsertTokenRequestProviderType	Required	푸시 알림을 전달할 푸시 서비스입니다. Android에서는 Fcm을 지정합니다. iOS와 macOS에서는 Apple Push Notification service 푸시 알림 Add-on의 GetProviderEnvironmentAsync()가 알려 준 환경에 맞춰 Apns 또는 ApnsSandbox를 지정합니다.
SdkVersion	string?	Optional	앱에 적용한 Hive Axyl SDK 버전입니다. 최대 32자입니다.
ServerId	string?	Optional	앱 서버 ID입니다. 최대 64자입니다.
TimezoneId	string	Required	기기의 시간대 이름입니다. Internet Assigned Numbers Authority(IANA) 시간대 데이터베이스에 있는 이름을 넣으며, 없는 이름을 넣으면 요청이 거부됩니다. 푸시 캠페인을 기기의 현지 시각 기준으로 발송할 때 참조합니다. 최대 64자입니다. 예: Asia/Seoul, America/New_York
Token	string	Required	등록할 디바이스 토큰입니다.

열거형

앱 코드에는 C# 멤버 이름을 입력하세요. 와이어 값은 서버와 주고받는 문자열입니다.

LanguageCode

Hive Axyl이 지원하는 언어 코드입니다. UpsertTokenRequest.Language와 PatchTokenLanguageRequest.Language에 지정합니다.

Mailbox 모듈에도 LanguageCode가 있습니다

Hive.Axyl.Mailbox 네임스페이스에도 같은 이름의 LanguageCode가 있습니다. 한 파일에서 두 네임스페이스를 함께 가져온 뒤 LanguageCode를 그대로 쓰면 어느 타입인지 모호해 컴파일 오류가 발생합니다. 두 타입을 한 파일에서 함께 쓰려면 using PushLanguageCode = Hive.Axyl.Push.LanguageCode;와 using MailboxLanguageCode = Hive.Axyl.Mailbox.LanguageCode;처럼 두 타입에 각각 별칭을 지정하세요.

C# 멤버	와이어 값	설명
Unspecified	LANGUAGE_CODE_UNSPECIFIED	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Ko	ko	한국어입니다.
En	en	영어입니다.
Ja	ja	일본어입니다.
ZhHans	zh-Hans	중국어 간체입니다.
ZhHant	zh-Hant	중국어 번체입니다.
De	de	독일어입니다.
Fr	fr	프랑스어입니다.
Ru	ru	러시아어입니다.
It	it	이탈리아어입니다.
Es	es	스페인어입니다.
Pt	pt	포르투갈어입니다.
Pl	pl	폴란드어입니다.
Nl	nl	네덜란드어입니다.
Tr	tr	튀르키예어입니다.
Th	th	태국어입니다.
Id	id	인도네시아어입니다.
Ar	ar	아랍어입니다.
Hi	hi	힌디어입니다.
Vi	vi	베트남어입니다.
Sv	sv	스웨덴어입니다.
Cs	cs	체코어입니다.
Fa	fa	페르시아어입니다.
No	no	노르웨이어입니다.
Uk	uk	우크라이나어입니다.
Ro	ro	루마니아어입니다.
He	he	히브리어입니다.
Ms	ms	말레이어입니다.
Da	da	덴마크어입니다.
El	el	그리스어입니다.
Hu	hu	헝가리어입니다.
Tl	tl	타갈로그어입니다.

UpsertTokenRequestProviderType

푸시 알림을 전달할 푸시 서비스입니다. UpsertTokenRequest.ProviderType에 지정합니다.

C# 멤버	와이어 값	설명
Unspecified	UPSERT_TOKEN_REQUEST_PROVIDER_TYPE_UNSPECIFIED	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Fcm	FCM	Firebase Cloud Messaging입니다. Android 기기의 토큰에 지정합니다.
Apns	APNS	Apple Push Notification service(APNs)의 운영 환경입니다. GetProviderEnvironmentAsync()가 알려 준 환경이 Apns인 iOS·macOS 기기의 토큰에 지정합니다.
ApnsSandbox	APNS_SANDBOX	APNs 샌드박스 환경입니다. GetProviderEnvironmentAsync()가 알려 준 환경이 ApnsSandbox인 iOS·macOS 기기의 토큰에 지정합니다.