John Schumacher

Background

I received an email on 11-Nov-2012 stating that OpenFeint will be discontinued in about a month.  That’s not a lot of time to research alternatives, code, test, and publish an update to existing apps that utilize that service.  I wish the announcement came a bit sooner.

Since I am using CoronaSDK, OpenFeint was easy to implement.  Another solution will require a bit more work, since there are no other integrated libraries for Android devices to handle leaderboards and achievements.  Game Minion seems to be a very nice alternative, but at this time, it is lacking a bit in documentation and sample apps, so working through implementation requires a lot of testing.

In this article, I am going to document my attempt to integrate Game Minion into my existing app, Spell Them Out, using the Facebook login feature.  Further articles will outline specific features I am implementing.

This demo will log into Facebook to grab the appropriate info needed to pass to Game Minion.  Each step will display some text on your device.

First Steps

A few things before you start coding… In order to test this…

• You will need to register a Facebook app.
• You will need to implement Facebook single sign-on.
• You will need to sign up with Game Minion, add an app and obtain the appropriate access keys.
• You will need to download the Game Minion library.

Step 1 – Setup

local gm = require "gameminion"
local json = require("json")
local facebook = require "facebook"

local FACEBOOK_APPID = "XXXXXXXXXXXXXXXXX"   -- your app's fb id
local GM_ACCESSKEY = "XXXXXXXXXXXXXXXXXXX"   -- your app's Game Minion Access Key
local GM_SECRETKEY = "XXXXXXXXXXXXXXXXXXX"   -- your app's Game Minion Secret Key
local returnToken, returnID -- stores needed facebook info

local GMLoginListener  -- Game Minion Listener
local fbListener       -- Facebook Listener
local StartDemo
local EndDemo

Basic stuff, declare the required libraries, variables, and functions.  You will need to enter your app’s info where indicated above.

Step 2 – Start  function

function StartDemo()
    Runtime:addEventListener( "LoggedIn", GMLoginListener )
    Runtime:addEventListener( "LoginError", GMLoginListener )

    gm = gm.init(GM_ACCESSKEY, GM_SECRETKEY)
    facebook.login(FACEBOOK_APPID, fbListener, {"publish_stream", "email"})
end

StartDemo will be called to kick off all of this.  In that function, start the event listeners needed for Game Minion, and then call gm.init, passing the Access Key and Secret Key provided by Game Minion when you added your app on their portal.

At this point, log into facebook, using your app’s ID, and identify the listener to receive facebook notification.  Notice the “email” permission?  That is required in order to pass info to Game Minion later.  Be sure to add this permission to your app on the Facebook portal as well.

Step 3 – Create the Facebook Listener

function fbListener(event)
    local function onComplete(event)
        if event.action == "clicked" then
            if event.index == 2 then
                facebook.login(FACEBOOK_APPID, fbListener, {"publish_stream", "email"})
            end
        end
        return true
    end

    local alert

    if event.type == "session" then
        if event.phase == "login" then
            display.newText("1. Facebook Login Successful", 0, 0, native.systemFont, 12)
            returnToken = event.token
            facebook.request( "me" )
        elseif event.phase == "loginFailed" or event.phase == "loginCancelled" then
            display.newText("1. Facebook Login Failed", 0, 0, native.systemFont, 12)
            alert = native.showAlert("Facebook Login Error", 
               event.response, { "Cancel", "Try Again" }, onComplete)
        end
    elseif event.type == "request" then
        if event.isError then
            display.newText("2. Facebook Request Failed", 0, 20, native.systemFont, 12)
        else
            display.newText("2. Facebook Request Successful", 0, 20, native.systemFont, 12)
            local response = json.decode( event.response )
            gm:loginFacebook(response["id"], returnToken)
        end
    end
end

The facebook login call will return an event type of “session”, so we check to see if login was successful or if there was a failure.  Failure will pop up a dialog box and ask the user to try again.

If successful, you need to store the event.token that is returned at this point (line 16).  We will need this later.  The token is only returned in the login phase, so we have to store it for now.

Now, you need to get the user’s Facebook ID, so we call facebook.request() with the “me” parameter (line 17).  This will return a JSON string, and once we receive an event type of “request”, we can decode the JSON string returned in event.response.  Once the string has been decoded, the user’s ID is available for use.  I decode the JSON string to a variable named response, and the ID field needed is now located in response["id"].

We now have all the info needed to log into Game Minion (user’s ID and the access token).  Call the loginFacebook() function with these parameters.  Game Minion’s event listener will be triggered when the login procedure is complete.

Step 4 – Game Minion Listener events

function GMLoginListener(event)
    if (event.errorMsg ~= nil) then
        display.newText("3. Game Minion Login Filed", 0, 40, native.systemFont, 12)
        local alert = native.showAlert("Game Minion Login Error", event.response, { "Cancel"})
    else
        display.newText("3. Game Minion Login Successful", 0, 40, native.systemFont, 12)
        local alert = native.showAlert("Login Success!", "Logged into Game Minion", { "OK" })
    end

    EndProg()       -- demo complete, clean up
    return true
end

If everything works as planned, you will have successfully logged into Game Minion, and there will be no errors. In the event there is a problem, event.errorMsg will have some meaningful info, which you can then display or parse to determine what happened.  My GM Listener function above is very generic, but once you get a successful login, do what you need to do in your app.  I am just displaying a message and exiting.

Result

The image on the left is a shot of my Android phone with a successful login.  The step step will be the addition of leaderboards and trophies.  I am not sure what I will handle next, but I will post another article detailing whatever I decided to cover.

Let me know what you think of this article, and how you are doing with your Game Minion integration.  Remember, I am learning as I go, so some things may change.

Want to download a copy of the code?