Connections

To use any of the Player.IO services, your game must first identify itself and the current player by using the Connect method of the API. Connections come from games or even your own webservers or similar.

Typically, whatever is sent from the game client is insecure and can be tampered with by the player. Since this code is less trustworthy than code running on your own webservers or in the serverside code for a multiplayer game, it is possible to have multiple connections with different access rights.

Connections are added and edited in the Player.IO Control Panel.

Editing a connection in the Control Panel

By default, there is only one connection (called "public") with full access rights. Most games will never edit their connections, and simply use the default public connection. However, if security is a priority, you can change the access rights on the public connection or add more connections for specific purposes.

A common use case is to setup the connections such that the game client is only allowed to read data, and only write data from the serverside.

The serverside code for multiplayer games always has full access rights, since it´s running in a trusted environment in the Player.IO server cluster.

The Connect() Method

Each client library (ActionScript3, .NET...) has a different implementation of the Connect() method, but they all look almost the same:

• GameId

  The game id of the game you wish to connect to. This value can be found in the Control Panel

• ConnectionId

  The id of the connection, as given in the settings section of the Control Panel. By default, a connection with id='public' is created on all games.

• UserId

  The id of the user connecting. This can be any string you like. For instance, it might be "fb10239" if you´re building a Facebook app and the user connecting has id 10239

• Auth

  If the connection identified by ConnectionIdentifier only accepts authenticated requests, the auth value generated based on UserId is added here

   

Game database

Each connection can also specify a game database so that you can partition data from different social networks, for example if you want to put your game on both Facebook and Kongregate, you can use a different game database for connections from either location, but still only have one version of the game.

Then, players on Facebook will only see multiplayer rooms from other players on Facebook, while Kongregate users will only see rooms with other Kongregate users.

Of course, you have completely flexibility to decide if and how you wish to partition your players from different sources.

Authenticated Connections

Per default, anybody can connect to any connection with any user if they simply know the gameid and connectionid. Since this is insecure, you can specify that connections require authentication via a secret key.

When a connection requires authentication, all Connect requests must be accompanied by a hashed authentication value, based on the connect arguments and the secret key of the connection. Of course, the secret key should only be known by trusted parties, since those who have it can generate authentication hashes for anybody.

Generating an auth-hash

The following is how to generate a hash value based on a userId and shared secret using C#. If you are using another language like php, python, or ruby on rails, you will need to implement a method that does the same in that language.

Here's how to generate the auth-hash in java:

Here's how to generate the auth-hash in php:

Here's how to generate the auth-hash in python:

Here is the output from the above code, which is useful if you´re building an implementation in another language.

Facebook Game Example

Let´s say you´re building a Facebook game, consisting of a flash client and some web pages and other game logic running on your webserver. In this case, you might set the rights of the public connection to read only and use it for the flash client, and use a custom connection with full rights from your webserver. Of course, you´ll setup the custom connection to require authentication with a secret key, so only your webservers can access the privileged connection.

Single Sign On Example

Consider the case where you want to put your game on a site that already has a bunch of users and its own login and registration. In this case, you´d naturally want the users to be automatically logged into your game when they play it. The easy way to accomplish this, is simply to have the gaming site pass the connect arguments (including the auth-hash, if the connection requires authentication for extra security) to the game, for instance via FlashVars.