一.简介

WING FB小游戏SDK主要是为满足Facebook Instant Game（以下称小游戏）需要，为此类游戏封装Facebook小游戏正常运行所需的功能。该SDK仅适用于Facebook小游戏。

二.Facebook小游戏概述

Facebook小游戏是Facebook推出的HTML5类型的即时游戏，这类游戏主要以体积小，启动快，可同时运行于Facebook页端，Facebook PC端和移动端Messenger，依赖于Facebook庞大的用户群体，小游戏有望迅速积累用户。

三.小游戏上架步骤

小游戏新手入门可以参照Facebook官方文档（需要授权才能浏览）：https://developers.facebook.com/docs/games/instant-games
以下是小游戏快速上架简单步骤：

3.1 认证合作伙伴

2021 年 6 月 9 日后，仅经认证的合作伙伴才能在开放平台上发布游戏。其次，成为认证合作伙伴后，必须提交所有新游戏》必须以供质量审核
参考链接 : https://developers.facebook.com/docs/games/onboarding/instant-games

3.2 开发小游戏

WING FB小游戏SDK为了方便cp接入，已经做了封装。接入步骤：
1、集成WING FB小游戏SDK 参考 如何集成
2、初始化 参考初始化
3、加载游戏进度。如游戏较大，可以调用完wing.fbinstant.setLoadingProgress()后，游戏再加载自己的进度条 报告游戏的初始加载进
4、游戏自己逻辑

注:根据Facebook打包要求，根目录要有index.html以及fbapp-config.json文件。压缩后大小不超过200M。
可参考WING FB小游戏SDK demo:
https://github.com/ghw-wingsdk/wing-fbinstant/archive/refs/tags/v3.4.0.zip

3.3 Facebook后台配置小游戏

请参考以下文档进行配置：
第三方后台配置-Facebook小游戏

在Facebook应用管理后台创建应用->小游戏，输入名字等信息。
打开刚创建的facebook应用后台，商品->添加商品->小游戏，点击设置，填写该产品必填信息，如下图所示：

配置好Instant Games之后，还需要添加配置‘网页托管’，如下图：

3.4 测试游戏

配置好后便可以测试游戏了，测试游戏可以先在本地服务器运行，参考链接：
https://developers.facebook.com/docs/games/instant-games/test-publish-share
中的Testing the game from a local server部分。

本地测试完成后可以上传小游戏到Facebook后台进行托管，在上面提到的‘网页托管’中上传。小游戏上传成功后把状态改成‘推到生产’，测试人员便可在Messenger，手机和pc浏览器或者facebook app中进行测试。

3.5 发布游戏

在内部测试结束后便可提交Facebook审核上线了

审核前，需要选择审核的版本，小游戏-网页托管，选择需要审核的版本，点击星号按钮，发布到生产

如下图，提交的过程需要按照要求配置好相关信息。

3.6 其他配置

游戏在pc横屏展示，在mobile端竖屏展示

在 fbapp-config.json 文件配置
{
“instant_games”: {
“orientation”: “PORTRAIT”,
“override_web_orientation”: “LANDSCAPE”,
}
}

四.SDK功能简介

WING FB小游戏SDK主要包括以下模块：

4.1.玩家模块

用于获取玩家基本信息、设置获取储存的游戏数据、匹配玩家、获取排行榜信息等功能。

4.3.环境模块

用于邀请其他玩家、分享游戏信息及获取当前游戏唯一标志、切换到指定环境、切换到其它游戏等功能。

4.4.支付模块

提供获取商品列表及支付功能。

4.5.公共模块

用于获取玩家语言、平台、小游戏版本、设置游戏载入进度、开始游戏、设置玩家等级、 服务区服、游戏用户ID、置顶游戏等功能。

4.6.数据收集模块

数据收集模块提供了数据收集的接口，并发到Facebook后台以及WINGSDK后台。数据收集包含了丰富的应用内的事件类型，还支持用户自定义事件类型。

4.7.广告模块

接入Facebook广告系统，获取facebook后台配置的广告并展示。

4.8.排位赛模块

有用于获取新玩家，玩家可以分享自己游戏中的排行榜，提示好友加入挑战赛，并发布自己的比赛分数进行排行

4.9.调试模块

开启调试模式我们将会打印所有SDK在运行过程中的LOG，方便在集成阶段检查。同时我们提供一个可视化的图标及页面，方便在手机端也能查看log日志。

五.集成WING FB小游戏SDK

5.1.适用范围

该SDK适用于Facebook小游戏。Facebook小游戏可以运行于移动端messenger app、Facebook app、手机和pc浏览器、Facebook app等环境中。

