Game Launch API

Overview

When a player wants to play your game from a casino operator, Groove sends a game launch request to your platform. Your system must process this request, create a game session, and return a URL where the player will be redirected to play your game.

Start Game Process Flow

The game launch process follows these steps:

sequenceDiagram participant Player participant Casino participant Groove participant YourAPI as Your Game Provider API participant YourGame as Your Game Server Player->>Casino: Select game to play Casino->>Groove: Request game launch Groove->>YourAPI: Forward launch request with player data YourAPI->>YourAPI: Create game session YourAPI-->>Groove: Return game URL Groove-->>Casino: Return redirect URL Casino->>Player: Redirect to game Player->>YourGame: Start playing

Process Steps:

  1. Player selects your game in the casino lobby
  2. Casino sends game launch request to Groove
  3. Groove forwards the request to your Game Launch API endpoint
  4. Your system creates a session and returns the game URL
  5. Player is redirected to your game server

Start Game Request

Groove will send a game launch request to your platform with player and session information. Your system must process this request and return a URL where the player can access the game.

Request Details (From Groove to Your Platform)

  • Endpoint: https://{your_domain}/game/ (or your specified endpoint)
  • Method: GET
  • Content-Type: URL encoded parameters
Warning

All parameters sent by Groove will be URL encoded. Your system must decode them properly.

Request Parameters

Required Parameters

Parameter Data Type Description Example
accountid String(60) [0-9a-zA-Z] Account ID 5179068
country String Country code (ISO 3166-1 alpha-2) IL, UK, US
historyUrl String(50) URL for viewing player’s gaming history (regulatory requirement) http://casino.com/history
homeurl String(50) Page URL that the player is redirected to after exiting the game
Note: If empty, the home button should not be displayed in your game (prevents iframe-in-iframe issues)		 http://www.somecasino.com
is_test_account Boolean Indicates if the player is a test player (excluded from reports) false (regular), true (test)
license String Country that has gaming jurisdiction Curacao, Malta, UK
nogscurrency String Currency code EUR, USD, GBP
nogsgameid String Groove game ID
Note: Can contain letters and special characters		 80102, game_123, slot-abc
nogslang String Language code en_US
nogsmode String Game mode demo, real
nogsoperatorid String Groove ID for the casino 11
sessionid String(64) Session ID ${nogsoperatorid}_99d71938-d598c2es

Optional Parameters

Parameter Data Type Description Example
device_type String Device currently used by the player desktop, mobile
exitUrl String Exit URL http://myhomepage.com
rc_url String Reality check URL https://realitycheckapp.groovegaming.com
realityCheckElapsed Integer Reality Check Elapsed time in minutes 10
realityCheckInterval Integer Reality Check Interval in minutes 15
Info

**Note**: Some games are not available on mobile devices. Always specify the `device_type` parameter when known.

Request Example (What You’ll Receive)

GET /game/?accountid=5179068&country=UK&historyUrl=http%3A%2F%2Fcasino.com%2Fhistory&homeurl=http%3A%2F%2Fwww.somecasino.com&is_test_account=false&license=UK&nogscurrency=EUR&nogsgameid=80102&nogslang=en_US&nogsmode=real&nogsoperatorid=11&sessionid=11_99d71938-d598c2es HTTP/1.1
Host: {your_domain}

Processing the Request (Your Implementation)

Your platform must:

  1. Process the incoming parameters from Groove
  2. Create a game session in your system
  3. Store the session information for use in transaction callbacks
  4. Return a redirect to your game URL (HTTP 302)

**Critical for Transactions**: When making transaction callbacks to Groove, you must use the latest game session for the combination of: - `nogsoperatorid` (operator ID) - `accountid` (player account ID) - `nogscurrency` (currency) This ensures Groove can properly identify and process the transaction.

Response (What You Must Return)

Success Response

  • Status Code: 302 Found
  • Behavior: Your system must redirect to the actual game URL where the player can start playing
  • Location Header: Must contain the full URL to your game

Error Response

If you cannot launch the game, return an error response:

{
    "errMsg": "general_error"
}

Error Handling

Common error scenarios:

Error Description Solution
general_error Generic error occurred Check all required parameters are present and valid
Missing parameters Required parameter not provided Ensure all required parameters are included
Invalid game ID Game ID doesn’t exist Verify the nogsgameid is correct
Invalid session Session has expired or is invalid Generate a new session

Reality Check Feature

For jurisdictions requiring reality check functionality:

  1. Include realityCheckInterval - the interval in minutes for reality checks
  2. Include realityCheckElapsed - time already elapsed in the current session
  3. Provide rc_url - URL for the reality check application

The game will automatically prompt players at the specified intervals.

Implementation Best Practices

  1. Validate all incoming parameters from Groove before processing
  2. Store session information securely for later transaction validation
  3. Implement proper error handling for invalid or expired sessions
  4. Support both demo and real modes in your game
  5. Handle device detection to serve appropriate game versions
  6. Maintain session mapping between Groove session IDs and your internal sessions
  7. Use HTTPS for all endpoints
  8. Handle empty homeurl - If homeurl is empty, hide the home button in your game UI to prevent iframe-in-iframe issues

Next Steps

After successfully launching a game, your game will need to communicate with Groove through the Transaction API for:

  • Validating player sessions (GetAccount)
  • Retrieving player balances (GetBalance)
  • Processing bets (Wager)
  • Reporting results (Result)

Continue to Transaction APIs →