GS2-SerialKey SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-SerialKey SDK のモデルの仕様と API のリファレンス

モデル

EzSerialKey

シリアルコード

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

型

有効化条件

必須

デフォルト

値の制限

説明

campaignModelName

string

✓

~ 128文字

キャンペーン名

このシリアルコードが属するキャンペーンモデルの名前です。キャンペーン情報はシリアルコード自体に埋め込まれているため、コード使用時にはネームスペースを指定するだけで利用できます。

metadata

string

~ 2048文字

メタデータ

メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。

code

string

✓

~ 48文字

シリアルコード

「XXXXX-XXXX-XXXXX-XXXX-XXXX」形式のシリアルコード文字列です。各コードは一意で、キャンペーン識別情報が含まれています。コードの形式とデータ長は固定で変更できません。

status

文字列列挙型
enum {
  “ACTIVE”,
  “USED”,
  “INACTIVE”
}

“ACTIVE”

ステータス

このシリアルコードの現在の使用状態です。ユーザーが消費すると ACTIVE から USED に遷移します。二重使用を防ぐため楽観的ロックで保護されています。INACTIVE のコードは使用できません。

定義	説明
“ACTIVE”	利用可能
“USED”	使用済み
“INACTIVE”	無効（利用不可）

EzCampaignModel

キャンペーンモデル

キャンペーンモデルはキャンペーンを定義し、シリアルコードと紐づけて管理するために使用されます。

	型	必須	デフォルト	値の制限	説明
name	string	✓		~ 128文字	キャンペーンモデル名
metadata	string			~ 2048文字	メタデータメタデータには任意の値を設定できます。これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。
enableCampaignCode	bool		false		キャンペーンコードによる引き換えを許可するか有効にすると、個別のシリアルコードではなく共通のキャンペーンコード（キャンペーン名）を使って報酬を引き換えられるようになります。これにより、1つのコードを複数のユーザーが使用できます。

メソッド

getCampaignModel

特定のシリアルコードキャンペーンの詳細を取得する

キャンペーン名を指定して、設定を含む詳細を取得します。

キャンペーンモデルは、同じ目的と設定を共有するシリアルコードのグループを定義します。
たとえば「リリース記念コード」「雑誌プロモーションコード」「イベント配布コード」などを別々のキャンペーンとして管理できます。

レスポンスには以下が含まれます:

キャンペーン名とメタデータ
キャンペーンが現在有効でコードの引き換えを受け付けているかどうか

コード入力画面を表示する前にキャンペーンの詳細を確認する際に使います。たとえばプレイヤーにシリアルコードを入力させる前に、キャンペーンが有効かどうかを確認できます。

Request

	型	有効化条件	必須	デフォルト	値の制限	説明
namespaceName	string		✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
campaignModelName	string		✓		~ 128文字	キャンペーンモデル名

Result

	型	説明
item	EzCampaignModel	キャンペーンモデル