5.2.如何集成

WING FB小游戏SDK推荐使用标签方式引入JS，同时也支持AMD、CommonJS等方式引入。

注：第二行引用的注释不需要打开。

5.3.接口说明

此章节结合Facebook小游戏SDK对接文档来看会更清晰：
https://developers.facebook.com/docs/games/instant-games/sdk/fbinstant7.1

注意：如无特别说明，本文档接口的回调方法中的对象形式如下：
{ code:成功或失败代码, message:相关提示消息, data:具体数据}；

5.3.1.初始化

5.3.1.1.初始化

接口名称：wing.init(config);
接口说明：WING SDK在使用前需要调用此接口设置初始化参数，并完成登录操作
参数说明：

示例：
//初始化数据

返回结果参数说明：

5.3.1.2.调试

通过在WING SDK 管理后台 设置》测试设备 中添加设备ID 到测试设备列表，可打开LOG 日志。

5.3.2.玩家模块

1.获取玩家ID

接口名称：wing.fbinstant.getPlayerID()
接口说明：获取facebook小游戏玩家ID

参数：无
示例：

2.获取获取玩家的唯一标识和签名

接口名称：wing.fbinstant.getSignedPlayerInfoAsync()
接口说明：异步获取小游戏唯一标识和签名

参数说明：

示例：

返回结果参数说明：

3.获取经本地化显示的玩家姓名

接口名称：wing.fbinstant.getName()
参数说明：无
示例 ：

4.获取玩家公开头像的网址

接口名称：wing.fbinstant.getPhoto()
参数说明：无
示例 ：

5.设置要保存到指定云存储的当前玩家的数据, 对于每个独立玩家，游戏最多可存储 1MB 的数据。

接口名称：wing.fbinstant.setDataAsync()
接口说明：设置要保存到指定云存储的当前玩家的数据, 对于每个独立玩家，游戏最多可存储 1MB 的数据。
参数说明：

示例：

返回结果参数说明：

6.从指定的云存储中检索当前玩家的数据

接口名称：wing.fbinstant.getDataAsync()
参数说明：

示例：

返回结果参数说明：

8.立即将玩家数据的任何更改刷新到指定的云存储中

接口名称：wing.fbinstant.flushDataAsync()
参数说明：

示例：

返回结果参数说明：

11.提取 ConnectedPlayer对象的数组，这些对象包含与当前玩家关联的玩家的信息

接口名称：wing.fbinstant.getConnectedPlayersAsync()
接口说明：提取 ConnectedPlayer对象的数组，这些对象包含与当前玩家关联的玩家的信息
参数说明：

示例：

返回结果参数说明：

12.检查当前玩家是否可以使用匹配玩家接口

接口名称：wing.fbinstant.checkCanPlayerMatchAsync(object)
接口说明：可以使用该接口来寻找陌生人组群来玩游戏。此接口一般与wing.fbinstant.matchPlayerAsync(object)接口成对使用并且比后者先调用。
参数说明：

示例：

返回结果参数说明：

13.匹配玩家

接口名称：wing.fbinstant.matchPlayerAsync(object)
接口说明：匹配成功后创建一个新的messager组，玩家转移到该小组中。该接口需要和与接口wing.fbinstant.checkCanPlayerMatchAsync(object)联合使用。
参数说明：

示例：

返回结果参数说明：

14.获取游戏排行榜

接口名称：wing.fbinstant.getLeaderboardAsync(object)
接口说明：使用该接口可以获取到当前游戏的排行榜。前提是排行榜需先在Facebook后台配置好，玩家在玩游戏的过程中把相应的分数记录到排行榜中。
参数说明：

示例：

返回结果参数说明：

15.检查是否能订阅游戏消息助手

接口名称：wing.fbinstant.canSubscribeBotAsync (object)
接口说明：游戏智能助手会自动相应某些操作，一般与接口wing.fbinstant.subscribeBotAsync (object)成对使用 。
参数说明：

示例：

16.玩家订阅游戏消息助手 (强烈建议接入)

接口名称：wing.fbinstant.subscribeBotAsync (object)
接口说明：此接口必须在接口wing.fbinstant.canSubscribeBotAsync(object)被调用之后回调结果成功才可使用。建议在游戏进服后(选择游戏服务器，然后进入游戏时)调用。
参数说明：

示例：

5.3.4.环境模块

5.3.4.1.当前游戏环境的唯一标识

接口名称：wing.fbinstant.getContextID()
参数说明：
无

示例：

5.3.4.2.当前游戏环境的类型

接口名称：wing.fbinstant.getContextType()
参数说明：
无

