> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-SerialKey

シリアルコード機能




ゲーム外の物販やリアルイベント、SNSキャンペーン、コラボキャンペーンなどを通じてゲーム内アイテムを配布したい場合に使用できます。
紙のパッケージや QR コードに印字したコード、メール／SNS で配布する文字列のいずれも同じ仕組みで取り扱うことができます。

ただし、この機能は一部プラットフォーマーは実装を許していないため、採用にあたってはプラットフォーマーのガイドラインを確認するようにしてください。

## シリアルコードの種類

シリアルコードは以下の2種類があります。

- シリアルキー：1回使用すると再利用できないコード
- キャンペーンコード：1つのコードを複数人で共有できるコード

```mermaid
graph TD
  SerialCode["シリアルコード"]
  SerialCode --> SerialKey["シリアルキー<br/>1人1回限定"]
  SerialCode --> CampaignCode["キャンペーンコード<br/>複数人で共用"]
  SerialKey --> SerialKeyUse["RPCLP-FP7N-NCDMJ-FLVA-IRI4"]
  CampaignCode --> CampaignCodeUse["NEWYEAR2026"]
```

### シリアルキー

1回使用すると2度と使用できなくなるコード です。

シリアルキーは「RPCLP-FP7N-NCDMJ-FLVA-IRI4」のような形式で発行され、データ長を変更することはできません。
シリアルキー内にはキャンペーンの種類の情報も含まれており、シリアルキーを使用する際にはネームスペースを指定するだけで使用できます。

### キャンペーンコード

「ハロウィン2025」「SUMMER」のように人間にとって覚えやすい文字列を、運営側が任意に設定できるコード です。
1つのコードを多数のプレイヤーが共有して引き換えに使用することを想定しています。

キャンペーンコードはキャンペーンに紐づけて発行する シリアルキー とは異なり、キャンペーンの名前自体がコードとして引き換え可能になります。

## キャンペーン

「シリアルキー」も「キャンペーンコード」もキャンペーンに属します。

キャンペーンには以下を設定します。

- `name`: キャンペーン名（キャンペーンコードとしても利用される）
- `metadata`: 任意のメタデータ
- `enableCampaignCode`: キャンペーンコード（キャンペーン名そのものを使った引き換え）を有効化するか

キャンペーンは GS2-Schedule のイベントと関連づけることで有効期間を設定することが可能です。
有効期間の検証はトランザクションアクションを組み合わせて実現できます。

### シリアルキーの発行

対象のキャンペーンと発行数量を指定してシリアルキーの発行処理を実行することで、シリアルキーが発行されます。
発行処理は非同期ジョブとして実行され、`IssueJob` を介して進捗を確認できます。
発行されたシリアルキーのリストはCSV形式でダウンロードが可能です。

物販パッケージに印字するなど、大量に発行する用途では数十万件単位での発行も可能です。

### シリアルキーの状態

シリアルキーは以下の状態を持ちます。

| 状態 | 説明 |
| --- | --- |
| `ACTIVE` | プレイヤーが利用可能な状態 |
| `USED` | 既に使用済み（再利用不可） |
| `INACTIVE` | 運営によって無効化された状態 |

実際にプレイヤーが利用できる状態が `ACTIVE` で、使用すると `USED` になります。
運営サイドでシリアルキーを無効化すると `INACTIVE` になります。

## トランザクションアクション

GS2-SerialKey では以下のトランザクションアクションを提供しています。

- 検証アクション: シリアルコードの有効性の検証、シリアルコードが指定キャンペーンに属することの検証
- 消費アクション: シリアルコードの使用済み化
- 入手アクション: シリアルコードの未使用化（キャンセル用）、シリアルコードの発行

「シリアルコードの発行」を入手アクションとして利用することで、ゲーム内の特定のミッションを達成した際や、上位入賞の報酬として、プレイヤーごとにユニークなシリアルコード（他者へ譲渡可能）を自動発行してプレゼントするといった処理を、トランザクション内で安全に完結させることが可能になります。これにより、ゲーム外でのファン交流や、プレイヤー間でのプレゼント要素を促進する施策が容易になります。

### コードによる引き換え回数制限

キャンペーンコードでの引き換えは何もしなければ、何回でも引き換えが可能です。

普通は「一度引き換えを行ったら二度と引き換えできなくする」か「一定期間引き換えをできなくしたい」といった要件があるはずですし、
キャンペーンコードにしろ、シリアルキーにしろ「同一キャンペーンでの引き換え可能な総回数に制限を設けたい」など、様々な要件があるはずです。

GS2-SerialKey はそのような制限機能はもたず、純粋に入力されたシリアルキーが有効かだけを判断する機能を提供します。
そのため、GS2-SerialKey 自身は交換を実行した時に得られる報酬も持ちません。

シリアルキーを使用する場合の実装例を以下に示します。

```plantuml
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 例です。

```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 といったサービスを通してシリアルキーの使用を行うことで、シリアルキーの使用と報酬の付与・回数制限のチェックを一連のトランザクションとして扱うことができます。



**Unity**
```csharp

    var result = await gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SerialKey(
        code: "code-0001"
    ).UseSerialCodeAsync(
    );
    var item = await result.ModelAsync();
```
**Unreal Engine**
```cpp

    const auto Future = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->SerialKey(
        "code-0001" // code
    )->UseSerialCode(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
```


### シリアルキーの情報を取得

シリアルキーのコードを指定して、そのコードが所属するキャンペーンや現在の状態（`ACTIVE` / `USED` / `INACTIVE`）を確認できます。
引き換え画面で「入力されたコードは既に使用済みです」のようなエラーメッセージを表示する用途にも使用できます。



**Unity**
```csharp

    var item = await gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SerialKey(
        code: "code-0001"
    ).ModelAsync();
```
**Unreal Engine**
```cpp

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->SerialKey(
        "code-0001" // code
    );
    const auto Item = Domain->Model();
```


### キャンペーン情報を取得

特定のキャンペーンの定義（メタデータ、キャンペーンコードの有効・無効など）を取得します。



**Unity**
```csharp

    var item = await gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).CampaignModel(
        campaignModelName: "newyear-2026"
    ).ModelAsync();
```
**Unreal Engine**
```cpp

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->CampaignModel(
        "newyear-2026" // campaignModelName
    );
    const auto Item = Domain->Model();
```


## 詳細なリファレンス

[GS2-SerialKey API リファレンス](../../api_reference/serial_key)