Click here to Skip to main content
11,485,982 members (78,815 online)
Click here to Skip to main content

How To: Initialize a game on Android with XPG

, 26 Jan 2012 CPOL 19.3K 9
Rate this:
Please Sign up or sign in to vote.
This is a continuation of the How To series. This first post is here. This article will cover: Adding the XPG Live API for Android to your project’s build path in Eclipse Adding the XPG Live API for Android reference in Visual Studio Initializing the XPG Live API in code Handling the initialization

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

This article will cover:

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

Prerequisites

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

Copy the XPG.Android_[VERSION].jar and XPG.Android.Doc_[VERSION].jar to your project’s "assets" folder.

In Eclipse, select your project and refresh it

Expand the "assets" folder in your project

Open the context menu on "XPG.Android_[VERSION].jar"

Point to "Build Path" and click "Add to Build Path"

image

You will see XPG.Android_[VERSION].jar under the "Referenced Libraries" node in your project

image

Open the context menu for the XPG.Android_[VERSION].jar from the "Referenced Libraries" node

Point to "Build Path" and click "Configure Build Path…"

image

On the "Libraries" tab, under "XPG.Android_[VERSION].jar, select "Javadoc Location" and click "Edit"

image

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

image

Expand your project and the "assets" folder, then select "XPG.Android.Doc_[VERSION].jar and click "OK"

image

Click "OK" again

image

Now your project is setup to use XPG Live.

Adding the XPG Live API for Android reference in Visual Studio

For simplicity sake, and because the source code is freely available, we’ll use the XPG Demo Source for MonoDroid. We’ve also installed the stable release of the XPG Live API for MonoDroid. This reference dialog may look a bit different than yours because of other installed Visual Studio extensions.

Right click the "References" node in your solution and select the "Add Reference…" option

image

Click the "Browse…" button and navigate to "C:\Program Files (x86)\XPG\APIs" on 64-bit or "C:\Program Files\XPG\APIs" on 32-bit

Select "XPG.Android.dll" and click "Open"

image

Click "Add" then click "Close"

image

Now your project is setup to use XPG Live.

Initializing the XPG Live API in 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.

Java Code

XPGAPI.Instance.initialize("DEMOKEY000000001", AndroidGameActivity.this, new InitializeCompleted());

C# Code

XPGAPI.Instance.Initialize("DEMOKEY000000001", this, InitializeCompleted);

This will initialize your game locally unless you haven’t enabled Android 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 Android is pretty flexible when it comes to event handling. You can handle events on a per call basis with anonymous delegates, 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 Android 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:

Java Code

XPGAPI.Instance.setCallbackOnUiThread(false);

C# Code

XPGAPI.Instance.UseUIThreadEvents = false;

If you choose to handle callbacks 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:

Java Code

/** 
* Handle the API having been initialized.
*/
private class InitializeCompleted extends
        XPGAPICallbackGeneric<XPGInitGameInfo> {
    @Override
    public void gotResponse(XPGAPIResponseGeneric<XPGInitGameInfo> response) {
        if (!response.getFailed()) {
            if (response.getBody() == null) {
                Toast.makeText(AndroidGameActivity.this, response.getMessage(), Toast.LENGTH_LONG);
            }
            else {
                /* Use response.getBody() or XPGAPI.Instance to access the game and user */
            }
        }
        else {
            Toast.makeText(AndroidGameActivity.this, response.getMessage(), Toast.LENGTH_LONG);
        }
    }
}

C# Code

///<span class="code-SummaryComment"><summary>Handle the API having been initialized.</summary>
</span>///<span class="code-SummaryComment"><param name="response">The server response to the initialization.</param>
</span>public void InitializeCompleted(XPGAPIResponse<XPGInitGameInfo> response)
{
    if (!response.Failed)
    {
        if (response.Body == null)
        {
            Toast.MakeText(this, response.Message, ToastLength.Long).Show();
        }
        else
        {
            // Use response.Body or XPGAPI.Instance to access the game and user
        }
    }
    else
    {
        Toast.MakeText(this, response.Message, ToastLength.Long).Show();
    }
}

You’ll notice that not much is going on here. The XPG Live API for Android handles it’s state so that your 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 Code

Java Code

package com.android.game;




import com.xpglive.api.XPGAPI;
import com.xpglive.api.XPGAPICallbackGeneric;
import com.xpglive.api.XPGAPIResponseGeneric;
import com.xpglive.api.XPGInitGameInfo;




import android.app.Activity;
import android.os.Bundle;
import android.widget.Toast;




public class AndroidGameActivity extends Activity {
    /** 
     * Called when the activity is first created.
     */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        XPGAPI.Instance.initialize("DEMOKEY000000001", AndroidGameActivity.this, new InitializeCompleted());
    }




    /** 
     * Handle the API having been initialized.
     */
    private class InitializeCompleted extends
            XPGAPICallbackGeneric<XPGInitGameInfo> {
        @Override
        public void gotResponse(XPGAPIResponseGeneric<XPGInitGameInfo> response) {
            if (!response.getFailed()) {
                if (response.getBody() == null) {
                    Toast.makeText(AndroidGameActivity.this, response.getMessage(), Toast.LENGTH_LONG);
                }
                else {
                    /* Use body or XPGAPI.Instance to access the game and user */
                }
            }
            else {
                Toast.makeText(AndroidGameActivity.this, response.getMessage(), Toast.LENGTH_LONG);
            }
        }
    }
}

C# Code

using System;
using Android.App;
using Android.Content;
using Android.Graphics;
using Android.OS;
using Android.Widget;
using XPG.Demo.MonoDroid;




namespace XPG.Demo.Android
{
    [Activity(Label = "XPG Demo MonoDroid", MainLauncher = true, Icon = "@drawable/Main")]
    public class ActivityMain : Activity
    {
        ///<span class="code-SummaryComment"><summary>Called when the activity is first created.</summary>
</span>        ///<span class="code-SummaryComment"><param name="bundle">The saved instance state.</param>
</span>        protected override void OnCreate(Bundle bundle)
        {
            base.OnCreate(bundle);
            SetContentView(Resource.Layout.main);
            XPGAPI.Instance.Initialize("DEMOKEY000000001", this, InitializeCompleted);
        }




        ///<span class="code-SummaryComment"><summary>Handle the API having been initialized.</summary>
</span>        ///<span class="code-SummaryComment"><param name="response">The server response to the initialization.</param>
</span>        public void InitializeCompleted(XPGAPIResponse<XPGInitGameInfo> response)
        {
            if (!response.Failed)
            {
                if (response.Body == null)
                {
                    Toast.MakeText(this, response.Message, ToastLength.Long).Show();
                }
                else
                {
                    // Use response.Body or XPGAPI.Instance to access the game and user
                }
            }
            else
            {
                Toast.MakeText(this, response.Message, ToastLength.Long).Show();
            }
        }
    }
}

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

XPG Live

United States United States
No Biography provided
Group type: Organisation (No members)



Comments and Discussions

 
-- There are no messages in this forum --
| Advertise | Privacy | Terms of Use | Mobile
Web04 | 2.8.150520.1 | Last Updated 26 Jan 2012
Article Copyright 2012 by XPG Live
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid