‹ Facebook Gameroom Doc Home

Facebook Gameroom 集成指南

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

预备条件

请参考 Facebook 的官方文档，在你的 Facebook Application 中设置 Gameroom 相关的配置。

与 Cocos 工程集成

使用 SDKBOX Installer （推荐）

• 使用 SDKBOX Installer，你可以非常方便的在 Windows 下安装插件。你可以访问 SDKBOX 官方网站 获取更多信息安装 SDKBOX Installer。

• 在下载 SDKBOX Installer 之后，你可以用它在线直接安装 Gaemroom 插件：

sdkbox import gameroom

• 或者，如果你的 Gameroom 插件是在本地的，你也可以离线安装它：

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

手动集成

如果你想手动集成 Gameroom 插件，你需要一步步的完成下列多种配置。这些步骤比较复杂，我们并不推荐你手动集成插件。

1. 找到 Visual Studio Solution 文件并且打开它。对于 JS 工程，你可以在 ./framework/runtime\_src/proj.win32 子目录下找到这个文件。为了便于下面的描述，我们将 proj.win32 这个目录命名为项目目录。

2. 解压 Gameroom 插件包，你会得到一个目录，我们把这个目录称作插件目录。

3. 拷贝头文件。对于 JS 工程，拷贝插件目录下的 win32/include/*.h 头文件到项目目录的 include/plugingameroom 文件夹下。

4. 拷贝插件目录下的 win32/libs/*.lib 库文件到项目目录下的 libs 文件夹下。

5. 部署 Facebook Gameroom SDK 文件。

   a. 拷贝插件目录下的 sdk/fbg 头文件目录到你的项目目录下的 include 子文件夹下。

   b. 拷贝插件目录下的 sdk/libs/*.lib 库文件到你的项目目录下的 libs 子文件夹下。

6. 对于 JS 工程， 你需要添加一些与 js-binding 相关的代码文件。把它们从 插件目录 下的 jsbindings 子目录拷贝到项目目录的上一级目录下的 /Classes 里。

7. 修改 Visual Studi 配置：

   a. 为编译器添加头文件目录，依次单击：项目 -> 属性 -> 配置属性 -> VC++ 目录 -> 包含目录 （单击编辑，添加新项）。

   然后添加 $(solutiondir)include 。

   b. 添加库文件目录，依次单击：项目 -> 属性 -> 配置属性 -> VC++ 目录 -> 库目录（单击编辑，添加新项）。

   然后添加 $(solutiondir)libs 。

   c. 链接库文件，依次单击：项目 -> 属性 -> 配置属性 -> 链接器 -> 输入 -> 附加依赖项 （单击编辑，添加新项）。

   然后添加 GameroomPlugin32.lib 以及 LibFBGPlatform32.lib 。

   对于 debug 版本，请添加 GamerommPlugin32.debug.lib 。

8. 打开项目目录子文件夹 /Classes 中的 AppDelegate.cpp 文件，准备为其打代码补丁。

9. 接下来打补丁的步骤也可以使用 patch 工具完成。对于 JS 工程，请使用插件目录下的 AppDelegate.js3.15.patch 文件。

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

• 在 USING_NS_CC添加 SDKBOX 头文件：

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

• 在 AppDelegate 类的构造与析构函数里，重定向 STDOUT 至一个文件，因为 Facebook SDK 没有提供任何 log API 。

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

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

• 在判断语句 if (!glview) 之后添加如下代码：

#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

• 在语句 sc->addRegisterCallback(register_all_cocos2dx_3d_extension); 之后添加注册 js-binding 函数的代码：

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

用法

关于本章下面提到的方法的细节，你可以访问 API Reference 一节。并且如果你想进一步了解这些方法在 Facebook Gameroom SDK 中相应的细节，你可以参考 Facebook Gameroom SDK 官方网页 。

初始化 Gameroom 插件

在你调用其他 API 之前，你应该在 app.js 中初始化插件。

sdkbox.PluginGameroom.init('your_facebook_app_id');

设置 Listener

与其他 SDKBOX 插件一样， 你需要设置一个 listener 对象去处理回调事件。

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

    onFeedShareMsg: function (handle) {
    },

    onPurchaseIAPMsg: function (handle) {
    },

    onHasLicenseMsg: funciton (handle) {
    },

    onAppRequestMsg: function (handle) {
    }
});

这个对象中的每一个回调函数将在下面的小节中解释。

用户登录

在插件初始化之后，当你的游戏在 Gameroom 运行时，你应该让玩家登录你的游戏并且获取玩家的信息。你可以使用简单的 login() 方法或者另一个稍复杂的 loginWithScopes() 方法去完成这一功能。

这两个方法的不同之处在于 login() 方法在完成用户登录时总是申请使用以下3种权限: user_friends，email 以及 public_profile 。

sdkbox.PluginGameroom.login()

而使用另一个方法 loginWithScopes() ，你可以在玩家登录时指定申请的权限。在下面的例子里，user_friends 和 email 权限将被申请使用。

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

你也可以像下面的例子那样来检测用户是否已经完成登录：

ret = sdkbox.PluginGameroom.isLoggedIn();

玩家登录将会触发 listener 对象中的 onLoginAccessTokenMsg 回调。你可以像下面例子中那样从参数 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');
    }
}

分享至 Facebook

在你的游戏中，你可以给玩家提供分享功能：

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

上面的例子将会分享一张图片到玩家的 Facebook 。

在分享发生之后，listener 对象里的 onFeedShareMsg 回调将会被调用。你可以通过 handle 的属性取到 Post ID 。

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

}

IAP

插件的 IAP 功能包括以下3种类型：

• 通过配置在 Facebook App 中的 product ID 进行 IAP 。

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

• 通过一个商品的 url 进行 IAP 。

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

• 购买付费版本或者许可证。

sdkbox.PluginGameroom.payPremium();

这3种类型的 IAP 都会触发 onPurchaseIAPMsg 回调。这里有一个例子说明了如何在这个回调中通过 handle 对象的属性得到 IAP 相关的结果。

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

}

另外，你可以调用 hasLicense() 方法去检测该玩家是否购买了许可证或者付费版。

sdkbox.PluginGameroom.hasLicense();

值得注意的是，这个方法将会触发 onHasLicenseMsg 回调。奇怪之处在于，你必须在这个回调中通过用 handle 对象的属性去取得许可证或者付费版的 ID 。（Facebook Gameroom SDK 要求这样做）

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

发送 App 日志事件

你可以通过下面的方法将你的游戏事件日志记录到 Facebook Analytics：

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. 键值对数据存储在一个 JavaScript 对象中。如果你想在事件中提供额外的值，你应该使用 logAppEventWithValueToSum() 方法。

发送游戏请求

你可以使用下面的方法触发一个对话框以在你的游戏内发送游戏请求：

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

通常情况下，你不需要设置用户 ID ，这样就可以让玩家在对话框里选择他想发送请求的朋友。

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

在游戏请求的回调里，你可以像下面这样得到请求的相关属性和结果：

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.