好友邀请服务
概要
在 Mobage JS SDK 中,可使用好友邀请服务。通过使用好友邀请服务,可对发送邀请用户和收到邀请用户给予奖励。
在本教程中,开发实现“好友邀请服务”所需的实现方法,以及按照“好友邀请已发送 / 好友邀请已成功”等条件从 Platform 发送通知的通知接收处理程序。
需创建的文件列表
在本教程中,要创建的文件如下所述。
| 文件名 | 概要 |
|---|---|
| config.php | 各种设置值 |
| invite.php | 实现 Client 端的画面 UI |
| invite.js | 在 Client 端执行好友邀请服务 |
| sent_invitation.php | 对 Client 发送至 Game Server 的好友邀请函发送结果进行处理 |
| sent_async_invitation.php | 对 Platform 发送至 Game Server 的好友邀请函发送通知进行接收 |
| accepted_async_invitation.php | 对 Platform 发送至 Game Server 的好友邀请成功通知进行接收 |
教程前序
本教程在以下教程结束的前提下进行。
在以下教程中,如未创建文件,请先完成。
下载样例代码
样例代码可从 Github 克隆。
$ git clone https:``//github.com/DeNADev/mobage-jssdk-sample-others.git |
另外,事先下载以下程序库以备使用。
开发的步骤
为了实现“好友邀请功能”,需按以下4大步骤进行。
- 在 Mobage Developers Japan(开发者网站)中注册好友邀请通知目标 URL
- 在 Client 中调用好友邀请服务
- Server端处理从Client发送过来的好友邀请
- 在 Server 中对 Platform 通知进行处理
在 Mobage Developers Japan(开发者网站)中注册好友邀请通知目标 URL
在好友邀请功能中使用的 Platform 通知有以下两种。
- 好友邀请 发送 通知
- 好友邀请 成功 通知
在 Mobage Developers Japan(开发者网站)中,设置这些通知目标 URL。
- 从仪表盘的左菜单,打开“应用软件”>“应用软件列表”画面。
- 从“应用软件列表”中,选择当前开发的应用软件。
- 选择显示页面上方的“SPWeb”选项卡。
- 点击SPWeb页面中央部“Mobage Connect 信息”右侧的“更改信息”。
- 会显示以下画面,选择“Invitation发送通知处理设置”。
7. 请将发送好友邀请时 Platform 发送通知的通知目标 URL ,注册至“Subscriber Callback URI (Sandbox用)”。
※在此,设置对“sent\_async\_invitation.php”的链接。
只有在向 Mobage 中的好友发送邀请后,Platform 才会发送好友邀请函发送通知。
- 接着,选择“Invitation 成功通知处理设置”
- 请将好友邀请成功时 Platform 发送通知的通知目标 URL ,注册至“Subscriber Callback URI (Sandbox用)”。
※在此,设置对“accepted_async_invitation.php”的链接。
通过这些设置,在好友邀请函发送时和好友邀请成功时, Platform 会向 Game Server 发送通知。
与发送通知不同,无论Mobage 内外好友,当好友邀请成功时, Platform 均会向 Game Server 发送通知。
TOC
在 Client 中调用好友邀请服务
在 Client 端,采用 Mobage JS SDK 的 mobage.ui.open() 方法,使用 invitation 服务。
在此,以点击按键时的事件作为触发器,实现使用mobage.ui.open() 方法执行 invitation 服务。
mobage-jssdk-sample-others/invitation/invite.js
inviteButton = document.getElementById(``'invite'``); if (clientData.state) { var params = { state : clientData.state }; mobage.oauth.getConnectedStatus(params, function``(err, result) { if (result) { sendToRedirectURI(result); inviteButton.style.cssText = "visibility:visible"``; inviteButton.addEventListener(``'click'``, function``() { mobage.ui.open( "invitation"``, {}, function (error, result) { if (error) { if (error.error == "user_canceled"``) { window.alert(``'邀请已被取消'``); } else { window.alert(``'邀请失败'``); } } else { if (result.response.result.channel == 'mobage'``) { sendInvitationResult(result); } } } ); }, false``); } else { console.log(``'getConnected Status Error'``); inviteButton.style.cssText = "visibility:hidden"``; } }); } |
向 Mobage 外的好友发送邀请信息时,callback 接收 result 对象的 channel 参数为 email 或 **line,**inviteeUserIds 为空白。
另外,向 Mobage 外的好友发送邀请时,Platform 不会发送通知。
在本教程中,实现的规格是只有向Mobage 内的好友发送邀请信息时才会给予奖励。
好友邀请函发送成功后,通过callback 函数向 Game Server 发送 result.signedResponse。
在此发送以下内容。
mobage-jssdk-sample-others/invitation/invite.js
// Send to GameServer function sendInvitationResult(result) { console.log(``'sendInvitationResult was called.'``); var req = new XMLHttpRequest(); req.open(``'POST'``, 'sent_invitation.php'``); req.setRequestHeader(``'Content-Type'``, 'application/json;charset=UTF-8'``); req.addEventListener(``'load'``, function``() { showInvitationSuccessfulDialog(req, result); } , false``); req.send(result.signedResponse); } |
result.signedResponse 的发送格式为 JSON Web Token(JWT)。
解码 signedResponse 后的 JWT,其 payload(JWT Claims Set) 的数据结构如下。
{ "jti"``: "87090946" , "iss"``: "https://sb-widget.mobage.jp"```,` "aud"``: "12000129-4" , "sub"``: "12341234" , "typ"``: "signed_extra"``, "extra "``: { "service "``: "invitation"``, "result "``: { "invitee "``: [``"12012" , "34881" , "77601"``], "inviteeUserIds"``: [``"12012" , "34881" , "77601"``] } }, "iat"``: 1406108627 } |
不使用为了向后兼容而保留的 invitee,作为替代请使用 inviteeUserIds。
TOC
Server端处理从Client发送过来的好友邀请
Client 发送至 Game Server 的 result.signedResponse,在 Game Server 进行 JWT 验证。
result.signedResponse 的签名算法为 RS256。在此使用以下程序库进行JWT 验证。
-
https://github.com/firebase/php-jwt
此 JWT 带有 Platform 端的私钥签名,因此使用 X.509 格式的公钥对签名的适宜性进行验证。
(签名验证用公钥)mobage-jssdk-sample-others/invitation/sent_invitation.php// load json from request body$jwt_body=file_get_contents``(``'php://input'``);if(``empty``(``$jwt_body``)) {echojson_encode(['result'=> false ]);return``;}// decode JSON Web Tokentry{$jwt_claims= JWT::decode(``$jwt_body``, PUBLIC_KEY,array``(``'RS256'``));}catch(Exception$e``) {error_log``(``'jwt_decode failed because '.$e."\n"``, 3, ERROR_LOG_PATH);render_error_json();}为了对 Platform 发送的 result.signedResponse 进行适宜性确认,实现 JWT 正文 JWT Claims Set 的验证处理。在Game Server 中的验证项目如下。
-
iss(Issuer Claim, 发行此 JWT 的服务器的标识符)是否适宜?
-
aud(Audience Claim, 作为此 JWT 公开范围而指定的 Client ID)与应用软件的Client ID是否一致?
-
sub(Subject Claim)与登录用户持有的Mobage用户ID是否一致?
-
iat(Issued At)是比当前时间早的UNIX时间戳值吗?
iss 值在 sandbox/service 中是如下所示的不同值。
| 环境 | iss 值 |
|---|---|
| sandbox | https://sb-widget.mobage.jp |
| service | https://widget.mobage.jp |
JWT 验证完成后,根据游戏条件进行给予奖励等处理。
(向用户交付物品或提供奖励等条件)
在此只留下以下日志。
mobage-jssdk-sample-others/invitation/sent_invitation.php
$result = [ 'From' => 'Client'``, 'inviterUserId' => $jwt_claims``->sub, 'inviteeUserIds' => $jwt_claims``->extra->result->inviteeUserIds ]; error_log``(json_encode(``$result``) . "\n"``, 3, SENT_INVITATION_LOG_PATH); |
根据游戏条件进行处理后,向 Client 反馈成功响应。
在 Client 端,根据收到的响应,进行以下处理。
mobage-jssdk-sample-others/invitation/invite.js
// 好友邀请函发送成功对话 function showInvitationSuccessfulDialog(req, result) { if (req.status != 200) { window.alert(``"邀请已发送。交付物品尚需时间"``); return``; } var res = JSON.parse(req.response); window.alert(res); } |
Game Server 端不能正常给予奖励时,会显示此处理的 http_status != 200 处理。
此时,请根据下文介绍的 Platform 通知,向用户给予奖励。
另外,Game Server 会从 Client 和 Platform 收到双重通知,因此请注意避免给予双重奖励。
TOC
在 Server 中对 Platform 通知进行处理
从 Platform 发送至 Game Server 的好友邀请通知有以下两种。
-
好友邀请已发送的通知
-
好友邀请已成功的通知
采用 JSON Web Token(JWT) 格式发送各通知。
JWT 中的 Parameter 稍微不同,但在Game Server 端进行的处理 (JWT 验证) 相同,因此在此一并开发。好友邀请已发送的通知
好友邀请已发送的通知 JWT payload 如下。
{"jti"``:"87090946","iss"``:"https://sb-hub.mobage.jp"```,`"aud"``:"12000129-4","sub"``:"12341234","typ"``:"user_invitation_sent"``,"event "``: {"inviterUserId "``:"12341234"``,"inviteeUserIds"``: [``"12012","34881","77601"``],"recipients"``: [``"12012","34881","77601"``],},"iat"``:1406108627}注意
不使用为了向后兼容而保留的 recipients,作为代替请使用 inviteeUserIds。 :::
好友邀请已成功的通知
好友邀请已成功的通知的 JWT payload 如下。
{ "jti"``: "87090946" , "iss"``: "https://sb-hub.mobage.jp"```,` "aud"``: "12000129-4" , "sub"``: "12341234" , "typ"``: "user_invitation"``, "event "``: { "inviterUserId "``: "12341234"``, "inviteeUserId"``: "12012"``, "invitedUserId"``: "12012" }, "iat"``: 1406108627 } |
不使用为了向后兼容而保留的 invitedUserId,作为代替请使用 inviteeUserId。
上述两种通知的签名算法为 RS256。在此使用以下程序库进行JWT 验证。
本 JWT 带有 Platform 端的私钥签名,因此使用 X.509 格式的公钥对签名的适宜性进行验证。
(签名验证用公钥)
mobage-jssdk-sample-others/invitation/sent_async_invitation.php or accepted_async_invitation.php
// load json from request body $jwt_body = file_get_contents``(``'php://input'``); if (``empty``(``$jwt_body``)) { echo json_encode([ 'result' => false ]); return``; } // decode JSON Web Token try { $jwt_claims = JWT::decode(``$jwt_body``, PUBLIC_KEY, array``(``'RS256'``)); } catch (Exception $e``) { error_log``(``'jwt_decode failed because ' . $e . "\n"``, 3, ERROR_LOG_PATH); render_error_json(); } |
为了确认 Platform 发送的通知是否适宜,实现对 JWT 正文 JWT Claims Set 的验证处理。在Game Server 中的验证项目如下。
- iss(Issuer Claim, 发行此 JWT 的服务器的标识符)是否适宜?
- aud(Audience Claim, 作为此 JWT 公开范围而指定的 Client ID)与应用软件的Client ID是否一致?
- sub(Subject Claim)与登录用户持有的Mobage用户ID是否一致?
- iat(Issued At)是比当前时间早的UNIX时间戳值吗?
iss 值在 sandbox/service 中是如下所示的不同值。
| 环境 | iss 值 |
|---|---|
| sandbox | https://sb-hub.mobage.jp |
| service | https://hub.mobage.jp |
JWT 验证完成后,根据游戏条件进行给予奖励等处理。
(向用户交付物品或提供奖励等条件)
TOC
好友邀请的准备
为了进行动作确认,预先创建邀请端(下称User1) 和被邀请端(下称User2) 这两个测试帐号。
1个帐号已创建,因此按照与 这里 的教程同样步骤,创建另1个帐号 User2。
在获得 User1 邀请之前,不得用User2 身份安装游戏,敬请注意。
使用以下Sandbox 辅助功能,在好友中设置已创建的两个测试帐号。
- Sandbox辅助功能
请从验证用终端的浏览器,访问 http://sb-sp.mobage.js/_sandb_top。
如果已用 User1 以外的帐号登录,请退出后重新用 User1 身份登录。
点击“帐号列表”。

