Flash Library Integration

From J2Play

Introduction

Calling J2Play APIs requires a connection to a the J2Play servers. The following instructions walk you through the complete process, from connecting to the J2Play platform to successfully calling its APIs.

Preparation

First you need to copy some necessary files over to the folder where your .swf is generated. To do so:

Find the J2Play library that matches your Flash and ActionScript version. We provide three different versions of J2Play library in our flash-toolkit package
- AS3 -- for Flash9 with ActionScript 3
- AS2 -- for Flash7, Flash8 and Flash9 with ActionScript 2
- Flash6 -- for Flash6 with ActionScript 2

Copy following files from the directory j2play-flash-toolkit/[version]/swf/ to your game's output directory (this is found in the publish settings for the .swf file your game.fla file produces):

game.properties
j2play.properties
j2playlib.swf

Configuration

Change Settings in game.properties

Each game is identified with a unique Game_ID. For local testing you need to provide login information to the platform. The following steps explain how to obtain a Game_ID and how to setup your local testing environment.

Open the copied game.properties file in a text editor (open from your game's output directory)
Set up the debug information for launching test movie in your local Flash IDE.

The first field value you need to set in the game.properties file is game_id. You can obtain this by going to the J2Play Game Management System. Copy the 5 digit number under the "ID" column for your game and replace "your_game_id" with this value. For example, replace this:

DEBUG.GAME_ID=your_game_id

with this:

DEBUG.GAME_ID= 80503

Add J2Play Developer App

Accessing the J2Play social network developer application varies with each social network. See Perform any social site specific setup for further instructions.

Setup Game for Local Testing

Notice: The following settings are only for local testing from the Flash IDE. When the game is launched from J2Play community on web, these settings will be ignored.

Copy and paste the information a from the J2Play social network developer application added above as outlined bellow:

DEBUG.NETWORK_ID= networkid
DEBUG.SCREENNAME= screenname
DEBUG.USER_ID= userid

Example:

DEBUG.NETWORK_ID= facebook
DEBUG.SCREENNAME= joe
DEBUG.USER_ID= 11111111111

Save the properties file and close it

Include the J2Play Flash interface to your game

Open your game .fla file
In the Flash publish settings, add the Flash interface directory into your game class path (Publish Settings -> Flash -> ActionScript Settings). On Windows use ..\j2play-flash-toolkit\[flash version]\interface (or the appropriate relative path); on Unix use ../j2play-flash-toolkit/[flash version]/interface (or the appropriate relative path).

Action Script

Insert a keyframe (empty, except for the background layer graphics) at the very beginning of your Flash movie for all layers.
Insert a extra layer to your Flash game named j2playlib. This layer should be the same length (in frames) as your longest layer.

NOTE: if you are using Scenes make sure this layer is added to the same Scene that the API is to be called from

Add the following code to the j2playlib layer in frame 1:

Actionscript 2

import ca.j2x.flash.J2PlayLoader;
import ca.j2x.flash.IController;
import flash.external.ExternalInterface;

stop();

if (!ExternalInterface.addCallback("unload", this, j2play_unload))
{
	trace("*****WARNING*****\nCannot build the external callback function!\n");
}

var loader= new J2PlayLoader;
loader.load(this, loadCallback);

function loadCallback(success : Boolean)
{
	if (success)
	{
		trace("J2Play Library initialized successfully!");
		// play the actual game movie
		play();
	}
}

function j2play_unload()
{
	var j2play:IController = _global.controller;
	if (j2play && j2play.isConnected())
	{
		j2play.destroy();
	}
}

Actionscript 3

import ca.j2x.flash.J2PlayLoader;
import ca.j2x.flash.IController;
import ca.j2x.flash.lang.Global;
import flash.external.ExternalInterface;

stop();

var loader= new J2PlayLoader;

if (!ExternalInterface.addCallback("unload", j2play_unload))
{
	trace("*****WARNING*****\nCannot build the external callback function!\n");
}


loader.load(this, onGameLoad);

function onGameLoad(success : Boolean)
{
	if (success)
	{
		trace("J2Play Library initialized successfully!");
		// play the actual game movie
		play();
	}
}

function j2play_unload()
{
	var j2play:IController = Global.vars.controller;
	if (j2play && j2play.isConnected())
	{
		j2play.destroy();
	}
}

Document Class

If your application uses a document class (under Publish Settings when using ActionScript 3.0), you will need to move the initialization code in your document class's constructor to a new function named j2play_continue(). Replace the call to "play()" in the above code with a call to "j2play_continue()".

Result

Your modified game layer and frame layout will now look like:

a-----------------------------------    j2playlib layer
o#############################       Your old game layers      
o###################################    
  ....                  ...
o#####                   
o###################################    Your old game layers

a: j2playlib layer, keyframe 1, contains aforementioned ActionScript code
-: empty frame added
o: empty keyframe added
#: old frames contains your original game

Test and Finish

Publish your Flash game and test it. (From the menu -> Control -> Test Movie).
Make sure you got the "J2Play Library initialized successfully!" message in the Output window of the Flash IDE.

You should now see your Flash game running as it normally would. However, the J2Play Flash Toolkit is integrated and its features are now available to players.

Links

Back to Flash Checklist