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

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

モデル

EzTrigger

トリガー

相対イベントスケジューリングの起点を定義し、プレイヤーごとのイベント期間を実現します。
プレイヤーに対してトリガーが発動されると、発動時刻（triggeredAt）と有効期限（expiresAt）が記録されます。
“relative” スケジュールタイプで設定されたイベントはトリガーを名前で参照し、そのプレイヤーのイベント期間はトリガーの発動時刻から有効期限まで続きます。
トリガーは更新可能（createdAt をリセットし expiresAt を更新）で、有効期限後は TTL により自動的にクリーンアップされます。

	型	必須	デフォルト	値の制限	説明
triggerId	string	※		~ 1024文字	トリガー GRN ※ サーバーが自動で設定
name	string	✓		~ 128文字	トリガー名トリガー固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
createdAt	long	※	現在時刻		作成日時 UNIX 時間・ミリ秒 ※ サーバーが自動で設定
expiresAt	long	✓			有効期限このトリガーが期限切れとなり、相対イベント期間が終了するタイムスタンプ。この時刻以降、トリガーは期限切れと見なされ（IsExpire が true を返す）、このプレイヤーに対する関連する相対イベントは無効になります。トリガーデータは有効期限後に DynamoDB TTL により自動的にクリーンアップされます。UNIX 時間（ミリ秒）で表現されます。

EzEvent

イベント

イベントの期間は絶対期間と相対期間の2種類存在します。
絶対期間は例えば YYYY年MM月DD日 00:00(UTC) ～ YYYY年MM月DD日 23:59(UTC) のような固定の期間で、
相対期間はトリガーを引いたタイミングから 24時間のようなゲームプレイヤー毎に異なる期間をイベント期間とするものです。

イベントには開催期間だけでなく、繰り返しが設定できるようになっており
イベント期間のうち、月曜日の 10:00 ～ 11:00 だけをイベント期間とするような設定も可能です。

型有効化条件必須デフォルト値の制限説明

name

string

✓

~ 128文字

イベント名

イベント固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

metadata

string

~ 2048文字

メタデータ

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

scheduleType

文字列列挙型
enum {
“absolute”,
“relative”
}

✓

スケジュールタイプ

イベント期間の定義方法を決定します。
“absolute” は全プレイヤー共通の固定開始・終了タイムスタンプを使用します。
“relative” はプレイヤーごとのトリガーを起点として使用し、パーソナライズされたイベント期間を実現します（例: 各プレイヤーの初回ログインから24時間）。

定義	説明
“absolute”	固定期間
“relative”	プレイヤー毎に異なる期間

absoluteBegin

long

絶対開始日時

絶対スケジューリングにおけるイベント期間の固定開始時刻。
全プレイヤーが同じ開始時刻を共有します。絶対イベントで未設定の場合、イベントは過去から開始されているものとして扱われます。
UNIX 時間（ミリ秒）で表現されます。

absoluteEnd

long

絶対終了日時

絶対スケジューリングにおけるイベント期間の固定終了時刻。
全プレイヤーが同じ終了時刻を共有します。絶対イベントで未設定の場合、イベントは終了しないものとして扱われます。
UNIX 時間（ミリ秒）で表現されます。

relativeTriggerName

string

{scheduleType} == “relative”

✓※

~ 128文字

イベント開始トリガー名

ゲームプレイヤー毎にイベント期間を設定する (relative) 場合に、イベントの開始の起点とするトリガーの名前を指定します。
英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

※ scheduleType が “relative” であれば必須

EzRepeatSchedule

繰り返しスケジュール状態

特定の時点におけるイベントの繰り返しサイクルの現在の状態を表します。
繰り返し回数（サイクルが発生した回数）、現在のアクティブウィンドウの開始・終了時刻、
前回完了したウィンドウの終了時刻、および次回のウィンドウの開始時刻を含みます。
この情報はイベントの繰り返し設定と現在時刻から動的に計算されます。

	型	必須	値の制限	説明
repeatCount	int	✓	0 ~ 2147483646	繰り返し回数現在時刻までに完了した繰り返しサイクルの回数。繰り返しウィンドウが終了するたびにインクリメントされます。シーズン制や定期イベントのサイクル進捗の追跡に使用できます。
currentRepeatStartAt	long			現在のリピート開始日時現在アクティブな繰り返しウィンドウの開始時刻。イベントが現在アクティブな繰り返しウィンドウにない場合は null です。UNIX 時間（ミリ秒）で表現されます。
currentRepeatEndAt	long			現在のリピート終了日時現在アクティブな繰り返しウィンドウの終了時刻。イベントが現在アクティブな繰り返しウィンドウにない場合は null です。UNIX 時間（ミリ秒）で表現されます。
lastRepeatEndAt	long			前回のリピート終了日時直近で完了した繰り返しウィンドウの終了時刻。まだ繰り返しウィンドウが終了していない場合は null です。UNIX 時間（ミリ秒）で表現されます。
nextRepeatStartAt	long			次回のリピート開始日時次回の繰り返しウィンドウの開始時刻。イベント期間内に次の繰り返しウィンドウがない場合は null です。UNIX 時間（ミリ秒）で表現されます。

