How To: Initialize a game on BlackBerry with XPG

This is a continuation of the How To series. The first post is here.

This article will cover:

• Adding the XPG Live API for BlackBerry to your project’s build path in Eclipse
• Initializing the XPG Live API in code
• Handling the initialization response

Prerequisites

• Eclipse with BlackBerry plugin
• XPG Live API for BlackBerry
• An existing project or XPG Demo Source for BlackBerry

Adding the XPG Live API for BlackBerry to your project’s build path in Eclipse

Ensure you have a “lib” folder under your project’s root folder

Copy the XPG.BlackBerry_[VERSION].jar and XPG.BlackBerry.Doc_[VERSION].jar to your project’s “lib” folder.

In Eclipse, select your project and refresh it

Expand the “lib” folder in your project

Open the context menu on “XPG.BlackBerry_[VERSION].jar”

Point to “Build Path” and click “Add to Build Path”

You will see XPG.BlackBerry_[VERSION].jar under the “Referenced Assemblies” node in your project

Open the context menu for the XPG.BlackBerry_[VERSION].jar from the “Referenced Assemblies” node

Point to “Build Path” and click “Configure Build Path…”

On the “Libraries” tab, under “XPG.BlackBerry_[VERSION].jar, select “Javadoc Location” and click “Edit”

Select “Javadoc in Archive” and “Workspace File”, then click “Browse…”

Expand your project and the “lib” folder, then select “XPG.BlackBerry.Doc_[VERSION].jar and click “OK”

Click “OK” again

Select “Order and Export” tab, check the box for “XPG.BlackBerry_[VERSION].jar and click “OK”

Now your project is setup to use XPG Live.

Initializing the XPG Live API in Java code

Game initialization is very simple, but does require that you’re registered a free developer account on XPG Live, create a game and activate your first access key. Since we’re using the demo app we’ve already completed those steps. The first post of this series gives a walk through of the management app and covers games and access keys.

XPGAPI.Instance.initialize("DEMOKEY000000001", null);

This will initialize your game locally unless you haven’t enabled BlackBerry as a platform, you fat fingered the access key, or you forgot to activate the access key for your game. In one of these cases you’ll get back a localized failure response.

Handling the initialization response

The XPG Live API for BlackBerry is pretty flexible when it comes to event handling. You can handle events on a per call basis with anonymous delegates of delegate method references, or you can wire up event handler to the API instance. The API will only invoke one callback per request. If a delegate was provided in the call then it will be invoked, if the delegate passed was null then the API instance event will be raised if there is one.

Additionally, the API will raise events on the UI thread by default. This is done to protect against accidental cross thread access of UI components. The XPG Live API for BlackBerry DOES NOT directly interact with UI components with the exception of social logins which will be discussed in a later post. You can choose to have your delegate raised on a background thread to keep your main thread free for drawing and updates with the following code:

XPGAPI.Instance.setCallbackOnUIThread(false);

If you choose to handle callback on background threads it is your responsibility to manage your cross thread interactions appropriately.

Since this is the first callback you’ll always get, this is a great opportunity to mention that when the initialization call is made is when the server becomes aware of the clients locale. This response, and every response after it, will be sent in the clients locale if at all possible, which means that error messages are not only user friendly but in the users language as well. If you defined game titles and descriptions, etc. for your game in the users language they will also be used here.

Here’s a simple callback example for game initialization:

private class InitializeCompleted extends XPGAPICallbackInitialize {
    public void gotResponse(XPGAPIResponse response,
            XPGInitGameInfo body) {
        if(!response.getFailed().booleanValue()) {
            if (body == null) {
                Dialog.alert(response.getMessage());
            }
            else {
                /* Use body or XPGAPI.Instance to access the game and user */
            }
        }
        else {
            Dialog.alert(response.getMessage());
        }
    }
}

You’ll notice that not much is going on here. The XPG Live API for BlackBerry handles it’s state so that you’re game only needs to be concerned with it’s own state.

During this initialization the background queue will also spin up to process any score postings, achievement awards, or friend requests which might not have made it to the server before the last shut down.

Announcements for your game are also brought down with initialization, so this callback could be useful for toasts or other user notifications. When this callback is raised, the leaderboards will be initializing their first page of the latest scores already, so there isn’t much for you to do other than handle your game logic.

The complete Java Code

package XPG.Demo.BlackBerry;

import com.xpglive.api.XPGAPI;
import com.xpglive.api.XPGAPICallbackInitialize;
import com.xpglive.api.XPGAPIResponse;
import com.xpglive.api.XPGInitGameInfo;

/**
 * A class extending the MainScreen class, which provides default standard
 * behavior for BlackBerry GUI applications.
 */
public final class ScreenMain extends MainScreen {

    /**
     * Creates a new BlackBerry object
     */
    public ScreenMain() {
        XPGAPI.Instance.initialize("DEMOKEY000000001", null);
    }

    /**
     * Handle the API having been initialized.
     */
    private class InitializeCompleted extends XPGAPICallbackInitialize {
        public void gotResponse(XPGAPIResponse response,
                XPGInitGameInfo body) {
            if(!response.getFailed().booleanValue()) {
                if (body == null) {
                    Dialog.alert(response.getMessage());
                }
                else {
                    /* Use body or XPGAPI.Instance to access the game and user */
                }
            }
            else {
                Dialog.alert(response.getMessage());
            }
        }
    }
}