GS2-SerialKey

Serial code feature

This feature can be used when you want to distribute in-game items through out-of-game merchandising, real events, SNS campaigns, collaboration campaigns, and so on. The same mechanism can handle codes printed on paper packaging or QR codes, as well as strings distributed via email/SNS.

However, some platformers do not allow the implementation of this feature, so please check the platformer’s guidelines before adoption.

Types of Serial Codes

There are two types of serial codes:

Serial Key: A code that cannot be reused once redeemed
Campaign Code: A code that can be shared and redeemed by multiple players

graph TD
  SerialCode["Serial code"]
  SerialCode --> SerialKey["Serial key<br/>One use per player"]
  SerialCode --> CampaignCode["Campaign code<br/>Shared by multiple players"]
  SerialKey --> SerialKeyUse["RPCLP-FP7N-NCDMJ-FLVA-IRI4"]
  CampaignCode --> CampaignCodeUse["NEWYEAR2026"]

Serial Key

A code that cannot be used again once it has been redeemed.

Serial keys are issued in a format such as “RPCLP-FP7N-NCDMJ-FLVA-IRI4” and the data length cannot be changed. Information about the campaign is also included in the serial key, so when using a serial key you only need to specify the namespace.

Campaign Code

A code in which the operator can freely set a string that is easy for humans to remember, such as “Halloween2025” or “SUMMER.” It is intended that many players share and redeem the same code.

Unlike serial keys, which are issued in association with a campaign, a campaign code uses the name of the campaign itself as the redeemable code.

Campaign

Both serial keys and campaign codes belong to a campaign.

A campaign has the following settings:

name: Campaign name (also used as the campaign code)
metadata: Arbitrary metadata
enableCampaignCode: Whether to enable the campaign code (redemption using the campaign name itself)

By associating a campaign with a GS2-Schedule event, you can set its valid period. Validation of the valid period can be achieved by combining transaction actions.

Issuing serial keys

Serial keys are issued by specifying the target campaign and the number to issue and running the issue process. The issue process runs as an asynchronous job, and progress can be checked through IssueJob. The list of issued serial keys can be downloaded in CSV format.

For uses such as printing on packaged merchandise, hundreds of thousands of keys can be issued at once.

Serial Key Status

A serial key has the following states:

Status	Description
`ACTIVE`	Available for the player to use
`USED`	Already used (cannot be reused)
`INACTIVE`	Deactivated by the operator

ACTIVE is the state in which the player can actually use the key, and it becomes USED once used. If the operator deactivates the key, it becomes INACTIVE.

Transaction Actions

GS2-SerialKey provides the following transaction actions:

Verify actions: verify serial code validity, verify that a serial code belongs to a specified campaign
Consume actions: mark a serial code as used
Acquire actions: revert a serial code to unused (for cancellation), issue a serial code

By using “Issue serial code” as an acquire action, you can safely complete processes within a transaction such as automatically issuing and gifting a unique serial code (transferable to others) per player upon completing a specific in-game mission or as a reward for a top ranking. This facilitates measures that encourage fan interaction outside the game and gift-giving among players.

Limit on the number of redemptions by code

By default, campaign codes can be redeemed an unlimited number of times.

Typically there are requirements such as “do not allow redemption again once redeemed” or “do not allow redemption for a certain period of time,” and for both campaign codes and serial keys there may be various requirements such as “limit the total number of redemptions within the same campaign.”

GS2-SerialKey does not provide such limit functions; it purely provides a function that determines whether the entered serial key is valid. Therefore, GS2-SerialKey itself has no rewards granted at the time of redemption.

An example implementation when using a serial key is shown below.

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 defines the reward obtained when a serial key is used, and GS2-Limit applies a redemption count limit, preventing items from being obtained multiple times.

When composing rewards, complex requirements can be realized by combining multiple microservices in a transaction, such as campaign period checks via GS2-Schedule or item granting via GS2-Inventory.

Master Data Management

Registering master data allows you to configure data and behaviors available to the microservice.

Master data types include the following:

CampaignModel: Definition of a campaign (the parent group of serial keys / campaign codes)

The following is a JSON example of master data.

{
  "version": "2019-08-19",
  "campaigns": [
    {
      "name": "newyear-2026",
      "metadata": "New Year campaign",
      "enableCampaignCode": true
    },
    {
      "name": "package-promo",
      "metadata": "For package insert (campaign code disabled)",
      "enableCampaignCode": false
    }
  ]
}

Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy.

Example Implementation

Using a serial key

It is not recommended to process the use of a serial key directly via this API.

By using the serial key through a service such as GS2-Exchange, the use of the serial key, granting of rewards, and check of redemption count limits can be handled as a single transaction.

    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;

Getting serial key information

Specify a serial key code to check which campaign it belongs to and its current state (ACTIVE / USED / INACTIVE). This can also be used to display error messages such as “the entered code has already been used” on a redemption screen.

    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();

Getting campaign information

Get the definition of a specific campaign (metadata, whether the campaign code is enabled, etc.).

    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();