‹ Facebook Gameroom Doc Home

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

Using SDKBOX Installer (recommend)

sdkbox import gameroom
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.

  1. 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.

  2. Unzip the Gameromm Plugin package to get a dir including the plugin files. It's called plugin-dir.

  3. Copy header files. For JS project, copy win32/include/*.h in plugin-dir to include/plugingameroom in your project-dir.

  4. Copy library files win32/libs/*.lib in plugin-dir to libs in your project-dir.

  5. 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.

  6. 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.

  7. 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.

  8. Patch the AppDelegate.cpp. Open the AppDelegate.cpp in project-dir/Classes.

  9. 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
#ifdef SDKBOX_ENABLED
#include "PluginGameroomJS.hpp"
#include "PluginGameroomJSHelper.h"
#endif
AppDelegate::AppDelegate()
{
    freopen("fbg.log", "w", stdout);
}

AppDelegate::~AppDelegate()
{
    ...
    fclose(stdout);
}
#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
#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.

User Login

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');
    }
}

Feed Share

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:

sdkbox.PluginGameroom.purchaseIAP(
        'sdkbox_product_1',
        1,
        1,
        1,
        '',
        '',
        ''
);
sdkbox.PluginGameroom.purchaseIAPWithProductURL(
        'https://friendsmash-unity.herokuapp.com/payments/100coins.php',
        1,
        1,
        1,
        '',
        '',
        ''
);
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.