Skip to main content

Setting up Server-based

This is the step-by-step guide for setting up the server-based architecture. For general information about architecture see here.

In the Server-based architecture, your game-backend interacts with Idem. This can be either your custom backend or a third-party Game-Backend-as-a-Service (GBaaS; e.g. Pragma, Accelbyte).

Idem integrates with a number of GBaaS out of the box. While Idem can be used with most backends, we provide code samples and integration instructions for these backends particularly.

Server-based architecture can be used through both REST and WebSocket. We recommend WebSocket for any later production use.

🄰 Select Server-based configuration​

Go to the Integration section of the Idem console. There, select Server-based using the toggle on the top. This will hide the server hosting providers. Click Save to persist your selection.

Note: If you want to use the the server-based architecture with game server hosting via Idem (see here), please reach out at match@idem.gg and we'll set that up for you.

🄱 Integrate Idem into your backend server​

This section explains the integration of Idem into a backend server from the ground up. We start with how to get a token for the WebSocket connection, continue to establishing the connection and then look at the messages that can be sent and received.

If you are using one of the game backends we natively integrate with, you can take a shortcut and use that integration directly:

  • Beamable Logo
  • Pragma Logo
  • Redwood Logo

Note: If you are curious to learn more about how the interaction with Idem works, going through the step-by-step guide is still recommended.

① Get IdToken for the WebSocket API from AWS Cognito​

To establish a conncetion to Idem's WebSocket API you need an authentication token. Therefore, the first step before opening a WebSocket connection is getting this token.

This is done by sending a POST request to https://cognito-idp.eu-central-1.amazonaws.com/ with the following data:

Headers

X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
Content-Type: application/x-amz-json-1.1

Body

{
  "AuthParameters": {
    "USERNAME": "idem-10253",
    "PASSWORD": "AVN2ufg3hT36$"
  },
  "AuthFlow": "USER_PASSWORD_AUTH",
  "ClientId": "<client_id>"
}

You find the username and password in the Keys section of the Idem console. The client_id depends on which WebSocket API you are interacting with. New accounts have only the Beta API enabled by default. The client_id for this is 3ns1sc0lkrdqh25qvrqb9k3a80. If you need the client_id for another API, you can find it here.

The response to the request will look like this:

