Player vs player session

info

Endpoint API definition
Authorization through the X-Api-Key header containing your API key is required.

With the API, you can create a game session that returns embeddable URLs that can be used by your application to connect two remote players.

Parameters

The POST Create an embeddable game session endpoint allows you to specify the configuration that fit the needs of your App.

Parameter		Type	Comments
gameType	required	Enum (TicTacToe, Connect4 , Gomoku, Battleships, Chess)
language	required	Enum (en, fr, es, vi, ru, pt-br, cz, id, de)
inactivityTimeout	optional	Number	Time per turn in seconds. How much time each player has to make a move. Set to 0 if you want infinite time per turn.
timerTimeout	optional	Number	Total time per player in seconds. How much time each player receives to complete a single game. Set to 0 if you want infinite time per player.
boardSize	optional	String	The size of the board, appliable only for Tic-Tac-Toe (3x3, 5x5) and Connect 4 (7x6, 8x7, 8x8, 9x7, 9x9). If no boardSize is specified, or if the value is wrong, it fallbacks to the classic size.
maxGames	optional	Number	Maximum number of games per session. If not specified, the game session has unlimited games. We recommend setting it to odd values (1, 3, 5) to try to have a winner.

info

Keep in mind that the timerTimeout parameter should always be greater than the inactivityTimeout.

Sample payload

{
    "gameType": "TicTacToe",
    "language": "en",
    "inactivityTimeout": 30,
    "timerTimeout": 60
}

Sample response

{
  "uid": "wdnH6gXc1",
  "playUrl": "https://papergames.io/en/r/wdnH6gXc1/embed/play",
  "watchUrl": "https://papergames.io/en/r/wdnH6gXc1/embed"
}

The playUrl field contains an embeddable URL that can be integrated into an iframe for a user to play.
The watchUrl field contains an embeddable URL that can be integrated into an iframe for a user to watch the game as a spectator. The uid field contains the identifier for the game session. It can be combined with Webhooks to update your system with the game score.

tip

To have a better understanding of the flow, head up to the Getting started section where you can test our API with a short and practical example (5 minutes ⏱).

iFrame integration

When you create pvp game session, your receive playUrl as a response. This URL can be embedded in an iframe to connect two players.
On your frontend application, you need to create an iframe and set the src attribute to the playUrl value, with a few extra parameters.

iframe query parameters

Query parameter	Sample value	Required	Description
username	John Doe	yes	This is used as a display name on papergames.
externalUserId	JF_001	no	This field is useful if you listen to webhook events. It will be populated on the payload. If you don't use webhooks, you can skip this parameter.

Exaple of an iframe with the query parameters:

<iframe src="https://papergames.io/en/r/wdnH6gXc1/embed/play?username=John%20Doe&externalUserId=JF_001"></iframe>

Timing considerations

Games like Tic-Tac-Toe have a completion average of 15 seconds. Chess completion average is 10 to 15 minutes. Ensure you set the timing options to a reasonable value for average players to feel comfortable. If you're unsure about the timing values, you can follow the recommendations below.

Game	inactivityTimeout	timerTimeout
Tic Tac Toe	30	120
Connect 4	40	240
Battleship	40	180
Gomoku	40	300
Chess	0	1200

If you don't want to stress out the players with timers, simply set both inactivityTimeout and timerTimeout to 0.

Game session expiration

The game sessions don't expire automatically. Therefore, you can create one and start it five days later. They expire only under the conditions below.

• Player1 joins and leaves (e.g., when the iframe is destroyed from the DOM), without starting a game with Player1
• Player1 and Player2 are matched together. As soon as one of them leaves the game (e.g. when the iframe is destroyed from the DOM)