会显示测试帐号列表,选择被邀请端 User2。

会打开个人简介图片,选择“希望添加好友”链接,进行好友申请。

接着, 退出User1,用 User2 身份登录 Sandbox 辅助功能页面。
显示我的页面,选择“聊天”链接,同意好友申请。

按照画面跳转,同意申请。




至此, User1 与 User2 成功成为好友。
动作确认
下面,按如下所示,将开发的程序配置于 Game Server。
为了进入本教程,需要准备可接收Platform 请求的 Game Server 。在本教程中,假设已准备可接收Platform请求的Game Server,域名为example.com,以此为前提进入说明。
未登录时,访问以下URL。
-
http://example.com/mobage-jssdk-sample-login/hybrid_flow/login_hybrid.php
好友邀请函发送的动作确认
首先,为了对好友邀请函发送进行监控,预先在Game Server 端进行日志监控。
勿忘确认能否从Game Server 端的程序写入日志的权限。tail -f mobage-jssdk-sample-others/log/sent_invitation.log在有进行好友邀请的用户且在登录状态下,点击以下URL访问Game Server 中配置的程序。
-
http://example.com/mobage-jssdk-sample-others/invitation/invite.php
点击“Invite Friends”键,调用好友邀请服务

从调用的好友邀请服务中,触摸“邀请梦宝友”。

