How To: Initialize a Game on Windows Phone with XPG

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

This article will cover:

• Adding the XPG Live for Windows Phone reference in Visual Studio
• Initializing the XPG Live API in C# code
• Handling the initialization response

Prerequisites

• Windows Phone SDK 7.1 for Windows Phone
• XPG Live API for Windows Phone
• An existing project or XPG Demo Source for Windows Phone

Adding the XPG Live for Windows Phone Reference in Visual Studio

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

As with most Visual Studio assemblies, just right click the “References” node in your solution and select the “Add Reference…” option. The XPG.WinPhone assembly will be listed under “Extension” if you have the Productivity Tools installed. Double click the assembly to add it to your project as a reference and close the dialog if it doesn’t close itself.

Initializing the XPG Live API in C# 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 walkthrough of the management app and covers games and access keys.

string _gameSecretKey = "DEMOKEY000000001";
XPGAPI.Instance.Initialize(_gameSecretKey, Instance_InitializeCompleted);

This will initialize your game locally unless you haven’t enabled Windows Phone 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 Windows Phone 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 Windows Phone 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.UseUIThreadEvents = 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:

///<summary>Handle the API having been initialized.</summary>
///<param name="response">The server response to the initialization.</param>
public void Instance_InitializeCompleted(XPGAPIResponse response)
{
    if (!response.Failed)
    {
        if (response.Body == null)
        {
            // Show a simple message so we know it returned successful 
            // without a body
            MessageBox.Show(response.Message, 
                "XPG Notification", MessageBoxButton.OK);
        }
    }
    else
    {
        // Show the localized error message
        MessageBox.Show(response.Message, "XPG Notification", 
                        MessageBoxButton.OK);
    }
}

You’ll notice that not much is going on here. The XPG Live API for Windows Phone handles its state so that your game only needs to be concerned with its 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 C# Code

using System.Windows;
using System.Windows.Data;
using Microsoft.Phone.Controls;

namespace XPG.Demo.WinPhone
{
    ///<summary>The primary application page.</summary>
    public partial class PageMain : PhoneApplicationPage
    {
        #region Member Variables

        ///<summary>The Demo game secret key.</summary>
        private string _gameSecretKey = "DEMOKEY000000001";

        #endregion Member Variables

        #region Constructors

        ///<summary>Creates a new instance of .</summary>
        public PageMain()
        {
            InitializeComponent();

            XPGAPI.Instance.Initialize
                (_gameSecretKey, Instance_InitializeCompleted);
        }

        #endregion Constructors

        #region Methods

        #region Instance_InitializeCompleted
        ///<summary>Handle the API having been initialized.</summary>
        ///<param name="response">The server response to the initialization.
        ///</param>
        public void Instance_InitializeCompleted(XPGAPIResponse response)
        {
            if (!response.Failed)
            {
                if (response.Body == null)
                {
                    MessageBox.Show(response.Message, 
                    "XPG Notification", MessageBoxButton.OK);
                }
            }
            else
            {
                MessageBox.Show(response.Message, 
                    "XPG Notification", MessageBoxButton.OK);
            }
        }
        #endregion Instance_InitializeCompleted

        #endregion Methods
    }
}