Skip to content
The Facebook Instant Games Wrapper for Web and Facebook Instant Game Developers
Branch: master
Clone or download
Latest commit c9e7b34 Mar 7, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build
lib
src
license.txt
readme.md

readme.md

IGX - The Facebook Instant Games Wrapper for Web and Facebook Instant Game Developers

What is IGX?

IGX stands for Instant Games Extension, it is basically a replacement object for the Facebook Instant Games FBInstant object which enables developers to:

  • Deploy games created that use the Facebook Instant Games API to the web and beyond with little to no code changes
  • Build instant game features into existing games before deploying to the Instant Games platform, saving valuable time and money
  • Bolster the existing Instant Games platform with new features via FBInstant.ext, such as real time user to user communication

Why IGX?

IGX was created to enable developers to maximise their development time and money. It's difficult and time consuming to port games to Instant Games taking into consideration platform features, but its also more difficult to port games from Instant Games to web because so many features are lost without considerable back-end work to replace them. IGX attempts to replace some features that the IG platform provides to enable the developer to retain as much functionality as possible.

What features are available?

The following features are available:

What other features are available?

The layer also includes additional functionality that is available outside of the Facebook Instants API, these features include:

  • Login status
  • User registration
  • Account conversion
  • Password management
  • Profile query and modification
  • Add / remove / find friends
  • Real time user to user messaging
  • User chat
  • Referral system
  • Sharing on Twitter and other networks

What features will be coming?

  • Contexts
  • Portal specific services

How to get started

