쿠폰 사용

사용자가 앱 내 쿠폰 교환소에 쿠폰 코드를 입력하면 RedeemCouponAsync()를 호출해 쿠폰을 사용 처리합니다. 앱 내 쿠폰 교환소는 사용자가 쿠폰 코드를 입력하는 앱 화면으로, 앱이 직접 만듭니다. 쿠폰 사용에 성공하면 Hive Axyl 서버가 쿠폰에 설정한 아이템을 지급 우편에 담아 로그인한 사용자의 앱 내 우편함으로 발송합니다. 사용자는 이 우편함에서 아이템을 받습니다.

이 메서드를 호출하려면 사용자가 로그인해 있어야 합니다. 아직 쿠폰 모듈을 등록하지 않았거나 로그인 세션을 활성화하지 않았다면 먼저 모듈 설치, 초기화, 로그인을 완료하세요.

1. 쿠폰 코드 준비

RedeemCouponAsync()에 전달하는 쿠폰 코드는 운영자가 Hive 콘솔에서 발행하고 사용자가 앱 내 쿠폰 교환소에 입력한 값입니다. 코드가 올바른지는 Hive Axyl 서버가 검증합니다.

1.1. 쿠폰 코드 발행

쿠폰 코드는 운영자가 Hive 콘솔 > 쿠폰 > 쿠폰 발행에서 쿠폰을 발행하고 승인을 거치면 생성됩니다. 운영자는 쿠폰을 발행할 때 그 쿠폰을 사용한 사용자에게 지급할 아이템과 수량도 함께 정합니다. 쿠폰 코드를 만드는 방식은 쿠폰 종류에 따라 아래와 같이 다릅니다.

• 대량 쿠폰: 랜덤한 영문과 숫자로 자동 생성한 8자리, 12자리, 16자리 코드
• 키워드 쿠폰: 운영자가 영문 또는 숫자 8~20자로 직접 정한 코드

쿠폰 발행과 승인 절차는 쿠폰 발행을 참조하세요.

테스트 쿠폰

정식 오픈 전에 앱에서 쿠폰 코드를 입력하고 아이템을 받는 흐름을 확인하려면 테스트 쿠폰을 사용하세요. 테스트 쿠폰은 대량 쿠폰을 발행할 때 최대 10건까지 함께 발행합니다. 사용 시작일 전에도 사용할 수 있지만 종료일이 지나면 사용할 수 없습니다. 그 밖의 사용 조건은 정식 쿠폰과 같습니다.

테스트 쿠폰 코드와 사용 여부는 쿠폰 발행 목록 팝업의 테스트 쿠폰 탭에서 확인합니다. 쿠폰이 발행 완료 상태가 된 뒤 Hive 콘솔 > 쿠폰 > 쿠폰 발행 목록에서 쿠폰 제목을 선택하고, 쿠폰 상세 내용 팝업에서 발행 목록 보기를 선택해 쿠폰 발행 목록 팝업을 여세요.

1.2. 쿠폰 코드 형식

쿠폰 코드는 영문과 숫자로 이루어진 8~20자 문자열이며 대소문자를 구분하지 않습니다. 사용자가 1234-ABCD처럼 읽기 쉽게 하이픈을 넣어 입력해도 Hive Axyl 서버가 하이픈을 제거한 뒤 검증합니다. 따라서 앱 클라이언트에서 하이픈을 지우거나 대소문자를 바꾸지 않고 보내도 됩니다. 단, 하이픈을 포함한 전체 길이는 20자를 넘을 수 없습니다.

2. 쿠폰 사용 요청

RedeemCouponAsync

RedeemCouponAsync()를 호출해 사용자가 입력한 쿠폰 코드의 사용을 요청합니다. 쿠폰 사용에 성공하면 Hive Axyl 서버는 쿠폰에 설정한 아이템을 지급 우편에 담아 우편함 서버에 발송을 요청합니다. 우편함 서버가 발송 요청을 접수하면 Hive Axyl 서버는 응답 데이터의 MailId에 지급 우편의 ID를 담아 돌려줍니다. 쿠폰 코드를 사용할 수 없으면 RedeemCouponAsync()가 사유에 해당하는 응답 상태의 결과 케이스를 반환합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	CouponRedeemRequest	Required	사용할 쿠폰 코드를 담은 요청. null을 전달하면 ArgumentNullException이 발생
context	ApiCallContext?	Optional	호출 단위 설정 객체입니다. 호출을 취소하거나 이 호출에만 제한 시간 같은 요청 정책을 따로 적용할 때 지정하며, 생략하면 기본값을 사용합니다. 호출을 취소해도 Hive Axyl 서버에 이미 전달된 쿠폰 사용 요청은 취소되지 않을 수 있습니다. 자세한 내용은 Core 호출 컨텍스트를 참조하세요.

