토큰 설정 변경

등록한 디바이스 토큰의 언어와 수신 동의를 변경하거나, 토큰에 연결된 사용자 식별자를 해제합니다. 세 메서드 모두 요청 본문의 토큰 값으로 대상 토큰을 식별하며, 요청은 접수(202) 후 서버에서 비동기로 처리됩니다.

Note

토큰 설정 변경은 로그인된 세션을 사용합니다. 호출 전에 로그인을 먼저 완료해야 합니다.
Token에는 토큰 등록 시 사용한 것과 같은 디바이스 토큰 값을 전달합니다.

토큰 언어 변경

public Task PatchTokenLanguageAsync();

디바이스 토큰의 언어 코드를 변경합니다. 변경한 언어 코드는 알림 메시지의 언어 현지화에 사용됩니다. 사용자가 앱에서 언어 설정을 바꿨을 때 호출하세요.

호출 파라미터

구분	타입	변수명	설명
입력 (Input)	PatchTokenLanguageRequest	request	변경 대상 토큰과 적용할 언어 코드를 담는 요청 객체입니다.
입력 (Input)	ApiCallContext	context	(선택) 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

PatchTokenLanguageRequest

변수명	타입	필수 여부	설명
`Token`	string	Required	등록 시 사용한 디바이스 토큰 값입니다.
`Language`	LanguageCode	Required	적용할 언어 코드입니다. enum 멤버로 지정합니다(예: `LanguageCode.En`).

호출 예시

Unity

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

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

PushPatchTokenLanguageResult result = await push.PatchTokenLanguageAsync(
    new PatchTokenLanguageRequest {
        Token    = fcmToken,
        Language = LanguageCode.En,
    });

