GS2-SerialKey

Serial code feature

This feature can be used if you want to distribute in-game items through out-of-game merchandising.

However, some platformers do not allow this feature, so please check the platformer’s policy before using it.

There are two types of serial codes:

  • Serial Key: A code that cannot be used again once it has been redeemed.
  • Campaign Code: A code that can be shared and used by multiple users.

Serial Key

A code that cannot be reused once it has been used.

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 type is also included in the serial key. When using a serial key, simply specify the namespace.

Issue Serial Keys

Serial keys are issued by running the Serial Key Issue process, specifying the target campaign and the number of serial keys to be issued. The list of issued serial keys can be downloaded in CSV format.

Serial key status

A serial key has the following states

  • ACTIVE
  • USED
  • INACTIVE

ACTIVE is when the serial key is actually available to the player, and USED is when it has been used. INACTIVE is when the serial key has been deactivated by management.

Campaign

Both serial codes and campaign codes are part of a campaign.

Campaigns can be associated with GS2-Schedule events to set a valid period. The “Campaign Code” can be any alphanumeric string specified as the “Campaign Name” and can be set to allow redemption with the Campaign Code.

Transaction Actions

GS2-SerialKey provides the following transaction actions:

  • Verify Action: Verify serial code validity
  • Consume Action: Mark serial code as used
  • Acquire Action: Revert serial code to unused (for cancellation), Issue serial code

By using “Issue serial code” as an acquire action, it is possible to safely perform processes within a transaction to automatically issue and gift a unique serial code (transferable to others) to a player upon achieving 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 redemption by code

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

Typically, there should be a requirement that the code cannot be redeemed again once it has been redeemed, or that the code cannot be redeemed for a certain period of time, and so on. There are various requirements for campaign codes or serial keys, such as “a limit on the total number of redemptions in the same campaign”.

GS2-SerialKey does not have such a limit function, but only provides a function to determine if the entered serial key is valid. Therefore, GS2-SerialKey itself has no reward for performing the exchange.

An example implementation of 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 for using the serial key, and GS2-Limit applies a redemption count limit, preventing items from being obtained multiple times.

Example implementation

Using serial keys

It is not recommended to process using serial keys with this API.

It is recommended to use a service such as GS2-Exchange to perform some processing instead of using serial keys.

    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;

Detailed Reference

Reference of GS2-SerialKey