CouponRedeemRequest

필드명	타입	필수 여부	설명
CouponCode	string	Required	사용자가 앱 내 쿠폰 교환소에 입력한 쿠폰 코드. 영문과 숫자 8~20자이며 대소문자를 구분하지 않음. 하이픈을 넣어도 Hive Axyl 서버가 제거한 뒤 검증하며, 하이픈을 포함한 전체 길이는 20자 이하. 예: ABCD1234EFGH

호출 예시

CouponRedeemCouponResult의 성공 결과와 이 메서드의 결과 케이스(Outcome)는 아래 예시와 응답 상태에서 확인합니다. 요청을 수행할 수 없을 때 반환하는 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

아래는 RedeemCouponAsync()가 반환하는 모든 결과 케이스를 switch 구문으로 분기하는 예시입니다. 각 분기의 주석은 앱 내 쿠폰 교환소에 표시할 안내 내용입니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Coupon;
using UnityEngine;

// coupon: 모듈 초기화 시 등록한 ICouponService
ICouponService coupon = HiveCore.Resolve<ICouponService>();

// inputCode: 사용자가 앱 내 쿠폰 교환소에 입력한 쿠폰 코드
CouponRedeemCouponResult result = await coupon.RedeemCouponAsync(new CouponRedeemRequest
{
    CouponCode = inputCode,
});

switch (result)
{
    case CouponRedeemCouponResult.Success success:
        // 지급 우편의 발송 요청이 우편함 서버에 접수되었습니다.
        // 쿠폰을 사용했음을 알리고, 앱 내 우편함에서 아이템을 받도록 안내합니다.
        string mailId = success.Data.MailId;   // 지급 우편의 ID
        break;

    case CouponRedeemCouponResult.CouponCodeInvalidFormat:
        // 쿠폰 코드 형식이 올바르지 않으므로 코드를 확인하도록 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponCodeNotFound:
        // 없거나 삭제된 쿠폰 코드이므로 코드를 확인하도록 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponDisabled:
        // 지금은 사용할 수 없는 쿠폰임을 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponBeforeStart:
        // 사용 기간이 시작된 뒤 다시 사용하도록 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponExpired:
        // 사용 기간이 끝난 쿠폰임을 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponAlreadyUsed:
        // 이미 사용한 쿠폰임을 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponAccountLimitExceeded:
        // 이 계정으로는 더 사용할 수 없는 쿠폰임을 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponGroupLimitExceeded:
        // 이 계정으로는 같은 그룹의 쿠폰을 더 사용할 수 없음을 안내합니다.
        break;

    case CouponRedeemCouponResult.CouponTotalLimitExceeded:
        // 이 쿠폰 코드의 사용 가능 수량이 모두 소진되었음을 안내합니다.
        break;

    // 공통 실패 처리 (네트워크·서버 오류, 공통 Failure 코드)
    case CouponRedeemCouponResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.ExternalCode} {err.Message} (trace: {err.TraceId})");
        if (err.ExternalCode == "internal_error")
        {
            // 쿠폰은 사용하지 않은 상태로 되돌아갔으므로 같은 쿠폰 코드로 다시 시도하도록 안내합니다.
        }
        else
        {
            // 일반적인 실패 안내를 표시합니다.
        }
        break;

    // 이 SDK 버전이 알지 못하는 새 결과: 기록한 뒤 실패로 처리합니다.
    case CouponRedeemCouponResult.UnknownOutcome unknown:
        Debug.LogWarning($"[Coupon] 알 수 없는 결과: {unknown.Code} {unknown.RawJson}");
        // 일반적인 실패 안내를 표시합니다.
        break;

    // 안전망: 처리하지 않은 결과
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 CouponRedeemCouponResult.Success의 Data(CouponRedeemResponseWrapperResponseData)에 결과가 담깁니다. Data.MailId는 사용자의 수신 우편 목록에서 지급 우편을 찾을 때 사용합니다.