実装例

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).CampaignModel(
        campaignModelName: "1111campaign-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).CampaignModel(
        campaignModelName: "1111campaign-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->CampaignModel(
        "1111campaign-0001" // campaignModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).CampaignModel(
        campaignModelName: "1111campaign-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).CampaignModel(
        campaignModelName: "1111campaign-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->CampaignModel(
        "1111campaign-0001" // campaignModelName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::SerialKey::Model::FCampaignModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

get

シリアルコードの状態を確認する

特定のシリアルコードの詳細を取得します。使用済みかどうか、どのキャンペーンに属しているかなどの情報が含まれます。

コードの引き換え前後に状態を確認する際に使います。たとえば:

プレイヤーが既に使用されたコードを入力した場合に「このコードは既に使用されています」と表示する
プレイヤーが引き換えを確定する前にキャンペーン情報（コードで得られる報酬）を表示する
カスタマーサポート目的でコードを調べる

コードは「XXXXX-XXXX-XXXXX-XXXX-XXXXX」のような形式です。
レスポンスにはシリアルコードの詳細と、関連するキャンペーンモデルが含まれます。

Request

	型	有効化条件	必須	デフォルト	値の制限	説明
namespaceName	string		✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
code	string		✓		~ 48文字	シリアルコード「XXXXX-XXXX-XXXXX-XXXX-XXXX」形式のシリアルコード文字列です。各コードは一意で、キャンペーン識別情報が含まれています。コードの形式とデータ長は固定で変更できません。

Result

	型	説明
item	EzSerialKey	シリアルコード
campaignModel	EzCampaignModel	キャンペーンモデル

実装例

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).SerialKey(
        serialKeyCode: "code-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).SerialKey(
        serialKeyCode: "code-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->SerialKey(
        "code-0001" // serialKeyCode
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).SerialKey(
        serialKeyCode: "code-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).SerialKey(
        serialKeyCode: "code-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->SerialKey(
        "code-0001" // serialKeyCode
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::SerialKey::Model::FSerialKey> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

useSerialCode

シリアルコードを引き換える

シリアルコードを使用（消費）し、現在のプレイヤーによって引き換え済みとしてマークします。
一度使用されたコードは、誰も再使用できません。

ゲーム内の「シリアルコード入力」機能で使うメインAPIです。一般的な流れ:

プレイヤーがゲーム内の「コード引き換え」画面を開く
プレイヤーがシリアルコードを入力する（プロモーションカード、メール、Webサイトなどから入手したもの）
ゲームが入力されたコードで UseSerialCode を呼び出す
成功した場合、コードが使用済みとなる — 報酬配布システムと組み合わせてプレイヤーに報酬を付与する
コードが既に使用済みの場合、「使用済み」エラーが返される
コードが存在しない場合、「コードが見つかりません」エラーが返される

主な使い方:

グッズや雑誌に同梱されるプロモーションコード
イベントやSNSで配布されるギフトコード
事前登録特典コード
コラボレーションキャンペーンコード

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSession	GameSession	✓		GameSession
code	string	✓	~ 48文字	シリアルコード「XXXXX-XXXX-XXXXX-XXXX-XXXX」形式のシリアルコード文字列です。各コードは一意で、キャンペーン識別情報が含まれています。コードの形式とデータ長は固定で変更できません。

Result

	型	説明
item	EzSerialKey	シリアルコード
campaignModel	EzCampaignModel	キャンペーンモデル

Error

このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法はこちらのドキュメントを参考にしてください。

型	基底クラス	説明
AlreadyUsedException	BadRequestException	指定されたシリアルコードはすでに使用されています
CodeNotFoundException	NotFoundException	指定されたシリアルコードは存在しません

実装例

try {
    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SerialKey(
        serialKeyCode: "code-0001"
    );
    var result = await domain.UseSerialCodeAsync(
        code: "code-0001"
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2SerialKey.Exception.AlreadyUsedException e) {
    // The specified serial code has already been used.
} catch(Gs2.Gs2SerialKey.Exception.CodeNotFoundException e) {
    // The specified serial code does not exist.
}

    var domain = gs2.SerialKey.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SerialKey(
        serialKeyCode: "code-0001"
    );
    var future = domain.UseSerialCodeFuture(
        code: "code-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2SerialKey.Exception.AlreadyUsedException)
        {
            // The specified serial code has already been used.
        }
        if (future.Error is Gs2.Gs2SerialKey.Exception.CodeNotFoundException)
        {
            // The specified serial code does not exist.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->SerialKey->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->SerialKey(
        "code-0001" // serialKeyCode
    );
    const auto Future = Domain->UseSerialCode(
        "code-0001" // code
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::SerialKey::Error::FAlreadyUsedError::Class))
        {
            // The specified serial code has already been used.
        }
        if (e->IsChildOf(Gs2::SerialKey::Error::FCodeNotFoundError::Class))
        {
            // The specified serial code does not exist.
        }
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();