示例：

5.3.4.3.确定加入当前游戏环境的玩家数量是否在给定的最小值和最大值之间

接口名称：wing.fbinstant.isSizeBetween()
参数说明：

示例：

5.3.4.4.请求切换到指定环境

接口名称：wing.fbinstant.switchAsync()
接口说明：使用此接口可以在不同玩家环境中切换
参数说明：

示例：

5.3.4.5.为玩家打开一个环境选择对话框, 邀请好友进行游戏。邀请后在调用wing.fbinstant.updateAsync()接口，可在message上通知相关玩家

接口名称：wing.fbinstant.chooseAsync()
参数说明：

示例：

5.3.4.6.尝试在指定玩家和当前玩家之间创建环境或切换环境

接口名称：wing.fbinstant.createAsync()
参数说明：

示例：

5.3.4.7.获取#contextplayer 对象的数组

接口名称：wing.fbinstant.getPlayersAsync()
接口说明：获取#contextplayer 对象的数组，其中包含与当前环境相关的活跃玩家（在过去90天内玩过游戏的用户）的信息。这可能包含当前玩家。
参数说明：

示例：

5.3.4.8.在不同的游戏之间切换

接口名称：wing.fbinstant.switchGameAsync(object)
参数说明：

示例：

返回结果参数说明：

5.3.5.支付模块

5.3.5.1.检查支付环境是否已经可用

接口名称：wing.fbinstant.payOnReady(callbackFunction)
参数说明：

示例：

返回结果参数说明：void

5.3.5.2.获取商品列表

接口名称：wing.fbinstant.queryProducts (object)
接口说明：此接口获取到的商品列表是wingsdk后台配置的商品列表，wingsdk后台需要配置好wingsdk商品与Facebook商品之间的映射，购买时只需要传wingsdk的商品Id即可。
参数说明：

示例：

返回结果参数说明：

返回结果示例：

5.3.5.3.支付

接口名称：wing.fbinstant.pay(object)
参数说明：

示例：

返回结果参数说明：

返回结果示例：

对于支付，接口的一般使用流程是：首先检查支付环境是否可用，可用的情况下查询商品获取商品列表，自行渲染商品列表页面，玩家选择商品（传入商品Id）进行购买。

注意：支付失败的回调fail(包含环境不能用时)，根据以往游戏审核出现的问题，此时需要研发做出提示，参考提示语：Payment not supported yet

5.3.6.广告模块

5.3.6.1.缓存插屏广告

接口名称： wing.fbinstant.getInterstitialAdAsync()
参数说明：

示例：

5.3.6.2.播放插屏广告

接口名称： wing.fbinstant.showInterstitialAdAsync()
参数说明：

示例：

5.3.6.3.缓存奖励视频广告

接口名称： wing.fbinstant.getRewardedVideoAsync()
参数说明：

示例：

5.3.6.4.播放奖励视频广告

接口名称： wing.fbinstant.showRewardedVideoAsync()
参数说明：

示例：

5.3.6.5.展示banner广告

接口名称： wing.fbinstant.showBannerAdAsync()
参数说明：
|参数名|类型|必填|说明|备注|
|—|—|—|—|—|
|success|JavaScript方法|N|执行成功回调方法||
|fail|JavaScript方法|N|执行失败回调方法||
示例：

5.3.6.6.隐藏banner广告

接口名称： wing.fbinstant.hideBannerAdAsync()
参数说明：
|参数名|类型|必填|说明|备注|
|—|—|—|—|—|
|success|JavaScript方法|N|执行成功回调方法||
|fail|JavaScript方法|N|执行失败回调方法||
示例：

5.3.7.数据收集模块

使用SDK数据收集接口配合大数据平台，可以轻松统计玩家习惯以及充值等行为，为游戏的市场营销提供数据依据。
目前数据收集支持以下平台：WINGSDK，Facebook。
WINGSDK数据收集使用在游戏的过程中打点的方式，如图所示:

1. 以上流程图中涉及到的几个接口是有时序要求的，请参考流程图中的逻辑步骤进行设置：setServerId、setGameUserId、setLevel、ghw_user_import事件、ghw_user_create事件
2. 其它的事件如ghw_level_achieved、ghw_self_tutorial_completed、ghw_self_lv_x等请根据对应业务逻辑，在对应业务发生时调用接口发送。

小游戏SDK会把事件同时发送到Facebook与WINGSDK后台。

5.3.7.1.事件发送（同时发送WINGSDK与Facebook）

此方式需要构造json对象作为参数。
接口名称：wing.fbinstant.logEvent()
参数说明：