필드명	타입	필수 여부	설명
Data.MailId	string	Required	쿠폰에 설정한 아이템을 담아 발송한 지급 우편의 ID. 우편함의 원본 발신 우편 ID이므로, 수신 우편을 상세 조회하거나 읽음 처리할 때 사용하는 MailRecipientId와 다름
Data.Meta	string?	Optional	Hive Axyl 서버가 함께 전달한 부가 정보. 가공되지 않은 원본 JSON 문자열이며, 부가 정보가 없으면 null

응답 예시

Unity

// success.Data (CouponRedeemResponseWrapperResponseData)
string mailId = success.Data.MailId;   // 예: "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
string? meta  = success.Data.Meta;     // 부가 정보가 없으면 null

응답 상태

반환 객체 CouponRedeemCouponResult는 아래 케이스 중 하나로 분기됩니다. Hive Axyl 서버는 쿠폰 코드를 형식, 존재 여부, 사용 조건, 사용 여부와 사용 한도 순서로 검증합니다. 여러 조건에 동시에 해당하면 그중 우선순위가 가장 높은 결과 하나만 반환합니다. 아래 표에서 CouponCodeInvalidFormat부터 CouponTotalLimitExceeded까지는 이 검증 순서를 따릅니다.

RedeemCouponAsync()는 결과 케이스만 전달하고 사용자에게 보여 줄 안내 문구는 전달하지 않습니다. 따라서 결과 케이스별 안내 문구를 직접 정해 앱 내 쿠폰 교환소에 표시하세요.

결과 케이스	설명	앱 클라이언트 대응
Success	쿠폰 사용에 성공했습니다. 지급 우편의 발송 요청이 우편함 서버에 접수되었고, 그 우편의 ID가 Data.MailId에 담깁니다.	쿠폰을 사용했음을 알리고 앱 내 우편함에서 아이템을 받도록 안내. 이후 처리는 지급 우편 수령을 참조하세요.
CouponCodeInvalidFormat	쿠폰 코드의 형식이 올바르지 않습니다.	쿠폰 코드를 확인해 다시 입력하도록 안내
CouponCodeNotFound	쿠폰 코드가 없거나 삭제되었습니다.	쿠폰 코드를 확인해 다시 입력하도록 안내
CouponDisabled	쿠폰이나 쿠폰 코드가 비활성화되었습니다. Hive 콘솔에서 쿠폰 사용이 Off 상태이거나 쿠폰 코드가 비활성 상태인 경우입니다.	지금은 사용할 수 없는 쿠폰임을 안내
CouponBeforeStart	쿠폰의 사용 기간이 아직 시작되지 않았습니다.	사용 기간이 시작된 뒤 다시 사용하도록 안내
CouponExpired	쿠폰의 사용 기간이 끝났습니다.	사용 기간이 끝난 쿠폰임을 안내
CouponAlreadyUsed	이미 사용한 쿠폰입니다.	이미 사용한 쿠폰임을 안내
CouponAccountLimitExceeded	계정당 사용 한도에 도달했습니다. 한도는 Hive 콘솔에서 쿠폰을 발행할 때 정해집니다.	이 계정으로는 더 사용할 수 없는 쿠폰임을 안내
CouponGroupLimitExceeded	쿠폰 그룹의 사용 한도에 도달했습니다. 운영자는 Hive 콘솔에서 같은 종류의 쿠폰 여러 개를 쿠폰 그룹으로 묶어 계정당 사용 수량을 그룹 단위로 제한합니다. 자세한 내용은 쿠폰 발행을 참조하세요.	이 계정으로는 같은 그룹의 쿠폰을 더 사용할 수 없음을 안내
CouponTotalLimitExceeded	이 쿠폰 코드의 전체 사용 한도에 도달했습니다. 한도는 Hive 콘솔에서 쿠폰을 발행할 때 정해집니다.	쿠폰의 사용 가능 수량이 모두 소진되었음을 안내
Failure	공통 Failure입니다. 네트워크 오류처럼 호출을 마치지 못한 경우와 Hive Axyl 서버가 공통 Failure 코드로 응답한 경우가 여기에 해당합니다. 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. ExternalCode가 internal_error이면 쿠폰은 사용하지 않은 상태로 되돌아갑니다. 지급 우편을 발송하지 못한 경우에도 ExternalCode는 internal_error입니다.	공통 오류 처리 기준에 따라 처리. internal_error이면 같은 쿠폰 코드로 다시 시도하도록 안내
UnknownOutcome	이 SDK 버전이 알지 못하는 새 결과입니다.	실패로 처리하고 Code와 RawJson을 기록. 처리 기준은 알 수 없는 결과를 참조하세요.

