PlayerIO

The fastest way to build online games without breaking a sweat.

Publishing Network Canvas

Integrating your game with the PlayerIO Publishing Network offers a multitude of benefits; You get access to a large global audience, their friend relations, a suite of social features to boost engagement and Publishing Network Payments for in-game payments.

The core of this functionality is the Canvas system. Every game site contains an iframe that points to a secure (https) page hosted by you that contains the game. This page must include our PublishingNetwork.js javascript, and potententally validate the user via a given usertoken.

Overview

It's easy and fast to get a canvas page up and running, simply follow the following steps:

  1. Create a PlayerIO Game
  2. Create a secure URL for your game
  3. Include PublishingNetwork.js
  4. Authenticate the user

1. Create a PlayerIO Game

If your game does not already use any PlayerIO features, you'll need to create a PlayerIO game to contain the configuration settings for your game.

  1. Site header » My Games » Create New Game
  2. Enter your game name
  3. Click "Create Game"

2. Create a secure URL for your game

You need to need to provide a https url for your game on your own server, such as 'https://mygame.gamescompany.com/'.

Once you have this URL, configure the Canvas Setup section of your game:

  1. Your Game » Publishing Network » Canvas Setup
  2. Pick a shortcode for your game
    The shortcode is used for the URL to your game. For instance, if you pick 'mygame', your game might be reachable on www.gamesite.com/games/mygame
  3. Enter the Canvas URL for your game
  4. Click Save

If everything goes well, you should now be able to click the "Test Canvas" button to see your game embedded on a gamesite.

3. Include PublishingNetwork.js

In order to support all the features of the PlayerIO Publishing Network, the canvas page needs to include a special PublishingNetwork.js javascript file. This script lets the game frame communicate with the hosting page for features such as showing payment dialogs and resizing the frame when the content size changes.

The script is quite simple to include, simply add the following script tag to your page. The preferred location is directly after the opening <body> tag:

The PublishingNetworkSetup object is how you configure the javascript. The only required configuration is that you include the usertoken from the querystring in the PublishingNetworkSetup object.

In the snippet above, simply ensure that instead of "[UserToken from QueryString]" you output the actual usertoken given in the querystring.

4. Authenticate the user

Whenever a user visits a play page for your game, your Canvas URL will be in an iframe with a UserToken given as a querystring argument. This UserToken is the basis for the user authentication.

For example, if your game has the Canvas URL https://mygame.mycompany.coms/, the iframe would load https://example.com/playeriocanvas/?usertoken=<token>.

Your receiving page must decode and validate the usertoken as described below to get the information about the user.

A UserToken is a Base64URLEncoded JSON object with information about the user, and a signature that can be used to validate the authenticity of a given token. They are encoded in this format:

The JSON object can contain the following values:

Keys and Values
version Contains version and validation algorithm. Currently always "V1_HMACSHA256"
userId The unique game-specific user ID of the user.
gamerName The gamer name of the user playing the game, i.e. the name under which this user wishes to be known in the game.
userAvatar Url to an avatar image of the user playing the game.
apiToken A token that can be used later to make API requests to PlayerIO. Intended for use with the PlayerIO Client Libraries, not manual usage.
expires When this token expires, in unixtime. (Seconds since Jan 1st 1970 in UTC Timezone)

Validation

UserTokens are generated like this (pseudocode):

In order to securely know which user is playing your game, you must decode and validate the given UserToken in your server-side code. The following pseudo-code illustrates how you can do this:

Note that you need the Game Secret from the Canvas settings page in the Control Panel to validate the signature. Since you must keep this secret from users, you must perform this validation server-side and not client-side.

PlayerIO Client Library Authentication

If you have already integrated your game with one of the PlayerIO Client Libraries, you do not need to parse or validate the UserToken yourself. Instead, you pass it into the Authenticate method in your game to connect to PlayerIO and receive an authenticated client.

To call the authenticate method you need the Game ID from the Control Panel, and you need to pass in the name of the Connection that you specified on the Canvas Setup page of the Publishing Setup section for your game. With that information you can call Authenticate like this in .Net/Unity:

Or like this in JavaScript:

Next Steps

Once your game is integrated with Canvas, you should start accepting in-game payments with Publishing Network Payments.