示例：

5.3.7.2.预定义事件

小游戏SDK包括了以下预定义事件。

5.3.7.2.1. ghw_initiated_purchase点击购买（虚拟货币）

说明:点击购买的时候调用（用于游戏内部虚拟交易统计）。
无参数
代码示例：

5.3.7.2.2. ghw_purchase购买完成（虚拟货币）

说明:购买完成的时候调用（用于游戏内部虚拟交易统计）。

代码示例：

5.3.7.2.3. ghw_level_achieved 等级增长事件

说明:统计玩家等级增长事件，达到等级时调用。

注意：发送ghw_level_achieved事件前需调用3.1.3 设置用户等级level接口更新用户等级信息。

代码示例：

5.3.7.2.4. ghw_user_create 创建角色

说明:创建游戏角色，游戏角色创建时调用

代码示例：

5.3.7.2.5 ghw_user_import导入用户事件

说明:导入用户事件，玩家第一次进某个服时调用

注意：发送ghw_user_import事件前需调用wing.fbinstant.setServerId()接口更新服务器id以及wing.fbinstant.setGameUserId()接口更新游戏用户id

代码示例：

5.3.7.2.6. ghw_self_tutorial_completed 完成新手任务

说明:新手完成新手任务时调用

无参数
代码示例：

5.3.7.2.7. ghw_self_lv_x 关键等级

说明:完成关键等级时调用，如ghw_self_lv_1、ghw_self_lv_3

无参数

代码示例：

5.3.7.2.8 设置玩家昵称 wing.fbinstant.setNickname

示例：

5.3.7.2.9 ghw_user_info_update 更新用户信息

代码示例：

5.3.8.事件名与事件参数

以下是SDK内部预定义事件名与事件参数。

5.3.8.1 事件名

以下是SDK预定义事件名。

5.3.8.2 事件参数

以下是SDK预定义事件的参数。

5.3.8 公共模块块

1.当前的语言设置

接口名称：wing.fbinstant.getLocale()

参数说明：无
示例：

2.当前运行游戏的平台

接口名称：wing.fbinstant.getPlatform()
接口说明：该接口可能返回的值有：(“IOS” | “ANDROID” | “WEB” | “MOBILE_WEB”)
参数说明：无
示例：

3.报告游戏的初始加载进度(此函数Facebook要求调用，见本文后面的发布检查表)

接口名称：wing.fbinstant.setLoadingProgress(value);

参数说明：value, 0~100
示例：

4.返回与启动游戏的入口点相关的任何数据对象

接口名称：wing.fbinstant.getEntryPointData()
接口说明：游戏的入口可能是另外一个游戏，比如接口wing.fbinstant.switchGameAsync(object)，该接口在原游戏中传入一些参数给目标游戏，在原游戏中启动目标游戏，目标游戏变可以获取到这些参数。

参数说明：无
示例：

返回值示例：{“myReplayData”:”…”}

5.返回启动游戏的入口点

接口名称：wing.fbinstant.getEntryPointAsync()
接口说明：调用该接口可以获取到游戏是从什么地方进来，已知的值目前有game_switch（游戏切换启动）、other（本地调试启动）、game_composer（pc版messenger中启动）、games_hub(客户端messenger中启动)等，可以参考官方相关说明：https://developers.facebook.com/docs/games/instant-games/guides/analytics 。

参数说明：

示例：

6.为当前环境设置与单个游戏会话相关的数据

接口名称：wing.fbinstant.setSessionData()

参数说明：

示例：

7.开始游戏

接口名称：wing.fbinstant.startGameAsync()
接口说明：此接口应在初始化接口调用成功后尽早调用（表示游戏已完成初始加载， 并准备就绪可以开始游戏）

参数说明：

示例：

8.分享

接口名称：wing.fbinstant.shareAsync()

参数说明：

示例：

9.更新游戏内容

接口名称：wing.fbinstant.updateAsync()
接口说明：一般调用此接口后，Facebook会在Messenger中通知对应的玩家。
这些更新也可能触发向玩家发送通知。这些更新可以用于从一个玩家那里广播游戏中的重大事件，作为回合提醒，以提示其他玩家进行他们的回合，或发送邀请与他人一起玩。
参数说明：

示例：

10.退出游戏

接口名称：wing.fbinstant.quit()
参数说明：无
示例：

11.设置发生暂停事件时将触发的回调

接口名称：wing.fbinstant.onPause()
参数说明：

示例：

12.设置游戏用户id

接口名称：wing.fbinstant.setGameUserId()

参数说明：

示例：

13.设置服务器id

接口名称：wing.fbinstant.setServerId()

