Javascript framework for social games

During my time at Social Games Ventures, I made a JavaScript framework that simplifies and standardizes the communication between a game, a social network and a statistics service. It also adds features such as landing pages and dynamic permission requests.


The framework was built out of several needs:

  • Streamlining the authentication process
  • Gain control over the communication with the Facebook Graph API
  • Add landing pages to Open Graph stories, wall posts and app requests
  • Adapt to using Open Graph API, score API and achievements

In addition to the needs, I saw a potential to structure the framework in a way so that it would become easier to put the game on several social networks without any or much changes in the game code.

The benefits of creating the framework in JavaScript were:

  • Centralizing all communication with Facebook in a way so that both the game and the landing pages could easily get access to the Facebook Graph API.
  • Removing Facebook specific code from the game code. The game code is much more cleaner now, and the SWF is smaller.
  • Centralizing debugging traces. The game now prints traces and error messages to the same console we use for JavaScript debugging.
  • Because of the centralizing and standardizing it no longer matters if the game is made in HTML5/JavaScript, Flash or Unity -they all talk to Facebook and Upsight via the same framework.
  • Everything that has to do with Facebook uses the same code as Facebook has in their documentation. That makes it a lot easier to understand what is going on, and to modify the code. Now we actually have a documentation for all Facebook communication -something we didn’t have when using the AS3 Facebook API.

State of the framework

I’ve been working on the framework for a couple of months and it's still very immature. Things like the structuring of the code could definitely be done a lot better, loading of external modules, packing and minifying of all files. The framework is more a proof of concept that anything else. It works, but still has a lot of potential.

Structure overview


At startup RequireJS loads a main file which is individual to each game. This is where we define which game to start. The idea for the future version of the framework is to have the loading of both the social network API and the statistics service API to load automatically based on certain rules. I haven’t figured out which rules will be the best, but checking the URL might be an idea. So let’s say you try to load the game from, the game will se that you are on Facebook and therefore load the Facebook API.

The game specific code extends the game core, which includes a lot of common game code, such as loading a SWF via swfobject, connection to the social network and statistics service and so on. The core loads the correct game and injects a settings file. In this settings file, you will find settings for the SWF loading, flashvars, and also one settings object per social network which the game is to be on. This includes properties such as permissions to ask for when installing the game, API keys and such.

Some external resources are automatically loaded as a part of the authentication and installation process. For instance language files are loaded automatically because they are used by both the landing pages and the game.

The game itself is either a SWF, a package of JavaScript files or maybe a Unity file.

With a structure like this we are able to automatically load an API for a social network (Facebook, Tencent, Kongregate, the soon to be launched Zynga platform, etc.), and a statistics service such as Upsight, Claritics, Flurry or any other. We can even define different statistics services for each game because it is per-game setting.


Landing pages

We wanted to try to increase the conversion from users to player by using landing pages. The purpose of the landing pages was to add a context to the app requests, wall posts and Open Graph stories.

When you get an app request, it usually only says that “A friend of yours sent you a request in game ABC”. If you click on that you usually get to an authentication page and have to install the game before you get to see what that request was all about. I built a system that first takes you to a landing page which gives you more information on that app request. Should you like what you see and click on the play button, you will be asked to install the game.

To give an example, let’s imagine a RPG game. The landing page for an invitation to join a friend on a quest could be beautifully designed as a scene from a fight between knights and monsters. Your friend has written a message to you, you get some information on the game, you can see which other friends of yours are also playing this game. There might be a link to a video that shows a recording of an in-game fight scene. Everything that can be used for converting users into players can be put on this page.

Click tracking

As a part of the landing pages system, I had to know where the users were coming from. Did they click on an app request or Open Graph story? Facebook provides a lot of information on what the user clicked on.

For instance, when you click on a bookmarked app, the app can pick up if your bookmark is on the top list (always visible), or if you had to click the “more...” link to get to the bookmark, or if you had to go via the list of all the apps you have installed.

For app requests the app can detect if you clicked on a notification (via the globe icon in the top left corner), or via the Growl-like notification which pops up inthe bottom left hand corner or even the reminder area on the right (between the ticker and the ads).

Information like this can be useful. I imagine that we could give a reward to the player for bookmarking our game. It’s valuable to us that the player can always see a link to the game, so why not show that we are grateful for that. If the player had to click the “more...” link we could tip the player that we really appreciate a bookmark and that it could benefit the player to move the bookmark to the top list.

A/B testing

Each landing page type and the links you click on within them are tracked via the A/B testing system. We know which landing page you got and whether you clicked play or not. This way we can see which landing pages has the highest conversion rate, and work towards creating optimal landing pages.

Unified communication with the social network

I wanted the game to contain as little social network specific code as possible, so I constructed a system where you pass an object from the game to the JavaScript framework, and the framework decides what to do based on which social network is currently in use.

The object you pass has a name, and that name gets mapped to a certain call to the social network. To give an example, you have your game on social network A, B and C. To send a message via A you have to use a method called “post”, while on B you use “mail” and for C it is called “tweet”. If all of these methods are basically the same, you could map them all to the keywork “message”. That way you can make the game pass an object called “message”, and the framework would do the rest.

You would most likely still need to send some social network specific values along with the message object, but it would require a lot less code as you have only one method to call and one callback. No more including social network APIs in the game code and multiple event handlers and so on.

Dynamic permission requests

Usually you would be met with a permission dialog when going to an app that you haven’t used before. There, you give all the permissions the app require and you’re good to go. In many cases, especially if your require the permission to post on the behalf of the player or any other deal breaker permissions, you could end up with a lower conversion than if you had asked for fewer permissions.

This framework has incorporated a system for dynamically asking for permissions when needed. This way, we can ask for only a few permissions at install, and when or if the player decides to e.g. post on his wall, we ask for the necessary permission.

Thoughts for the future versions

This alpha version has proved that it is possible to create such a framework, and that it works. There’s still a lot that can be done better. The way the code is structured is one thing, another is how the objects are passed between modules. I’d like to get away from as many switch statements as possible. Less spaghetti, more structure. I’d like to test the framework with another social network, and build the system for automatically detecting of current social network.

Latest articles