GS2-Gateway

GS2-Gateway provides the ability to maintain a persistent WebSocket connection between the game client and the server, and to deliver notifications from the server at any time.

Normal communication with a game server is a request-response model where the server responds to client requests, but GS2-Gateway enables server-initiated notifications (incoming messages, friend requests, guild invitations, etc.) to be delivered to the client in real time.

sequenceDiagram
  participant Client
  participant Gateway as GS2-Gateway
  participant Service as Each Microservice

  Client->>Gateway: WebSocket Connect
  Client->>Gateway: SetUserId (authenticate)
  Service->>Gateway: SendNotification
  Gateway->>Client: Deliver notification payload

Main features

Persistent WebSocket connection

GS2-Gateway accepts connections from clients using the WebSocket protocol and maintains connection information per user. When a request arrives from another microservice saying “I want to send a notification to this user”, the payload is delivered to the connected client.

The main integration sources are as follows.

• GS2-Inbox: Notification for newly received messages
• GS2-Friend: Notification for friend requests and approvals
• GS2-Guild: Guild join requests and notifications of state changes within a guild
• GS2-Matchmaking: Match completion notification
• GS2-Distributor: Notifications for automatic transaction execution
• GS2-JobQueue: Notification when a new job is queued

Concurrent connection control

In principle, each user within a namespace can hold only one session at a time.

When SetUserId is executed with allowConcurrentAccess set to false, if another session is already connected, the new session can detect this as a concurrent connection error. If set to true, the old session is disconnected at the point when a new session connects.

By using this feature, you can deter concurrent logins from multiple devices. Combined with the automatic password change feature of GS2-Account, you can more strongly prevent account sharing or access from the old device after a takeover.

Firebase Cloud Messaging integration (mobile push notifications)

If you want to deliver notifications even when the client is not running (when the WebSocket is not connected), you can use integration with Firebase Cloud Messaging (FCM).

By registering the FCM server key (or service account credentials) in advance in firebaseSecret of the namespace and registering each user’s FCM token obtained from their device to GS2-Gateway, the integration is in place.

When delivering a notification, GS2-Gateway sends a push notification via FCM using the registered FCM token for users whose WebSocket session does not exist. This allows notifications to be delivered to users even when the app is not running.

By enabling enableTransferMobileNotification on a notification entry, you can control on a per-notification basis whether it is transferred to mobile push.

WebSocket API configuration

The GS2 client SDKs (Unity / Unreal Engine) include a utility that automatically establishes and maintains the GS2-Gateway WebSocket connection.

By specifying GatewaySetting at login time, the WebSocket connection and SetUserId call are performed automatically as part of the login flow.

The configuration items are as follows.

• gatewayNamespaceName: The name of the GS2-Gateway namespace to use
• allowConcurrentAccess: Whether to allow concurrent connections

Transaction Actions

GS2-Gateway does not provide transaction actions.

Master Data Management

GS2-Gateway does not have master data. Configuration such as Firebase integration information and log settings is set in the namespace settings.

Example Implementation

Establishing a WebSocket connection at login

By logging in with GatewaySetting specified, the SDK automatically establishes a WebSocket session and calls SetUserId to associate the user ID.

    var gameSession = await gs2.LoginAsync(
        new Gs2AccountAuthenticator(
            accountSetting: new AccountSetting {
                accountNamespaceName = this.accountNamespaceName,
            },
            gatewaySetting: new GatewaySetting {
                gatewayNamespaceName = "namespace-0001",
                allowConcurrentAccess = false,
            }
        ),
        account.UserId,
        account.Password
    );

    const auto Future = Profile->Login(
        MakeShareable<Gs2::UE5::Util::IAuthenticator>(
            new Gs2::UE5::Util::FGs2AccountAuthenticator(
                AccountNamespaceName,
                KeyId,
                "namespace-0001", // gatewayNamespaceName
                false             // allowConcurrentAccess
            )
        ),
        UserId,
        Password
    );

    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto Result = Future->GetTask().Result();

Explicitly setting the user ID

If you want to associate the user ID with an already-connected WebSocket session, or if you want to change the concurrent access setting after login, call SetUserId.

    var domain = await gs2.Gateway.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).WebSocketSession(
    ).SetUserIdAsync(
        allowConcurrentAccess: false
    );

    const auto Future = Gs2->Gateway->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->WebSocketSession(
    )->SetUserId(
        false // allowConcurrentAccess
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

More practical information

Handling concurrent connection disconnects

While connected with the setting allowConcurrentAccess: false, if the same user logs in from another device, the current WebSocket session is disconnected. The client needs to detect the disconnection event and take appropriate action, such as navigating to a re-login screen or displaying a message like “You have been logged in from another device”.

This effectively allows you to prohibit concurrent play from multiple devices.

Disconnecting all players on a version update

By combining with GS2-Version, when a new version is released you can disconnect all players’ WebSocket sessions, forcing them to pass the version check at reconnection time.

For details, see “Version Update Operating Procedures” in GS2-Version.

Detailed Reference