参数说明：

示例：

14.设置等级

接口名称：wing.fbinstant.setLevel()

参数说明：

示例：

15.判断玩家是否可以置顶游戏/创建快捷方式

接口名称：wing.fbinstant.canCreateShortcutAsync(object)
接口说明：
参数说明：

示例：

16.提示玩家置顶游戏/创建快捷方式(强烈建议接入)

接口名称：wing.fbinstant.createShortcutAsync(object)
接口说明：置顶游戏。为了方便玩家快捷启动游戏，facebook提供快捷启动游戏接口:在iOS、android web端表现为提示是否需要游戏置顶，在Android facebook app上表现为在主屏幕创建快捷方式，在iOS Facebook app上则无表现。建议在游戏过了新手后进行调用。此接口必须在接口wing.fbinstant.canCreateShortcutAsync(object)被调用之后回调结果成功才可使用，且调用太频繁将无法弹出游戏置顶弹框
参数说明：

示例：

17.邀请好友进行游戏

接口名称：wing.fbinstant.inviteAsync()
接口说明: 邀请好友去玩游戏，可邀请多个好友，邀请后相应玩家即会收到message消息提醒。

示例：

18.检测用户是否可以关注官方公共主页（sdk 3.4.0及以后版本才可用）

接口名称：wing.fbinstant.canFollowOfficialPageAsync()
接口说明: 检测用户是否可以关注官方公共主页

示例：

19.关注官方主页（sdk 3.4.0及以后版本才可用）

接口名称：wing.fbinstant.followOfficialPageAsync()
接口说明: 关注官方主页，先调用wing.fbinstant.canFollowOfficialPageAsync()检测可关注后，再调用

示例：

20.检测用户是否可以加入官方游戏组（sdk 3.4.0及以后版本才可用）

接口名称： wing.fbinstant.canJoinOfficialGroupAsync()
接口说明: 检测用户是否可以加入官方游戏组

示例：

21.加入官方游戏组（sdk 3.4.0及以后版本才可用）

接口名称：wing.fbinstant.followOfficialPageAsync()
接口说明: 加入官方游戏组，wing.fbinstant.canJoinOfficialGroupAsync()被调用之后回调结果成功才可使用。游戏小组创建流程（需要公共主页管理员权限）：在游戏公共主页tab导航栏 –> 点击’小组’栏 –> 点击创建绑定小组 –> 填写信息 –> 点击创建。如果绑定了多个小组，调用接口后会以第一个创建的小组展示给玩家加入。

示例：

5.3.8. 排位赛模块

5.3.8.1.创建排位赛

接口名称： wing.fbinstant.tournamentCreateAsync(obj)
接口说明：
参数说明：

示例：

5.3.8.2.提交排位赛分数

接口名称： wing.fbinstant.tournamentPostScoreAsync(obj)
接口说明： 进行排位赛结束后，可以进行分数提交
参数说明：

示例：

5.3.8.3. 分享排位赛

接口名称：wing.fbinstant.tournamentShareAsync(obj)
参数说明：

示例：

5.3.8.4. 获取当前排位赛信息

接口名称： wing.fbinstant.getTournamentAsync(obj)
参数说明：

示例：

5.3.8.5. 加入排位赛

接口名称： wing.fbinstant.tournamentJoinAsync(obj)
参数说明：

示例：

5.3.8.6. 获取排位赛列表

接口说明：返回一个可在游戏中出现的符合条件的比赛列表，包括1)玩家已经创建的比赛;2)玩家参与其中;3)玩家的好友(获得许可的)也参与其中
接口名称： wing.fbinstant.getTournamentsAsync(obj)
参数说明：

示例：

5.3.9 绑定CG短链

5.3.9.1 检测是否可以绑定CG平台短链接口

接口说明：检测是否可以获取绑定CG平台短链
接口名称： wing.fbinstant.canGetBindAccountUrl()
返回结果:BOOL

示例：

5.3.9.2 获取绑定CG平台短链接口

接口说明：获取绑定CG平台短链接口，需要先检测能够获取的情况下，才能调用
接口名称： wing.fbinstant.getBindAccountUrl(obj)
参数说明：

示例：

返回结果参数说明：

六.状态码

本SDK接口调用状态码如下：

七.参考

Facebook小游戏说明文档：
https://developers.facebook.com/docs/games/onboarding/instant-games

Facebook官方接口对接文档：
https://developers.facebook.com/docs/games/instant-games/sdk/fbinstant7.0

Facebook小游戏发布检查表：
https://developers.facebook.com/docs/games/instant-games/getting-started/launch-checklist