Integration

From FreePokerAlliance wiki

The article contains extended documentation about the Free Poker Alliance integration concept.

Contents 1 Introduction 2 Definitions 3 Methodology 4 The Cookie 5 Workflow 6 Conclusion

Introduction

So you have your website running, probably with lots of users registered, and in partnership with us you can provide them a great game experience customized with your branding, right from your website. There are a few terms to define, before we go into details.

Definitions

YOURSITE: This is your website
YOURUSER: The user registered on your website
FPA: Free Poker Alliance
FPAUSER: User registered at Free Poker Alliance
SUBPAGE: The HTML page that shows the game launcher, high score, prizes, etc. This is embedded usually via iframe into YOURSITE.
POKERDOMAIN: A second level domain to be registered under your domain, like poker.yoursite.com. It is pointed to our server's IP address (195.70.38.248).
FPA_SECRET: Second level domain cookie set at YOURSITE upon login

Methodology

We've worked with many partners, and found that the easiest way to integrate our SUBPAGE is via iframe. Usually we host the webpage, which is written in PHP and can be localized easily to your language. Though the SUBPAGE can be loaded dynamically via ajax or other ways, we're describing here the iframe way.
So, there are your users, and our huge userbase, how do we connect them? We have an easy way to do that, all you have to do is to expose your currently logged in user's details to the SUBPAGE, which then takes care all the necessary steps to link YOURUSER to an auto-registered FPAUSER. Our experience shows that the most effective (and secure) way to do this is by using a second level domain cookie. This is a type of cookie that is set on your domain (like yourdomain.com) so that it is visible to POKERDOMAIN (like poker.yourdomain.com). All the login and registration procedures remain on YOURSITE.

The Cookie

We use a predefined name for the cookie (called "FPA_SECRET"). All you have to do is, to add a few lines of code to your login handler at YOURSITE, which -upon successful login- fills the cookie with the necessary details so that SUBPAGE can link your user into our system. The following details are needed for this:

• Unique identifier for YOURUSER (can be a numeric ID or any string, hashing it with a hashing algorythm (ex: md5 or sha1) is strongly recommended)
• Full name of YOURUSER (First name + Last name)

Not needed but highly suggested:

• Avatar image URL of YOURUSER (we prefer 100x100 px square images, we can auto-crop-resize a larger picture also)
• User profile URL of YOURUSER

Here's a sample user data:

$userdata = array(
	'userid' => sha1('5717274921'),
	'fullname' => 'Example User',
	'avatar_url' => 'http://yoursite.com/avatars/5717274921.jpg',
	'profile_url' => 'http://yoursite.com/users/5717274921'
);

We prefer the JSON format for transport. After encoding it to JSON it looks like this:

{"userid":"c92a7c989af9cf157d8f172d1c29baa67df36d9e","fullname":"Example User","avatar_url":"http:\/\/yoursite.com\/avatars\/5717274921.jpg","profile_url":"http:\/\/yoursite.com\/users\/5717274921"}

This is the raw data, it wouldn't be wise to store it in plaintext, so we use RSA to encrypt it. We have written a small tool, where you can generate an RSA keypair, you can use it at the following link.
It is important that you save the private key, and send the public key to our technical staff.

Last but not least, as the encrypted data is binary, and the Cookie isn't, we simply base64+hex encode it. (hex after base64)
At SUBPAGE, if we see this cookie, we try to hex+base64 decode and decrypt it with the public key. If it's valid, we commence the finishing phase SUBPAGE links YOURUSER with FPAUSER.

We have prepared an example in PHP for how to set the Cookie.

Workflow

Usually we work under the same following principles:

• 1) We got our technical team connected with your technical team
  
• 2) You modify your DNS to point POKERDOMAIN to our server (195.70.38.248)
• 3) You implement the FPA_SECRET cookie
• 4) You generate a keypair at the api.freepokeralliance.com/keygen site, store the private key and send us the public key in email.
• 5) You create an iframe container at YOURSITE for the SUBPAGE, and show it to our technical team. The width/height of the container is important, so we can design the SUBPAGE.
• 6) Designer at FPA designs the SUBPAGE, based on the iframe container dimensions and the style of YOURSITE.
• 7) SUBPAGE gets configurated at FPA
• 8) Poker game is being built and deployed with your branding
• 9) Testing
• 10) Localization (if the default language of YOURSITE is other than english)

Conclusion

There are surely many ways to integrate to our system. This is just a way we found to be proven as the most effective and not to mention: it requires the least work on your side.
If you have any questions or requests, please contact our technical staff.