switch (result)
{
    case PushPatchTokenLanguageResult.Success:
        // 변경 요청 접수 완료(202). 서버가 비동기로 처리합니다.
        break;

    case PushPatchTokenLanguageResult.ResourceNotInScope:
        // 요청한 App ID 또는 리소스를 현재 프로젝트 범위에서 사용할 수 없습니다.
        break;

    case PushPatchTokenLanguageResult.InvalidSubject:
        // 로그인 세션의 사용자 식별자를 사용할 수 없습니다.
        break;

    // 공통 실패 처리 — 자세한 에러 모델은 [에러 처리](PLACEHOLDER_에러처리_링크) 참고
    case PushPatchTokenLanguageResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 상태

반환 객체 PushPatchTokenLanguageResult는 아래 케이스로 분기됩니다. 성공 시 별도의 응답 데이터는 없습니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	변경 요청이 접수되었습니다(202). 서버가 비동기로 처리합니다.	변경 완료로 처리
`ResourceNotInScope`	요청한 App ID 또는 리소스를 현재 프로젝트 범위에서 사용할 수 없습니다.	프로젝트와 App ID 설정 확인
`InvalidSubject`	로그인 세션에서 사용자 식별자를 확인할 수 없습니다.	로그인 상태 확인 후 재시도
`Failure`	네트워크, 서버 오류 또는 공통 실패 응답입니다. 요청 값 검증 오류는 `Problem`(`HiveError`)의 `ExternalCode`에 `invalid_parameter`, `missing_field`, `bad_request` 등으로 전달됩니다.	`ExternalCode` 확인 후 요청 값 수정 또는 재시도

수신 동의 변경

public Task PatchTokenAgreementAsync();

디바이스 토큰의 수신 동의 설정을 변경합니다. 변경할 항목만 보내는 방식이 아니라 세 항목 값 전체를 보내 통째로 교체하므로, 변경하지 않는 항목도 현재 값으로 채워 전달해야 합니다. 사용자가 앱의 알림 설정을 바꿨을 때 호출하세요.

호출 파라미터

구분	타입	변수명	설명
입력 (Input)	PatchTokenAgreementRequest	request	변경 대상 토큰과 적용할 수신 동의 전체 값을 담는 요청 객체입니다.
입력 (Input)	ApiCallContext	context	(선택) 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

PatchTokenAgreementRequest

변수명	타입	필수 여부	설명
`Token`	string	Required	등록 시 사용한 디바이스 토큰 값입니다.
`Agreement`	Agreement	Required	적용할 수신 동의 설정입니다. 세 항목 값을 모두 채워 전달합니다.

Agreement

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

호출 예시

Unity

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

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

PushPatchTokenAgreementResult result = await push.PatchTokenAgreementAsync(
    new PatchTokenAgreementRequest {
        Token     = fcmToken,
        Agreement = new Agreement {   // 변경하지 않는 항목도 현재 값으로 채웁니다.
            Info      = true,
            Advertise = true,
            Night     = false,
        },
    });

switch (result)
{
    case PushPatchTokenAgreementResult.Success:
        // 변경 요청 접수 완료(202). 서버가 비동기로 처리합니다.
        break;

    case PushPatchTokenAgreementResult.ResourceNotInScope:
        // 요청한 App ID 또는 리소스를 현재 프로젝트 범위에서 사용할 수 없습니다.
        break;

    case PushPatchTokenAgreementResult.InvalidSubject:
        // 로그인 세션의 사용자 식별자를 사용할 수 없습니다.
        break;

    // 공통 실패 처리 — 자세한 에러 모델은 [에러 처리](PLACEHOLDER_에러처리_링크) 참고
    case PushPatchTokenAgreementResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 상태

반환 객체 PushPatchTokenAgreementResult는 아래 케이스로 분기됩니다. 성공 시 별도의 응답 데이터는 없습니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	변경 요청이 접수되었습니다(202). 서버가 비동기로 처리합니다.	변경 완료로 처리
`ResourceNotInScope`	요청한 App ID 또는 리소스를 현재 프로젝트 범위에서 사용할 수 없습니다.	프로젝트와 App ID 설정 확인
`InvalidSubject`	로그인 세션에서 사용자 식별자를 확인할 수 없습니다.	로그인 상태 확인 후 재시도
`Failure`	네트워크, 서버 오류 또는 공통 실패 응답입니다. 요청 값 검증 오류는 `Problem`(`HiveError`)의 `ExternalCode`에 `invalid_parameter`, `missing_field`, `bad_request` 등으로 전달됩니다.	`ExternalCode` 확인 후 요청 값 수정 또는 재시도

토큰 식별자 연결 해제

public Task DetachTokenIdentifierAsync();

토큰에 연결된 사용자 식별자(Player ID)만 해제합니다. 토큰 데이터 자체는 삭제하지 않으므로, 해제 후에도 디바이스는 사용자 대상이 아닌 알림(예: 전체 발송)을 계속 받을 수 있습니다. 로그아웃이나 계정 전환으로 현재 사용자와 디바이스의 연결을 끊어야 할 때 호출하세요.

호출 파라미터

구분	타입	변수명	설명
입력 (Input)	DetachTokenIdentifierRequest	request	연결을 해제할 대상 토큰을 담는 요청 객체입니다.
입력 (Input)	ApiCallContext	context	(선택) 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

DetachTokenIdentifierRequest

변수명	타입	필수 여부	설명
`Token`	string	Required	등록 시 사용한 디바이스 토큰 값입니다.

호출 예시

Unity

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

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

PushDetachTokenIdentifierResult result = await push.DetachTokenIdentifierAsync(
    new DetachTokenIdentifierRequest {
        Token = fcmToken,
    });

switch (result)
{
    case PushDetachTokenIdentifierResult.Success:
        // 해제 요청 접수 완료(202). 서버가 비동기로 처리합니다.
        break;

    case PushDetachTokenIdentifierResult.ResourceNotInScope:
        // 요청한 App ID 또는 리소스를 현재 프로젝트 범위에서 사용할 수 없습니다.
        break;

    case PushDetachTokenIdentifierResult.InvalidSubject:
        // 로그인 세션의 사용자 식별자를 사용할 수 없습니다.
        break;

    // 공통 실패 처리 — 자세한 에러 모델은 [에러 처리](PLACEHOLDER_에러처리_링크) 참고
    case PushDetachTokenIdentifierResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 상태

반환 객체 PushDetachTokenIdentifierResult는 아래 케이스로 분기됩니다. 성공 시 별도의 응답 데이터는 없습니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	해제 요청이 접수되었습니다(202). 서버가 비동기로 처리합니다.	해제 완료로 처리
`ResourceNotInScope`	요청한 App ID 또는 리소스를 현재 프로젝트 범위에서 사용할 수 없습니다.	프로젝트와 App ID 설정 확인
`InvalidSubject`	로그인 세션에서 사용자 식별자를 확인할 수 없습니다.	로그인 상태 확인 후 재시도
`Failure`	네트워크, 서버 오류 또는 공통 실패 응답입니다. 요청 값 검증 오류는 `Problem`(`HiveError`)의 `ExternalCode`에 `invalid_parameter`, `missing_field`, `bad_request` 등으로 전달됩니다.	`ExternalCode` 확인 후 요청 값 수정 또는 재시도

연관 문서

본 문서의 내용과 관련하여 참조하는 문서는 아래와 같습니다.