从列表中选择想要发送邀请的梦宝友,触摸“邀请选中者”。

至此,向梦宝友发送邀请完成。
确认以下通知已发到监控日志中。
确认通知已从Client 发到 Game Server。
{``"From"``:``"Client"``,``"inviterUserId"``:``"43485"``,``"inviteeUserIds"``:[``"38215"``,``"58628"``,``"57267"``,``"66608"``]} |
写有上述日志,故确认通知已发到。
另外,确认好友邀请函发送通知已通过非同步方式从Platform 发到 Game Server。
{``"From"``:``"Platform"``,``"inviterUserId"``:``"43485"``,``"inviteeUserIds"``:[``"38215"``,``"58628"``,``"57267"``,``"66608"``]} |
写有上述日志,故确认通知已发到。
在 Game Server 端确认好友邀请已发送后,按照游戏条件对发送的用户给予奖励等。
好友邀请成功的动作确认
接着,进行好友邀请成功的动作确认。
为了对好友邀请成功进行监控,预先在Game Server 端进行日志监控。
勿忘确认能否从Game Server 端的程序写入日志的权限。
tail -f mobage-jssdk-sample-others/log/accepted_invitation.log |
用被邀请人User2 身份重新登录 Sandbox 辅助功能,确认Chat。

会通过 Chat 收到好友邀请信息,选择此信息。
如下所示,会显示来自邀请人User1 的好友邀请信息。

通过带有好友邀请信息的链接,安装游戏。

邀请的对方已通过邀请信息安装游戏,至此,好友邀请成功。
最后,确认好友邀请成功通知已从Platform 发到 Game Server。
{``"inviterUserId"``:``"43485"``,``"inviteeUserId"``:``"38215"``} |
如上所述,通过查看监控日志,确认好友邀请成功。
在 Game Server 端确认好友邀请成功后,按照游戏条件对发送邀请的用户给予奖励等。
至此,邀请好友和给予奖励的教程结束。
注意事项
- 请使用2.5.0及更高版本的JS SDK。
开发的代码
本教程开发的代码可从 Github 克隆。
$ git clone https:``//github.com/DeNADev/mobage-jssdk-sample-others.git |
使用的程序库如下。