WebGame Connect - mssgs | Bouw Mini Games voor mssgs

Overzicht

Mini games zijn webpagina's die worden geladen in de mssgs client via een iframe. Het platform regelt alle sessiebeheer, speler tracking en lifecycle - jouw game hoeft alleen te reageren op webhooks en een web UI te renderen.

Hoe het werkt

Een gebruiker maakt een game sessie aan in een server, spelers joinen, en de client van elke speler laadt de URL van jouw game met sessieparameters. Je backend ontvangt webhooks wanneer spelers joinen of vertrekken.

Hoe het werkt

1

Sessie aangemaakt

Een gebruiker maakt een game sessie aan in een server.

2

Spelers joinen

Spelers joinen de sessie via de mssgs client.

3

Game laadt

De client van elke speler laadt jouw web_url met sessieparameters.

4

Webhooks worden verstuurd

Je backend ontvangt webhooks wanneer spelers joinen of vertrekken.

5

Opruimen

Wanneer alle spelers vertrekken, wordt de sessie automatisch opgeruimd.

Game Registratie

Elke game wordt geregistreerd met de volgende velden:

Field	Beschrijving
`name`	Weergavenaam van de game (bijv. "Trivia")
`icon_url`	URL naar het game icoon
`web_url`	Basis URL van de webpagina van de game
`max_players`	Maximaal aantal spelers
`min_players`	Minimaal aantal spelers
`webhook_join_url`	Wordt aangeroepen wanneer een speler joint
`webhook_leave_url`	Wordt aangeroepen wanneer een speler vertrekt

Web URL

Wanneer een speler een game sessie joint, laadt de mssgs client jouw web_url met query parameters:

URL Format

{web_url}?session={session_id}&game_user={game_user_id}

Parameter	Beschrijving
`session`	De game sessie UUID - identificeert bij welke game sessie deze speler hoort
`game_user`	Een unieke 8-karakter ID die is toegewezen aan deze speler voor deze sessie

Voorbeeld

Als jouw web_url https://games.example.com/trivia is, laadt de browser van de speler:

Voorbeeld URL

https://games.example.com/trivia?session=a1b2c3d4-e5f6-7890-abcd-ef1234567890&game_user=de875d3a

Jouw webpagina moet:

session en game_user uitlezen uit de URL query params
Verbinding maken met je eigen backend met deze identifiers
De game UI renderen

Belangrijk

De game_user is een korte, opaque identifier. Het bevat geen persoonlijke informatie. Weergavenamen en gebruikersnamen worden alleen via webhooks naar je backend gestuurd - stel ze nooit bloot aan de client-side game code, tenzij je backend ze aanbiedt.

Webhooks

Je backend ontvangt POST requests met een JSON body van het mssgs platform wanneer spelers interacteren met de game sessie. Deze zijn fire-and-forget - fouten hebben geen invloed op de game sessie.

Webhook JSON body

Request Body

{
  "session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "player1",
  "display_name": "Player One",
  "game_user": "de875d3a",
  "host": true
}

Field	Type	Beschrijving
`session`	string	De game sessie UUID
`username`	string	De mssgs gebruikersnaam van de speler
`display_name`	string	De weergavenaam van de speler (valt terug op gebruikersnaam indien niet ingesteld)
`game_user`	string	De unieke 8-karakter game user ID van de speler (dezelfde ID die de client ontvangt)
`host`	boolean	Alleen aanwezig bij join/leave webhooks wanneer de speler de sessie host is

Join Webhook

Wordt aangeroepen wanneer een speler de sessie joint.

POST {webhook_join_url}

Het host veld is alleen aanwezig wanneer de joinende speler degene is die de sessie heeft aangemaakt. Gebruik dit om de game host te identificeren (bijv. voor het starten van de game, beheren van instellingen).

Leave Webhook

Wordt aangeroepen wanneer een speler de sessie expliciet verlaat.

POST {webhook_leave_url}

Het host veld is alleen aanwezig wanneer de vertrekkende speler de sessie host is. Je wilt mogelijk host migratie afhandelen of de game beëindigen wanneer de host vertrekt.

Verbinding verbroken

Spelers worden niet automatisch verwijderd wanneer ze de verbinding verliezen (bijv. refresh, achtergrond, verbinding verbroken). Ze blijven in de sessie en kunnen opnieuw joinen. Inactieve sessies worden na 1 uur automatisch opgeruimd.

Beveiliging

Gebruik game_user voor speler identiteit

De game_user ID is de enige speler identifier die naar de client-side game wordt gestuurd (via de web URL). Het is:

Uniek per speler per sessie
Een opaque 8-karakter string
Wordt niet hergebruikt tussen sessies

Gebruikersnamen en weergavenamen worden alleen naar je backend gestuurd via webhooks, nooit naar de client-side game. Dit voorkomt dat spelers identiteiten kunnen nabootsen en dat persoonlijke informatie lekt naar de browser.

Valideer session en game_user op je backend

De webpagina van je game stuurt session en game_user naar je backend (bijv. via WebSocket of API calls). Valideer altijd dat:

De session een bekende, actieve sessie is op je backend (ontvangen via een join webhook)
De game_user is geregistreerd via een join webhook voor die sessie
De game_user nog niet is vertrokken (ontvangen via een leave webhook)

Webhook herkomst

Webhooks komen van de mssgs gateway servers. Overweeg de bron te valideren als je webhook endpoints publiek toegankelijk zijn.

Game Lifecycle

Event	Wat er gebeurt
Sessie aangemaakt	Een game kanaal verschijnt in de server
Speler joint	Join webhook wordt verstuurd, aantal spelers wordt bijgewerkt in kanaal
Speler vertrekt	Leave webhook wordt verstuurd, aantal spelers wordt bijgewerkt
Alle spelers vertrekken	Sessie wordt verwijderd, game kanaal wordt verwijderd
1 uur inactiviteit	Sessie wordt automatisch opgeruimd

Architectuur

Jouw backend beheert de game state. Het mssgs platform regelt alleen de sessie lifecycle en speler tracking - alle game logica draait op jouw kant.

Voorbeeld Architectuur

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  mssgs Client   │     │  mssgs Gateway   │     │  Jouw Backend   │
│  (laadt iframe) │     │  (orchestrator)  │     │  (game logica)  │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                         │
         │  Speler joint sessie  │                         │
         │──────────────────────>│                         │
         │                       │  POST webhook_join_url  │
         │                       │────────────────────────>│
         │                       │                         │ Speler opslaan
         │  Laad web_url?session=&game_user=               │
         │<──────────────────────│                         │
         │                       │                         │
         │  Verbind met je backend via session+game_user   │
         │────────────────────────────────────────────────>│
         │                       │                         │ Valideer
         │                       │                         │ game_user
         │  Game data (via je eigen WebSocket/API)         │
         │<────────────────────────────────────────────────│
         │                       │                         │

Best Practices

Vertrouw de client niet

Valideer session en game_user op je backend tegen webhook data.

Verwerk disconnects

Spelers kunnen onverwacht vertrekken. Verwerk de leave webhook altijd op een correcte manier.

Host detectie

Gebruik de host: true webhook parameter om te identificeren wie de game beheert.

Stateless webpagina

Je game pagina moet initialiseren puur vanuit URL params. Vertrouw niet op cookies of local storage voor sessie-identiteit.

Responsive design

Games worden geladen in een webview. Zorg dat je UI werkt op mobiel en desktop.

Vragen?

We helpen je graag verder met je game integratie.

developers@mss.gs