Instead of linking to the Facebook Instants JS file, add igx_min.js and xtralife-3.2.3.min.js to your index page. Note that the back-end used by IGX to provide server side features is called Xtralife (http://xtralife.cloud/), you will need to create a free account and add a game to obtain an API key and secret to use the API.

Once you have an account and have added a game to the system you will be given an API key and secret which you can use to access back-end features.

To set this up in code use:

FBInstant.options.apiKey = "Your games Xtralife key";
FBInstant.options.apiSecret = "Your games Xtralife secret";
FBInstant.options.devMode = "sandbox";
FBInstant.createDefaultServices("xtralife");	// Use Xtralife back-end by default

The IGX SDK is designed so that different parts of the back-end can be replaced, so if you are not happy with a specific API then you can replace it.

The IGX SDK consists of the following files:

  • fbinstantx.js - Contains the replacement FBInstant data and functions
  • fbinstantx_ext.js - Contains extra features that are not found in the Facebook Instant Games API
  • lib_adsservice.js - Ads services interface
  • lib_analyticsservice.js - Analytics services interface
  • lib_chatservice.js - Chat services interface
  • lib_gameservice.js - Game service interface
  • lib_leaderboardservice.js - Leaderboards service interface
  • lib_messagingservice.js - User to user messaging service interface
  • lib_paymentsservice.js - Payment services interface
  • lib_referralservice.js - User referral services interface
  • lib_shareservice.js - Sharing services interface
  • lib_socials - Wrappers for various social API's, Facebook is currently the only one implemented (provides login etc)
  • lib_storageservice.js - Server side storage services interface
  • lib_userservice.js - User services interface
  • lib_utils.js - General utility code
Vendor specific files:
  • lib_adinplay.js - AdInPlay implementation of ads service
  • lib_crazygames.js - CrazyGames implementation of ads service
  • lib_gamedistribution.js - Game Distribution implementation of ads service
  • lib_generic.js - Generic service
  • lib_googleanalytics.js - Google Analytics implementation of analytics service
  • lib_kongregate.js - Kongregate implementation of game services
  • lib_paypal.js - PayPal implementation of payments service using PayPal Checkout
  • lib_xtralife.js - Xtralife implementation of game services

Extensions

A lot of extra functionality has been added to the IGX SDK which is not available in the FBInstant API. These are provided via the FBInstant.ext object. For example, to log in the user via Facebook you would call FBInstant.ext.loginWithFacebookAccessTokenAsync().

Modules and Vendors

IGX uses a system of modules that can work together or independently to provide various features. For each module you would like to use you need to instantiate it using the following format:

new ModuleName("vendor_name");

Where module name is the name of the module you would like to create, for example GameService would create the game service moduke. vendor_name is the name of the vendor that you would like to provide the implementation of the module, for example xtralife. An example set up may look like this:

new GameService("xtralife");
new StorageService("xtralife");
new UserService("xtralife");
new LeaderboardsService("xtralife");
new MessagingService("xtralife");
new ReferralService("xtralife");
new ShareService("generic");

new AnalyticsService("google");
new AdsService("crazygames");
new PaymentsService("paypal");

This looks a bit long winded so a utility function is provided to add the first 7 modules allowing the above 7 lines of code to be replaced with:

FBInstant.createDefaultServices("xtralife");

This sets up xtralife as the default back-end for all game related services.

Logging the user in

The user is by default logged in anonymously. This creates an account for them with Xtralife which allows their game data to be stored and retrieved. It also allows them to submit leaderboard scores and retrieve leaderboards. You can disable anonymous login by setting FBInstant.options.usersOptions.allowAnonymous to false. Lets take a look at an example that shows how to log the user in via Facebook:

	if (FBInstant.ext !== undefined)
	{
		LibSocial.Facebook.Login(function(response) {
			FBInstant.ext.loginWithFacebookAccessTokenAsync(response.authResponse.accessToken).then(function(error, gamer) {
				// User is now logged in with Facebook and Xtralife
			});
		});
	}

Note that if the user is already logged in anonymously then you can log in via the Facebook SDK and convert the account from anonymous using:

	if (FBInstant.ext !== undefined)
	{
		FBInstant.ext.convertAccountAsync("facebook", response.authResponse.userID, response.authResponse.accessToken, function(error) {
			// Account was converted
		});
	}

You can read more about user management on the User Authentication and Management wiki page.

Entry Point Data

Entry point data is passed via the URL in the data parameter. The data object passed must be url encoded. Note that when you make a call to shareAsync the data object passed in options.data will be sent with the URL. When a user clicks the link the data will be available via getEntryPointData().

User Management

IGX supports user login and mangagement. The following user providers are currently supported:

  • Xtralife
  • Kongregate

Server Side Data Persistence

IGX supports server side data persistence for sharing data across devices. The following storage providers are currently supported:

  • Xtralife

See the Data Persistence wiki page for more info.

Sharing

IGX supports social sharing. The following social sharing providers are currently supported:

  • Facebook
  • Twitter
  • Kongregate

See the Leaderboards wiki page for more info.

Leaderboards

IGX supports leaderboards. The following leaderboard providers are currently supported:

  • Xtralife

See the Social Sharing wiki page for more info.

Analytics

IGX supports collection of user data for game analytics purposes. The following analytics providers are currently supported:

  • Google Analytics
  • Kongregate

See the Analytics wiki page for more info.

Ads Services and Portals

Over time many portals and ad providers will be added to the IGX SDK. At the time of writing the following ad providers / portals have been added:

  • AdInPlay
  • Crazy Games
  • Game Distribution

See the Monetisation wiki page for more info.

Payment Services

Over time a variety of payment processing services will be added to the IGX SDK. At the time of writing the following payment services have been added:

  • Kongregate
  • PayPal Checkout

See the Monetisation wiki page for more info.

Chat Services

Over time a variety of user chat services will be added to the IGX SDK. At the time of writing the following chat services have been added:

  • Kongregate

User to User Game Messaging Services

IGX supports user to user game messaging. The following providers are currently supported:

  • Xtralife

See the User to User Messaging wiki page for more info.

Important Notices!

  • Before releasing your game ensure that you switch from sandbox to production, users are not shared between the two.
  • This SDK is very heavily under development so things can change quite quickly.

Integrating Guides

Check the Integration Guides wiki page for more info

Issues

When switching from a sandbox to production environment, be aware that data from the sandbox session will still be stored in the browser, so when you try to log into the production environment old stale data from ths sandbox environment will be used. If this occurs you will see errors relating to 401 (Unauthorized) and possibly also No 'Access-Control-Allow-Origin' header is present on the requested resource. To fix this, clear the storage for your domain. For example, to do this in Chrome go to developer tools->Application->Clear storage then click the Clear Site Data button.

Future Integrations

Below is a list of planned integrations with the IGX SDK:

  • Game Analytics
  • Miniclip
  • Newgrounds.io
  • Poki
  • Y8

Other possible integrations with the IGX SDK:

  • Armor Games
  • Spil Games
  • Kizi

Examples of games using IGX

Wiki

Read more about IGX on the IGX wiki.

Community

Join the IGX SDK community on Facebook.


Help keep this project alive by donating paypal

You can’t perform that action at this time.