{
    "AuthenticationResult": {
        "AccessToken": "eyJra...MFCmQ",
        "ExpiresIn": 3600,
        "IdToken": "eyJra...xt5zg",
        "RefreshToken": "eyJjd...vbsJA",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

For the next step, you will need the IdToken from this response.

② Establish WebSocket connection with Idem​

Once you have obtained the IdToken you can establish a WebSocket connection with Idem. For this you first need to create a WebSocket URL.

The WebSocket URL will include the following parameters:

ParameterDescription
baseUrlThe base URL for the WebSocket API you are interacting with.
For the default Beta API this is wss://ws.beta.idem.gg. For others see here.
gameModeA comma-separated list of game modes you want to interact with.
New accounts have one default game mode 1v1.
authorizationThe IdToken obtained in the previous step.
receiveMatches(Optional) If this is set to true, Idem will automatically send any match suggestion via this WebSocket. You can then listen for those messages in your code.

The WebSocket URL is created according using the following schema:

{baseURL}/gameMode={gameMode}&authorization={authorization}&receiveMatches=true

Below is an example for a full URL:

wss://ws.beta.idem.gg/?gameMode=1v1,2v2,5v5&authorization=eyJra...xt5zg&receiveMatches=true

Using this URL, connect the WebSocket.

info

Our hosting provider AWS limits WebSocket connections to a maximum duration of 2 hours. So you will need to implement logic to open a new connection latest when the old one is closed.

③ Sending and receiving messages via the WebSocket for creating a match​

Once the WebSocket connection is established, you can start sending and receiving messages from Idem. In this guide we will focus on the core messages for creating matches. You can find all the details in our API docs.

Default flow for a match​

The default flow for a match looks like this:

Server-based architecture default flow
Server-based architecture default flow

During this process the match does through different states. You can find a full overview of states and transitions in the appendix

Let's take a look at the individual steps:

Opening the WebSocket Connection​

This was covered in the previous section

Adding players​

To add a player, simply send an addPlayer message. This has the following format:

{
    "action": "addPlayer",
    "messageId": null,
    "payload": {
        "gameId": "1v1",
        "partyName": null,
        "reference": null,
        "players": [
            {
                "playerId": "player-xJjqJ60XtF",
                "servers": {
                    "frankfurt": 45,
                    "london": 102,
                }
            }
        ]
    }
}

The servers field for can either be:

  • A list of locations (any string is valid)
  • A object-shaped ping-map (as in the example above)

You can find details about all other fields here.

info

If you have a custom game configuration, additional fields might be required.

Once the player was successfully added to the system, Idem will reponse with an addPlayerResponse to confirm the adding.

{
    "action": "addPlayerResponse",
    "payload": {
        "gameId": "1v1",
        "players": [
            {
                "playerId": "player-xJjqJ60XtF",
                "reference": null
            }
        ]
    }
}
Receiving matches​

If you established the WebSocket connection with the receiveMatches parameter, Idem will automatically send you any new match suggestion it creates. They will come in as a matchSuggestion message like this:

{
    "action": "matchSuggestion",
    "payload": {
        "gameId": "1v1",
        "match": {
            "uuid": "e8d3b431-70d8-4add-8794-33784f61a0a9",
            "teams": [
                {
                    "players": [
                        {
                            "playerId": "player-xJjqJ60XtF",
                            "reference": null,
                            "rating": "1500",
                            "ranking": "0"
                        }
                    ]
                },
                {
                    "players": [
                        {
                            "playerId": "player-eEMHB0eHZS",
                            "reference": null,
                            "rating": "1500",
                            "ranking": "0"
                        }
                    ]
                }
            ],
            "server": "frankfurt"
        }
    }
}
info

The message is showing the data of two new players. Therefore both have the (customizable) default rating of 1500 and 0 ranking points.

The matchSuggestion includes all information you need to set up the match:

  • The server location Idem would recommend for the players
  • The gameId so you can host the right game mode
  • The uuid of the match for further handling
  • The teams and players
    The example shows a 1v1. For other game modes the structure of the teams object would match the player arrangement of that mode.

Idem will resend this information with exponential backoff until you acknowledge receiving the match with a matchSuggestionDeliveryAction to make sure it is received by your servcer. The maximum number of resends is 5.

{
    "action": "matchSuggestionDelivery",
    "messageId": null,
    "payload": {
        "gameId": "1v1",
        "matchId": "e8d3b431-70d8-4add-8794-33784f61a0a9"
    }
}

This in turn will be acknowledged by Idem with a matchSuggestionDeliveryResponse to close the loop:

{
    "action": "matchSuggestionDeliveryResponse",
    "payload": {
        "gameId": "1v1",
        "matchId": "e8d3b431-70d8-4add-8794-33784f61a0a9"
    }
}
Confirming a match​

Once you have created the actual match (i.e. hosted the server, sent the join info to players, etc.) you send a confirmMatchAction to Idem to sync the state with your system:

{
    "action": "updateMatchConfirmed",
    "messageId": null,
    "payload": {
        "gameId": "1v1",
        "matchId": "e8d3b431-70d8-4add-8794-33784f61a0a9"
    }
}

Idem will acknowledge this with an updateMatchConfirmedResponse:

{
    "action": "updateMatchConfirmedResponse",
    "payload": {
        "gameId": "1v1",
        "matchId": "e8d3b431-70d8-4add-8794-33784f61a0a9"
    }
}
Completing a match​

Finally, once the match has ended, you report the result to Idem so that we can update the rating and ranking of the involved players. This is done with the completeMatchAction:

{
    "action": "updateMatchCompleted",
    "messageId": null,
    "payload": {
        "gameId": "1v1",
        "matchId": "e8d3b431-70d8-4add-8794-33784f61a0a9",
        "server": "test",
        "gameLength": 50,
        "teams": [
            {
                "rank": 0,
                "players": [
                    {
                        "playerId": "player-xJjqJ60XtF",
                        "score": 1
                    }
                ]
            },
            {
                "rank": 1,
                "players": [
                    {
                        "playerId": "player-eEMHB0eHZS",
                        "score": 0
                    }
                ]
            }
        ]
    }
}
info

Depending on the setup of your game, the teams object in the completeMatchAction might need to look different. If you are not sure which format to use, reach out at match@idem.gg.

Idem will respond to this message with a completeMatchResponse including detailed information about all players after the updates from the match. E.g.:

{
    "action": "updateMatchCompletedResponse",
    "payload": {
        "players": [
            {
                "playerId": "player-eEMHB0eHZS",
                "reference": null,
                "totalMatchesPlayed": 1,
                "totalWins": 0,
                "totalLosses": 1,
                "season": "S1",
                "seasonMatchesPlayed": 1,
                "seasonWins": 0,
                "seasonLosses": 1,
                "matchesPlayed": 1,
                "wins": 0,
                "losses": 1,
                "rating": 1490.0,
                "ratingDeltaLastGame": -10.0,
                "rankingPoints": 0.0,
                "rankingDeltaLastGame": 0.0
            },
            {
                "playerId": "player-xJjqJ60XtF",
                "reference": null,
                "totalMatchesPlayed": 1,
                "totalWins": 1,
                "totalLosses": 0,
                "season": "S1",
                "seasonMatchesPlayed": 1,
                "seasonWins": 1,
                "seasonLosses": 0,
                "matchesPlayed": 1,
                "wins": 1,
                "losses": 0,
                "rating": 1510.0,
                "ratingDeltaLastGame": 10.0,
                "rankingPoints": 10.0,
                "rankingDeltaLastGame": 10.0
            }
        ],
        "gameId": "1v1",
        "matchId": "e8d3b431-70d8-4add-8794-33784f61a0a9"
    }
}

This concludes the flow for handling one match.

Additional notes​

Consistent player state​

Idem has a strong focus on maintaining a consistent state of your matchmaking system. Therefore no player (i.e. playerId) can be in the system twice at the same time.

If you try to add a player to a matchmaking queue that is already in the system, you will receive a 409 error. There are two cases:

  1. The player is not matched yet
    In this case the error will have the id party_exists_waiting with the message Party <playerId> exists with 1 players. If you want to remove the player, you can send a removePlayerAction (see here) to remove the previously added player from the system.
  2. The player is already matched
    In this case the error will have the id party_exists_matched with the message Party <playerId> exists with 1 players. In this case the player is in a match that has not been confirmed or failed yet. You cannot remove players when they have been matched. Once you confirm or fail the match they will be automatically "free up" for being added again.
keepAlive​

While the WebSocket connection is open, Idem will send a keepAlive message every minute. This has the following format:

{
    "action": "keepAlive",
    "payload": {}
}

Appendix​

Match states and transitions​

The following chart gives an overview of the states a match has while going through the matchmaking process.

Match states and transitions
Match states and transitions