メソッド

getTrigger

特定のトリガーの状態を取得する

名前を指定して特定のトリガーを取得し、いつ有効化されたか、いつ期限切れになるかを確認できます。
特定のトリガーの状態を確認するのに使います。たとえば「first_login」トリガーがまだ有効か、期限切れまでの残り時間はどれくらいかを確認し、「初心者ボーナス終了まで残り3日12時間」のように関連イベントのカウントダウンを表示する場合に便利です。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
triggerName	string	✓	~ 128文字	トリガー名トリガー固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSession	GameSession	✓		GameSession

Result

	型	説明
item	EzTrigger	トリガー

実装例

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Trigger(
        "trigger1" // triggerName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

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

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

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

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

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

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

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

Warning

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

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

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

listTriggers

プレイヤーの有効なトリガー一覧を取得する

プレイヤーに対して現在有効なすべてのトリガーを取得します。
トリガーは、相対スケジュールイベントを有効化するためのプレイヤー固有のタイマーです。トリガーが「引かれる」（有効化される）と、カウントダウンが始まり、そのトリガーに紐づいたイベントがプレイヤーに対して有効になります。
たとえば「first_login」トリガーが「7日間初心者ボーナス」イベントを有効化したり、「first_purchase」トリガーが「24時間サンキューセール」イベントを有効化したりします。
各トリガーには有効期限があり、期限が切れると、そのプレイヤーに対する関連イベントも終了します。
プレイヤーにどのトリガーが現在有効か確認するのに使います。たとえば、ステータス画面で「初心者ボーナス: 有効（残り5日で期限切れ）」と表示する場合に便利です。

Request

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

Result

	型	説明
items	List<EzTrigger>	トリガーのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.TriggersAsync(
    ).ToListAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Triggers(
    );
    List<EzTrigger> items = new List<EzTrigger>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Triggers(
    );
    TArray<Gs2::UE5::Schedule::Model::FEzTriggerPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

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

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeTriggers(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

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

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeTriggers(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

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

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeTriggers(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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

getEvent

特定のイベントのスケジュール状態を取得する

名前を指定して特定のイベントを、プレイヤーに対する現在のスケジュール状態とともに取得します。
レスポンスには、イベントが現在開催中か（inSchedule）、開始・終了時刻、該当する場合は繰り返しスケジュール情報が含まれます。
相対スケジュールイベントの場合、終了時刻はプレイヤーのトリガーに基づいて計算されるため、同じイベントでもプレイヤーによって終了時刻が異なる場合があります。
特定のイベントが開催中か確認し、残り時間を表示するのに使います。たとえば「サマーイベント: 残り3日」「初心者ボーナス: 残り12時間」のようにカウントダウンタイマーとともに表示するのに便利です。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
eventName	string	✓	~ 128文字	イベント名イベント固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSession	GameSession	✓		GameSession

Result

	型	説明
item	EzEvent	イベント
inSchedule	bool	現在イベント期間中か
scheduleStartAt	long	イベント期間開始時刻
scheduleEndAt	long	イベント期間終了時刻イベントの種類が absolute なら EventModel の absoluteEnd が格納されます。イベントの種類が relative なら scheduleEndAt にはトリガーの有効期限または EventModel の absoluteEnd のどちらか終了が近い方が格納されます。
repeatSchedule	EzRepeatSchedule	繰り返し情報
isGlobalSchedule	bool	イベントがグローバルスケジュールか

実装例

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Event(
        "event-0001" // eventName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

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

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

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

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

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

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

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

Warning

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

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

listEvents

プレイヤーの現在開催中のイベント一覧を取得する

このプレイヤーに対して現在開催中のすべてのイベントを取得します。
イベントには2種類あります:

絶対スケジュールイベント: 全プレイヤー共通の固定日時イベント（例: 「クリスマスイベント: 12月24日〜25日」「サマーセール: 7月1日〜31日」）
相対スケジュールイベント: トリガーが有効化された時点からプレイヤーごとに開始するイベント（例: 初回ログインから始まる「7日間初心者ボーナス」、レベル10到達から始まる「24時間限定フラッシュセール」）
現在開催期間中のイベントのみが返されます。
今どんなイベントが開催中かプレイヤーに表示するのに使います。たとえば、ホーム画面にイベントバナーを表示したり、イベント専用UIを有効にする場合に便利です。

Request

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

Result

	型	説明
items	List<EzEvent>	イベントのリスト

実装例

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.EventsAsync(
    ).ToListAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Events(
    );
    List<EzEvent> items = new List<EzEvent>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Events(
    );
    TArray<Gs2::UE5::Schedule::Model::FEzEventPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

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

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeEvents(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

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

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeEvents(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

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

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeEvents(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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