3. 지급 우편 수령

Success는 지급 우편의 발송 요청이 우편함 서버에 접수되었다는 뜻이며, 사용자가 아이템을 받았다는 뜻은 아닙니다. Hive Axyl 서버는 이 접수 시점에 지급 우편 발송에 성공한 것으로 처리합니다. 사용자가 실제로 아이템을 받았는지는 앱 서버가 우편함에서 따로 확인해야 합니다.

따라서 Success만 보고 아이템 지급이 끝났다고 판단하지 말고, 우편함에서 아이템 수령의 순서대로 처리하세요.

3.1. 지급 우편의 발송 정보

Hive Axyl 서버는 아래 값으로 지급 우편을 발송합니다. 앱에서 우편함 화면을 구성하거나 지급 우편을 처리할 때 이 값을 기준으로 삼으세요.

항목	지급 우편의 값	앱에서 확인할 점
발신자	"Admin"입니다.	언어 설정과 관계없이 바뀌지 않는 고정값입니다.
언어	Hive Axyl SDK가 RedeemCouponAsync() 요청과 함께 보내는 언어입니다. 요청에 언어가 없거나 Hive Axyl 서버가 지원하지 않는 언어이면 한국어로 발송됩니다.	Hive Axyl SDK는 초기화할 때 읽은 OS 언어를 요청에 담아 보냅니다. 앱이 OS 언어와 별개로 언어 설정을 둔다면 쿠폰을 사용하기 전에 SetLanguage()로 언어를 지정하세요.
카테고리	우편함 기본 카테고리인 DEFAULT입니다.	앱 클라이언트가 MailCategory로 카테고리를 지정해 수신 우편 목록을 조회한다면, 지급 우편은 DEFAULT를 지정하거나 MailCategory를 생략한 조회에만 나타납니다.
확장 데이터	사용한 쿠폰의 UUID 형식 식별자를 couponId 키로 담은 JSON 문자열입니다.	수신 우편 상세 정보 조회 응답의 Mail.MailExtension에 담깁니다. 필드 설명은 Mail을 참조하세요. 우편함은 이 값을 해석하지 않으므로 앱 서버가 우편을 처리할 때 읽어 사용합니다.

3.2. 우편함에서 아이템 수령

쿠폰에 설정한 아이템은 지급 우편의 첨부 아이템으로 전달되며, 사용자가 이 아이템을 받는 과정은 우편함 기능으로 처리합니다. Hive Axyl SDK의 우편함은 첨부 아이템의 수령 상태만 기록하고 아이템을 실제로 지급하지는 않습니다. 따라서 아이템 지급과 수령 검증은 앱이 직접 구현해야 합니다. 자세한 내용은 첨부 아이템을 참조하세요.

지급 우편은 아래 순서로 처리합니다.

1. 앱 클라이언트가 수신 우편 목록 조회로 사용자가 받은 우편 목록을 불러옵니다. 목록 항목의 MailId는 원본 발신 우편의 ID입니다. MailId가 RedeemCouponAsync() 응답의 Data.MailId와 같은 항목이 지급 우편입니다.
2. 앱 클라이언트가 지급 우편 항목의 MailRecipientId로 수신 우편 상세 정보 조회를 호출해 첨부 아이템과 Mail.MailExtension을 확인합니다.
3. 앱 서버가 첨부 아이템과 Mail.MailExtension을 확인하고 사용자에게 아이템을 지급합니다.
4. 앱 클라이언트가 앱 서버의 지급 결과를 받은 뒤 우편 읽음 처리를 호출해 첨부 아이템 수령 상태를 갱신합니다. 이때 Target은 Attachment 또는 All로 지정합니다. 수령 상태를 판단하는 방법은 읽음과 수령 상태 구분을 참조하세요.

더 알아보기

• 쿠폰 지급 구현 순서
• 수신 우편 정보 조회
• 우편 읽음 처리
• 쿠폰 발행
• 쿠폰 코드 사용 이력
• ICouponService