GS2-Gateway SDK for Game Engine API Reference

Specifications of models and API references for GS2-Gateway SDK for Game Engine

Models

EzWebSocketSession

WebSocketSession

A WebSocket session is a persistent connection between a GS2 server and a client for real-time bidirectional communication. The client registers a user ID as an identifier to the server.

	Type	Required	Value Limits	Description
connectionId	string	✓	~ 128 chars	Connection ID The unique identifier assigned to this WebSocket connection. Used to identify the specific client connection when sending notifications.
namespaceName	string	✓	~ 128 chars	Namespace name
userId	string	✓	~ 128 chars	User ID

EzFirebaseToken

Firebase Device Token

A Firebase Device Token is required to use mobile push notifications.

GS2-Gateway provides in-game push notification functionality, allowing you to receive push notifications when matchmaking is completed or missions are accomplished, If the target player is offline, the notification can be forwarded as a mobile push notification.

The Firebase Device Token is used to identify the device to be notified. As the name suggests, Firebase is an external service, so please refer to the Firebase documentation for detailed information on how to obtain the token.

	Type	Required	Value Limits	Description
userId	string	✓	~ 128 chars	User ID
token	string	✓	~ 1024 chars	Device Token for Firebase Cloud Messaging The FCM registration token obtained from the client device. Identifies the specific device to deliver mobile push notifications to when the player is offline and cannot receive in-game WebSocket notifications. The token is device-specific and may change when the app is reinstalled or data is cleared.
locale	string		~ 32 chars	Locale of the notification message The locale of the messages to deliver to this device. It is a free-form string such as `ja` or `en`, and is not restricted to a fixed list of values. When a notification is forwarded to a mobile push notification and its payload is a JSON that contains a `mobile` array of `{locale, message}` entries, the entry whose locale matches this value is used as the body of the push notification. If no entry matches, the entry whose locale is `default` is used, and if that is missing as well, the first entry of the array is used. If the payload is not in that format, the payload is used as is. This field is optional; when it is not set, only the `default` entry, the first entry, or the raw payload applies.

Methods

setUserId

Links the current WebSocket connection to the player’s user ID so that the server can send real-time push notifications to this client. This is typically called right after the player logs in and connects to the server — without this step, the server won’t know which connection belongs to which player. The allowConcurrentAccess flag controls whether the same player can be connected from multiple devices at once:

true: allows multiple simultaneous connections (e.g., playing on both phone and tablet)
false: only one connection per player is allowed (e.g., to prevent duplicate logins — the old connection gets kicked) Use this as part of your game’s login/initialization flow to enable features like real-time chat notifications, friend request alerts, or match-found notifications.

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name
gameSession	GameSession		✓			GameSession
allowConcurrentAccess	bool			true		Whether to allow connections from different clients at the same time
sessionId	string	{allowConcurrentAccess} == false			~ 128 chars	Specifies a session ID that allows reconnection when allowConcurrentAccess is false and the existing connection has the same session ID.

Result

	Type	Description
item	EzWebSocketSession	WebSocket session updated

