Documentation index for AI agents

GS2-SerialKey

시리얼 코드 기능

게임 외부의 물품 판매나 오프라인 이벤트, SNS 캠페인, 콜라보 캠페인 등을 통해 게임 내 아이템을 배포하고 싶은 경우에 사용할 수 있습니다. 종이 패키지나 QR 코드에 인쇄한 코드, 이메일/SNS로 배포하는 문자열 모두 동일한 구조로 다룰 수 있습니다.

단, 이 기능은 일부 플랫폼 사업자가 구현을 허용하지 않는 경우가 있으므로, 채택할 때는 플랫폼 사업자의 가이드라인을 확인하도록 하십시오.

시리얼 코드의 종류

시리얼 코드에는 다음 두 가지 종류가 있습니다.

  • 시리얼 키: 1회 사용하면 재사용할 수 없는 코드
  • 캠페인 코드: 하나의 코드를 여러 사람이 공유할 수 있는 코드
graph TD
  SerialCode["시리얼 코드"]
  SerialCode --> SerialKey["시리얼 키<br/>1인 1회 한정"]
  SerialCode --> CampaignCode["캠페인 코드<br/>여러 명이 공용"]
  SerialKey --> SerialKeyUse["RPCLP-FP7N-NCDMJ-FLVA-IRI4"]
  CampaignCode --> CampaignCodeUse["NEWYEAR2026"]

시리얼 키

1회 사용하면 두 번 다시 사용할 수 없게 되는 코드 입니다.

시리얼 키는 “RPCLP-FP7N-NCDMJ-FLVA-IRI4"와 같은 형식으로 발행되며, 데이터 길이를 변경할 수 없습니다. 시리얼 키 내부에는 캠페인 종류에 대한 정보도 포함되어 있으며, 시리얼 키를 사용할 때는 네임스페이스를 지정하는 것만으로 사용할 수 있습니다.

캠페인 코드

“할로윈2025”, “SUMMER"와 같이 사람이 기억하기 쉬운 문자열을, 운영 측에서 임의로 설정할 수 있는 코드 입니다. 하나의 코드를 다수의 플레이어가 공유하여 교환에 사용하는 것을 상정하고 있습니다.

캠페인 코드는 캠페인에 연결하여 발행하는 시리얼 키와는 달리, 캠페인 이름 자체가 코드로서 교환 가능해집니다.

캠페인

“시리얼 키"도 “캠페인 코드"도 모두 캠페인에 속합니다.

캠페인에는 다음을 설정합니다.

  • name: 캠페인 이름(캠페인 코드로도 사용됨)
  • metadata: 임의의 메타데이터
  • enableCampaignCode: 캠페인 코드(캠페인 이름 자체를 사용한 교환)를 활성화할지 여부

캠페인은 GS2-Schedule 의 이벤트와 연결하여 유효 기간을 설정할 수 있습니다. 유효 기간의 검증은 트랜잭션 액션을 조합하여 실현할 수 있습니다.

시리얼 키 발행

대상 캠페인과 발행 수량을 지정하여 시리얼 키 발행 처리를 실행하면 시리얼 키가 발행됩니다. 발행 처리는 비동기 작업으로 실행되며, IssueJob 을 통해 진행 상황을 확인할 수 있습니다. 발행된 시리얼 키 목록은 CSV 형식으로 다운로드할 수 있습니다.

물품 패키지에 인쇄하는 등 대량으로 발행하는 용도로는 수십만 건 단위의 발행도 가능합니다.

시리얼 키의 상태

시리얼 키는 다음과 같은 상태를 가집니다.

상태설명
ACTIVE플레이어가 사용 가능한 상태
USED이미 사용됨(재사용 불가)
INACTIVE운영에 의해 무효화된 상태

실제로 플레이어가 사용할 수 있는 상태가 ACTIVE이며, 사용하면 USED가 됩니다. 운영 측에서 시리얼 키를 무효화하면 INACTIVE가 됩니다.

트랜잭션 액션

GS2-SerialKey 에서는 다음과 같은 트랜잭션 액션을 제공하고 있습니다.

  • 검증 액션: 시리얼 코드의 유효성 검증, 시리얼 코드가 지정된 캠페인에 속하는지 검증
  • 소비 액션: 시리얼 코드의 사용 완료 처리
  • 획득 액션: 시리얼 코드의 미사용화(취소용), 시리얼 코드 발행

“시리얼 코드 발행"을 획득 액션으로 활용하면, 게임 내 특정 미션을 달성했을 때나 상위 입상 보상으로서 플레이어별 고유한 시리얼 코드(타인에게 양도 가능)를 자동으로 발행하여 지급하는 처리를, 트랜잭션 내에서 안전하게 완결시킬 수 있습니다. 이를 통해 게임 외부에서의 팬 교류나 플레이어 간 선물 요소를 촉진하는 시책을 손쉽게 구현할 수 있습니다.

코드에 의한 교환 횟수 제한

캠페인 코드에 의한 교환은 아무 조치도 하지 않으면 몇 번이든 교환이 가능합니다.

