Facebook Gameroom Integration Guide

For the Javascript version of cocos2d-x v3.x - (all other versions)

Precondition

Please follow the guide from Facebook to setup a Facebook application with Gameroom configurations.

Integration with Cocos Project

With SDKBOX Installer, you can install Gameroom Plugin in Windows easily. Please access SDKBOX official website for more information to get SDKBOX Installer.
After getting SDKBOX Installer, you can import Gameroom Plugin with it:

sdkbox import gameroom

Or, if the gameroom plugin is in local, you can also import it like this:

sdkbox import -b c:\the_path_to_gameroom_plugin\sdkbox-gameroom_v0.01

Manual Integration

If you want to install Gameroom Plugin manually, you would modify more configurations step by step. It's a little perplex, we don't recommend you to do this.

Find the Visual Studio Solution file(.sln) and open it. As for JS project, you can find it in "./framework/runtime_src/proj.win32". We name the "proj.win32" project-dir for depict conveniently.
Unzip the Gameromm Plugin package to get a dir including the plugin files. It's called plugin-dir.
Copy header files. For JS project, copy win32/include/*.h in plugin-dir to include/plugingameroom in your project-dir.
Copy library files win32/libs/*.lib in plugin-dir to libs in your project-dir.
Deploy Facebook Gameroom SDK files.

a. Copy header files sdk/fbg/*.h in plugin-dir to include/fbg in your project-dir.

b. Copy library files sdk/libs/*.lib in plugin-dir to libs in your project-dir.
For JS project, you should add some js-binding source. Copy them in jsbindings in plugin-dir to the dir /Classes, which is located in the upper of your project-dir.
Modify the configuration of Visual Studio. Follow the steps as below:

a. Add an include directory for the compiler, click: project(on top bar) -> properties -> Configuration Properties -> VC++ Directories -> Include Directories (click and edit, add a new entry).

And then add $(solutiondir)include.

b. Add a library directory for *.lib files, click: project(on top bar) -> properties -> Configuration Properties -> VC++ Directories -> Library Directories (click and edit, add a new entry).

And then add $(solutiondir)libs.

c. Link the *.lib files, click: project(on top bar) -> properties -> Configuration Properties -> Linker -> Input -> Additional Dependencies (click and edit, add a new entry).

And then add GameroomPlugin32.lib and LibFBGPlatform32.lib.

For debug version, Please add GameroomPlugin32.debug.lib.
Patch the AppDelegate.cpp. Open the AppDelegate.cpp in project-dir/Classes.
The following steps can also be fulfilled with patch tool. The file AppDelegate.js3.15.patch in plugin-dir is for JS project.

patch AppDelegate.cpp ./plugin-dir/path/AppDelegate.js3.15.patch

Before USING_NS_CC, add the sdkbox header files:

#ifdef SDKBOX_ENABLED
#include "PluginGameroomJS.hpp"
#include "PluginGameroomJSHelper.h"
#endif

In the ctor and dtor of AppDelegate. Add redirect the STDOUT to a file since Facebook SDK don't offer any logging APIs.

AppDelegate::AppDelegate()
{
    freopen("fbg.log", "w", stdout);
}

AppDelegate::~AppDelegate()
{
    ...
    fclose(stdout);
}

And after the judgement statement if (!glview), add these codes:

#if(CC_TARGET_PLATFORM == CC_PLATFORM_WP8) || (CC_TARGET_PLATFORM == CC_PLATFORM_WINRT)
    glview = cocos2d::GLViewImpl::create("cocos_gameroom_sample_js");
    director->setOpenGLView(glview);
#else
    const wchar_t title[]{ L"Facebook Gameroom" };
    auto parentWin = FindWindow(NULL, title);

    // set dpi for app
    auto res_dpi = SetProcessDPIAware();

    RECT rect;
    GetWindowRect(parentWin, &rect);
    glview = GLViewImpl::createWithRect("cocos_gameroom_sample_js", Rect(0, 0, rect.right - rect.left - 20, rect.bottom - rect.top - 100), 1.0f, true);
    director->setOpenGLView(glview);
    auto currentWin = Director::getInstance()->getOpenGLView()->getWin32Window();
    SetParent(currentWin, parentWin);
#endif

And register js-binding functions after statement sc->addRegisterCallback(register_all_cocos2dx_3d_extension);

#ifdef SDKBOX_ENABLED
    sc->addRegisterCallback(register_all_PluginGameroomJS);
    sc->addRegisterCallback(register_all_PluginGameroomJS_helper);
#endif

Usage

About the details of these methods depicted below, you can access the section API Reference. And if you wanna know the corresponding functions in Facebook Gameroom SDK, you can refer to Facebook Gameroom SDK website.

Initialize Plugin Gameroom

Before you call other APIs, you should Initialize the plugin in app.js.

sdkbox.PluginGameroom.init('your_facebook_app_id');

Set Listener

As other SDKBOX plugins, you need to set a listener object to handle events.

sdkbox.PluginGameroom.setListener({
    onLoginAccessTokenMsg: function (handle) {
    },

    onFeedShareMsg: function (handle) {
    },

    onPurchaseIAPMsg: function (handle) {
    },

    onHasLicenseMsg: funciton (handle) {
    },

    onAppRequestMsg: function (handle) {
    }
});

Each callback will be explained below.

After the plugin is initialized, when your game starts, you should make a login call to retrieve player information. You can use a simple method login() or another method loginWithScopes for it.

The different between these two methods is that login() method will always apply 3 permissions of the player: user_friends, email and public_profile.

sdkbox.PluginGameroom.login()

But you can pass some parameters to loginWithScopes() method to designate witch permissions are applied. In this example, public_profile and email will be applied.

sdkbox.PluginGameroom.loginWithScopes(2, ['public_profile', 'email']);

You can also check whether the player has logged in:

ret = sdkbox.PluginGameroom.isLoggedIn();

The player login action will trigger onLoginAccessTokenMsg callback in your listener object. For examle, you can use some properties to retrieve the player's login information via the parameter handle.

onLoginAccessTokenMsg: function (handle) {
    cc.log('============');
    cc.log('onLoginAccessTokenMsg');
    cc.log(JSON.stringify(handle, null, 2));
    if (handle.isValidToken) {
        self.showText('login successful');
    }
    else {
        self.showText('login failed');
    }
}

In your game, you can offer the sharing function to the players:

sdkbox.PluginGameroom.feedShare(
        '',
        'https://www.facebook.com',
        'Testing Link Name',
        'Testing Link Caption',
        'Testing Link Description',
        'http://www.pamperedpetz.net/wp-content/uploads/2015/09/Puppy1.jpg',
        ''
);

Above example shares an image to the player's Facebook.

In your listener object, onFeedShareMsg will be called after sharing with the argument handle. Post ID can be returned if you access the property of handle.

onFeedShareMsg: function (handle) {
    cc.log('============');
    cc.log('onFeedShareMsg');
    self.showText('onFeedShareMsg');
    cc.log('shared post id = ' + handle.postID);

}

IAP

IAP funciton includes 3 aspects:

IAP with a product ID configured in your Facebook App.

sdkbox.PluginGameroom.purchaseIAP(
        'sdkbox_product_1',
        1,
        1,
        1,
        '',
        '',
        ''
);

IAP with an url link.

sdkbox.PluginGameroom.purchaseIAPWithProductURL(
        'https://friendsmash-unity.herokuapp.com/payments/100coins.php',
        1,
        1,
        1,
        '',
        '',
        ''
);

Purchase a premium version or license.

sdkbox.PluginGameroom.payPremium();

These 3 types of IAP will trigger onPurchaseIAPMsg callback. Here is an example to show how to handle the IAP result.

onPurchaseIAPMsg: function (handle) {
    cc.log('============');
    cc.log('onPurchaseIAPMsg');
    self.showText('onPurchaseIAPMsg');
    cc.log('payment ID = '+ handle.paymentID);
    cc.log('amount = ' + handle.amount);
    cc.log('curency = ' + handle.currency);
    cc.log('purchase time = ' + handle.purchaseTime);
    cc.log('product ID = ' + handle.productID);
    cc.log('purchase token = ' + handle.purchaseToken);
    cc.log('quantity = ' + handle.quantity);
    cc.log('request id = ' + handle.requestID);
    cc.log('status = ' + handle.status);
    cc.log('signed req = ' + handle.signedReq);
    cc.log('error code = ' + handle.errorCode);
    cc.log('error msg = ' + handle.errorMsg);

}

In addtion, you can use hasLicense() method to check whether the player has got the license or premium version.

sdkbox.PluginGameroom.hasLicense();

Please note that this checking operation will trigger a callback named onHasLicenseMsg. Bizarrely, you should get the license ID via the property hasLicense of handle object in callback(Faceebook Gameroom SDK demands these behaviors).

onHasLicenseMsg: function (handle) {
    cc.log('============');
    cc.log('onHasLicenseMsg');
    self.showText('onHasLicenseMsg');
    cc.log('has license = ' + handle.hasLicense);
}

Send App Events

You can log app events for Facebook Analytics via the following functions:

sdkbox.PluginGameroom.logAppEvent('test_event_1', { 'key1': 'val1', 'key2': 'val2' });
sdkbox.PluginGameroom.logAppEventWithValueToSum('test_event_2', { 'key3': 'val3', 'key4': 'val4' }, 10.24);

The key-value pairs are carried in an JavaScript object. And if you intend to offer an extra value in an event, you should use logAppEventWithValueToSum() method.

Send App Requests

To invoke an app request within your game, you may use the following call to trigger the dialog:

sdkbox.PluginGameroom.appRequest('hello, try this js demo.', '', '', 'faceboo_user_id_1, facebook_user_id_2', '', '', 20, '', 'hello');

In common, you don't need to set the users' ID in order to let the player choose which friends he want to send the requests.

sdkbox.PluginGameroom.appRequest('hello, try this js demo.', '', '', '', '', '', 20, '', 'hello');

In the callback of sending app requests, you can hanedle the result:

onAppRequestMsg: function (handle) {
    cc.log('============');
    cc.log('onAppRequestMsg');
    self.showText('onAppRequestMsg');
    cc.log('objectID = ' + handle.objectID);
    cc.log('to user: ' + handle.toUser);
}

API Reference

Methods

sdkbox.PluginGameroom.init(appID);

Initialize the Gameroom Plugin. appID is your Facebook Application ID. The method will return 0 if the plugin is Initialized successfully.

sdkbox.PluginGameroom.login();

Player login. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.loginWithScopes(scopeCount, loginScopes);

Player login with some permissions. scopeCount is the total of the permissions. loginScopes is a vector which can include these values: public_profile, email, user_friends and publish_actions. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.isLoggedIn();

Check whether the player has logged in.

sdkbox.PluginGameroom.feedShare(
    toId,
    link,
    linkName,
    linkCaption,
    linkDescription,
    pictureLink,
    mediaSource
);

Share to Facebook. The meaning of each parameters is as its name. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.purchaseIAP(
    product,
    quantity,
    quantityMin,
    quantityMax,
    requestId,
    pricePointId,
    testCurrency
);

Purchase a product with a prouduct ID. quantity is the number of product, quantityMin is the minimum number of quantity of product, quantityMax is the maximum of quantity of product. For other parameters, you can refer to Facebook Gameroom SDK and SDKBOX Gameroom Plugin Sample. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.purchaseIAPWithProductURL(
    product,
    quantity,
    quantityMin,
    quantityMax,
    requestId,
    pricePointId,
    testCurrency
);

Purchase a product with a prouduct url link. quantity is the number of product, quantityMin is the minimum number of quantity of product, quantityMax is the maximum of quantity of product. For other parameters, you can refer to Facebook Gameroom SDK. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.payPremium();

Purchase a premium version or license. It will return a string representing GameroomReq.

sdkbox.PluginGameroom.hasLicense();

Check whether the player has license or premium version. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.logAppEvent(eventName, formData);

Send an event to Facebook Analytics. FormDataHandle is a JavaScript object. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.logAppEventWithValueToSum(eventName, formData, valueToSum);

Send an event to Facebook Analytics with an extra value valueToSum. FormDataHandle is a JavaScript object. The method will return a string representing GameroomReq.

sdkbox.PluginGameroom.appRequest(
    message,
    actionType,
    objectID,
    to,
    filters,
    excludeIDs,
    maxRecipients,
    data,
    title
);

Send an app request to some users. if parameter to is nullptr, this method will let player to choose which users he want to send the request. For other parameters, please refer to Facebook Game Service Requests and SDKBOX Gameroom Plugin Sample. The method will return a string representing GameroomReq.

Listener Callbacks

Each parameter in callback is a JavaScript object, which has the properties to indicate the result of coresponding methods.

onLoginAccessTokenMsg(AccessTokenHandle);

Triggered by login() or loginWithScopes().

onFeedShareMsg(FeedShareHandle);

Triggered by feedShare().

onPurchaseIAPMsg(PurchaseHandle);

Triggered by purchaseIAP(), purchaseIAPWithProductURL() or payPremium().

onHasLicenseMsg(HasLicenseHandle);

Triggered by hasLicense().

onAppRequestMsg(AppRequestHandle);

Triggered by appRequest().

sdkbox.PluginGameroom.setListener(listenerObject);

Set a JavaScript listener object.