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.
It's easy and fast to get a canvas page up and running, simply follow the following steps:
- Create a PlayerIO Game
- Create a secure URL for your game
- Include PublishingNetwork.js
- 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.
- Site header » My Games » Create New Game
- Enter your game name
- 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:
- Your Game » Publishing Network » Canvas Setup
- 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
- Enter the Canvas URL for your game
- 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
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:
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)|
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:
Once your game is integrated with Canvas, you should start accepting in-game payments with Publishing Network Payments.