Skip to main content

Getting started

Welcome to the papergames.io API documentation! This guide will walk you through the steps to integrate the API into your application and start initiating one-on-one game sessions.

Duration: ⏱️ 5 minutes

Creating an API key​

info

Getting an API key is easy and can be done through the developer tools. You need to register with a valid email address or through social Logins.

  1. Visit the developer tools and click on "Create API Key" to generate a new API key.
  2. Fill in the form with your application API key name, for example the environment where you will use the API key (Development, Staging, Production).
  3. Copy the generated API key and store it in a secure place. You will need it to authenticate your requests. Generated API key

Test your API Key​

All your requests to the API must include the X-Api-Key header that includes your API key. The easiest way to quickly test is through the endpoint tester. Take some time to explore the API endpoints.

  1. Click on the Authorize button on the top right corner and paste your API key.
    Authorize button
  2. Click on the POST /api/v2/game-session/player-vs-player to create a player vs player game session.
  3. Go ahead and click on the Try it out button, have a look at the JSON payload that will be sent.
  4. Click on the Execute button to send the request.
  5. The endpoint returns two URLs that can be embedded in your application to connect two players.
{
  "uid": "{uid}",
  "playUrl": "https://papergames.io/en/r/{uid}/embed/play",
  "watchUrl": "https://papergames.io/en/r/{uid}/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.

Embedding URLs​

Once you know how to make API requests, you can proceed with a quick integration test (~5 minutes).

Initiate a game session for Player 1​

  1. Call the API endpoint Create a player vs player game session on the endpoint tester.
  2. Open our Codepen playground. You'll see a form and iframe placeholder.
  3. Copy the playUrl field provided by the API response (step 1) and paste its value on the Play url form field.
  4. Fill in the Username field with John Doe, or any dummy username.
  5. Click on the Set iframe URL. The iframe initiates a game session on papergames.io and prompts the user with a Waiting message.

At this point, the first player is joined to a game session and will wait for another player to join.

Join the game session with Player 2​

  1. Open a new private navigation tab on your browser.
  2. Repeat the steps 2 to 5 of the Initiate a game session for Player 1 section.
  3. When you click on the Set iframe URL, player 2 joins the session, and the players can play together.

Integration overview​

Integration overview

Conclusion​

Congratulations! You have successfully finished this quick introduction and now have a basic understanding of how to implement our games on your platform.
If you have any questions or encounter issues, feel free to contact us. Happy gaming!