Implementation Example

    var domain = gs2.Gateway.Namespace(
        namespaceName: "$hash"
    ).Me(
        gameSession: GameSession
    ).WebSocketSession(
    );
    var result = await domain.SetUserIdAsync(
        allowConcurrentAccess: true,
        sessionId: null
    );
    var item = await result.ModelAsync();

    var domain = gs2.Gateway.Namespace(
        namespaceName: "$hash"
    ).Me(
        gameSession: GameSession
    ).WebSocketSession(
    );
    var future = domain.SetUserIdFuture(
        allowConcurrentAccess: true,
        sessionId: null
    );
    yield return future;
    if (future.Error != null)
    {
        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->Gateway->Namespace(
        "$hash" // namespaceName
    )->Me(
        GameSession
    )->WebSocketSession(
    );
    const auto Future = Domain->SetUserId(
        true // allowConcurrentAccess
        // sessionId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        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();

var domain = ez.gateway.namespace_(
        "$hash"
    ).me(game_session).web_socket_session(
    )

var async_result = await domain.set_user_id(
    true, # allow_concurrent_access
    null # session_id
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

deleteFirebaseToken

Stop delivering mobile push notifications to this device

Deletes the FCM device token registered for the player. Once deleted, notifications that arrive while the player is offline are no longer forwarded as mobile push notifications; only in-game WebSocket notifications remain. Call this when the player logs out (so that the next player on a shared device does not receive the previous player’s notifications), or when the player turns notifications off in the game’s settings screen. Deleting the token does not affect anything else about the account — the player can start receiving mobile push notifications again simply by registering a token.

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession		✓			GameSession

Result

	Type	Description
item	EzFirebaseToken	Firebase Device Token deleted

Implementation Example

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    var result = await domain.DeleteFirebaseTokenAsync(
    );

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    var future = domain.DeleteFirebaseTokenFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Gateway->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->FirebaseToken(
    );
    const auto Future = Domain->DeleteFirebaseToken(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

var domain = ez.gateway.namespace_(
        "namespace-0001"
    ).me(game_session).firebase_token(
    )

var async_result = await domain.delete_firebase_token(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

getFirebaseToken

Get the device token currently registered for the player

Retrieves the FCM device token that is currently registered for the player. Use this to check whether the player has already registered a token on this device — for example, to decide whether you need to ask for notification permission and register a token, or to show the current state on a “notification settings” screen. If no token has been registered, the request fails with a not-found error, so treat that case as “notifications are not set up yet”. Note that the registered token may belong to a different device the player used before, so compare it with the token the Firebase SDK gives you on this device before deciding that registration can be skipped.

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession		✓			GameSession

Result

	Type	Description
item	EzFirebaseToken	Firebase Device Token

Implementation Example

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    var item = await domain.ModelAsync();

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

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

var domain = ez.gateway.namespace_(
        "namespace-0001"
    ).me(game_session).firebase_token(
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

Value change event handling

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->Gateway->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->FirebaseToken(
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Gateway::Model::FFirebaseToken> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

var domain = ez.gateway.namespace_(
        "namespace-0001"
    ).me(game_session).firebase_token(
    )

# Start event handling
var callback_id = domain.subscribe_model(func(value):
    # Called when the value changes
    # The value after the change is passed to "value".
    pass
)

# Stop event handling
domain.unsubscribe_model(callback_id)

Warning

This event is triggered when the value stored in the SDK’s local cache changes.

The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

setFirebaseToken

Registers (or refreshes) the FCM device token obtained from the Firebase SDK on the player’s device. Push notifications from the server are normally delivered over the player’s WebSocket connection, but when the player is offline and has no WebSocket session, the notification is forwarded to a mobile push notification using the token registered here. This lets you reach players who have closed the game — for example, “matchmaking is complete”, “your stamina is full”, or “a friend request has arrived”. Call this right after login, once the Firebase SDK has handed you a token, and call it again every time Firebase reports a token refresh: the token is device specific and changes when the app is reinstalled, the data is cleared, or Firebase decides to rotate it. If a token is already registered for the player it is simply overwritten, so it is safe to call this every time the game boots. Pass the player’s language setting in locale (for example ja or en) so that, when a notification payload carries messages in several languages, the message matching that locale is the one used for the mobile push notification.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession
token	string	✓	~ 1024 chars	Device Token for Firebase Cloud Messaging The FCM registration token obtained from the client device. Identifies the specific device to deliver mobile push notifications to when the player is offline and cannot receive in-game WebSocket notifications. The token is device-specific and may change when the app is reinstalled or data is cleared.
locale	string		~ 32 chars	Locale of the notification message The locale of the messages to deliver to this device. It is a free-form string such as `ja` or `en`, and is not restricted to a fixed list of values. When a notification is forwarded to a mobile push notification and its payload is a JSON that contains a `mobile` array of `{locale, message}` entries, the entry whose locale matches this value is used as the body of the push notification. If no entry matches, the entry whose locale is `default` is used, and if that is missing as well, the first entry of the array is used. If the payload is not in that format, the payload is used as is. This field is optional; when it is not set, only the `default` entry, the first entry, or the raw payload applies.

Result

	Type	Description
item	EzFirebaseToken	Firebase Device Token created

Implementation Example

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    var result = await domain.SetFirebaseTokenAsync(
        token: "firebase-token-0001",
        locale: null
    );
    var item = await result.ModelAsync();

    var domain = gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).FirebaseToken(
    );
    var future = domain.SetFirebaseTokenFuture(
        token: "firebase-token-0001",
        locale: null
    );
    yield return future;
    if (future.Error != null)
    {
        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->Gateway->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->FirebaseToken(
    );
    const auto Future = Domain->SetFirebaseToken(
        "firebase-token-0001" // token
        // locale
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        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();

var domain = ez.gateway.namespace_(
        "namespace-0001"
    ).me(game_session).firebase_token(
    )

var async_result = await domain.set_firebase_token(
    "firebase-token-0001", # token
    null # locale
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result