보통은 “한 번 교환을 실행하면 두 번 다시 교환할 수 없게 한다"거나 “일정 기간 교환을 할 수 없게 하고 싶다"와 같은 요건이 있을 것이며, 캠페인 코드든 시리얼 키든 “동일 캠페인에서 교환 가능한 총 횟수에 제한을 두고 싶다"는 등 다양한 요건이 있을 것입니다.

GS2-SerialKey 는 그러한 제한 기능을 가지고 있지 않으며, 순수하게 입력된 시리얼 키가 유효한지만 판단하는 기능을 제공합니다. 그렇기 때문에 GS2-SerialKey 자체는 교환을 실행했을 때 얻을 수 있는 보상도 가지고 있지 않습니다.

시리얼 키를 사용하는 경우의 구현 예제를 아래에 나타냅니다.

actor Player
participant "GS2-Exchange#Rate"
participant "GS2-SerialKey#SerialKey"
participant "GS2-Limit#Counter"
participant "GS2-Inventory#Item"
Player -> "GS2-Exchange#Rate" : Exchange
"GS2-Exchange#Rate" -[#f00]-> "GS2-SerialKey#SerialKey" : Use
"GS2-Exchange#Rate" -> "GS2-Limit#Counter" : Increase
"GS2-Exchange#Rate" -> "GS2-Inventory#Item" : Acquire
"GS2-Exchange#Rate" -> Player

GS2-Exchange 에 의해 시리얼 키를 사용했을 때 얻을 수 있는 보상이 정의되고, GS2-Limit 에 의해 횟수 제한이 적용되어 몇 번이든 아이템을 얻을 수 없게 됩니다.

보상을 구성할 때는 GS2-Schedule 에 의한 캠페인 기간 체크나 GS2-Inventory 에서의 경품 지급 등, 여러 마이크로서비스를 트랜잭션으로 연결하여 복잡한 요건을 실현할 수 있습니다.

마스터 데이터 관리

마스터 데이터를 등록하면 마이크로서비스에서 사용 가능한 데이터나 동작을 설정할 수 있습니다.

마스터 데이터의 종류에는 다음이 있습니다.

  • CampaignModel: 캠페인(시리얼 키/캠페인 코드의 모집단) 정의

다음은 마스터 데이터의 JSON 예입니다.

{
  "version": "2019-08-19",
  "campaigns": [
    {
      "name": "newyear-2026",
      "metadata": "새해 캠페인",
      "enableCampaignCode": true
    },
    {
      "name": "package-promo",
      "metadata": "패키지 동봉용 (캠페인 코드 비활성화)",
      "enableCampaignCode": false
    }
  ]
}

마스터 데이터의 등록은 관리 콘솔에서 등록하는 것 외에도, GitHub에서 데이터를 반영하거나 GS2-Deploy를 사용해 CI에서 등록하는 워크플로우를 구성할 수 있습니다.

구현 예제

시리얼 키를 사용

이 API로 직접 시리얼 키를 사용하는 처리를 하는 것은 권장하지 않습니다.

GS2-Exchange 와 같은 서비스를 통해 시리얼 키 사용을 수행함으로써, 시리얼 키의 사용과 보상 지급·횟수 제한 체크를 하나의 트랜잭션으로 처리할 수 있습니다.

    var result = await gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SerialKey(
        code: "code-0001"
    ).UseSerialCodeAsync(
    );
    var item = await result.ModelAsync();
    const auto Future = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->SerialKey(
        "code-0001" // code
    )->UseSerialCode(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
var domain = ez.serial_key.namespace_(
    "namespace-0001"
).me(game_session).serial_key("code-0001")
var async_result = await domain.use_serial_code()
if async_result.error != null:
    push_error(str(async_result.error))
    return
var item = async_result.result

시리얼 키의 정보 취득

시리얼 키의 코드를 지정하여, 해당 코드가 속한 캠페인이나 현재 상태(ACTIVE / USED / INACTIVE)를 확인할 수 있습니다. 교환 화면에서 “입력한 코드는 이미 사용되었습니다"와 같은 오류 메시지를 표시하는 용도로도 사용할 수 있습니다.

    var item = await gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SerialKey(
        code: "code-0001"
    ).ModelAsync();
    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->SerialKey(
        "code-0001" // code
    );
    const auto Item = Domain->Model();
var domain = ez.serial_key.namespace_(
        "namespace-0001"
    ).user(
        "user-0001"
    ).serial_key(
        "code-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

캠페인 정보 취득

특정 캠페인의 정의(메타데이터, 캠페인 코드의 활성화·비활성화 등)를 취득합니다.

    var item = await gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).CampaignModel(
        campaignModelName: "newyear-2026"
    ).ModelAsync();
    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->CampaignModel(
        "newyear-2026" // campaignModelName
    );
    const auto Item = Domain->Model();
var domain = ez.serial_key.namespace_(
        "namespace-0001"
    ).campaign_model(
        "campaign-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

상세 레퍼런스

GS2-SerialKey API 레퍼런스