Skip to main content

友達招待サービス

概要​

Mobage JS SDK では友達招待サービスを利用することができます。友達招待サービスを利用することで、招待を送ったユーザーと招待を受け取ったユーザーの両方にインセンティブを付与することが実現可能となります。

このチュートリアルでは、「友達招待サービス」を実現するための実装方法や、「友達招待を送信した / 友達招待が成立した」などの条件で Platform から送信される通知について、通知を受け取って処理するプログラムを開発していきます。

作成するファイル一覧​

このチュートリアルで作成するファイルは下記になります。

ファイル名概要
config.php各種設定値をまとめます
invite.phpClient側での画面の UI を実装しています
invite.jsClient側で友達招待サービスを実行します
sent_invitation.phpClient から Game Server に送られる友達招待送信結果を処理します
sent_async_invitation.phpPlatform から Game Server に送られる友達招待送信通知を受け取ります
accepted_async_invitation.phpPlatform から Game Server に送られる友達招待成立通知を受け取ります

チュートリアルをはじめる前に​

このチュートリアルは、以下のチュートリアルを終わらせている前提で進めます。
以下のチュートリアルでファイル作成していない場合は、先にそちらを完成させましょう。

サンプルコードのダウンロード​

Github からサンプルコードを clone できます。

$ git clone https://github.com/DeNADev/mobage-jssdk-sample-others.git

また、以下のライブラリを利用するので、ダウンロードしておきます。

開発のステップ​

「友達招待機能」を実現するために、大きく以下の4ステップで進めます。

  1. Mobage Developers Japan(デベロッパーサイト)で 友達招待の通知先 URL を登録をする
  2. Client にて 友達招待サービスを呼び出す
  3. Server にて Client から送られた友達招待送信結果を処理する
  4. Server にて Platform からの通知を処理する

Mobage Developers Japan(デベロッパーサイト)で 友達招待の通知先 URL を登録をする​

友達招待機能で利用する Platform からの通知には、以下の2つがあります。

  • 友達招待 送信 通知
  • 友達招待 成立 通知

これらの通知先 URL を、Mobage Developers Japan(デベロッパーサイト)で設定します。

  1. ダッシュボードの左メニューより「アプリケーション」>「アプリケーション一覧」画面を開きます。
  2. 「アプリケーション一覧」から開発しているアプリケーションを選択します。
  3. 表示されたページの上部にある「SPWeb」タブを選択します。
  4. SPWebのページ中央部、「Mobage Connect 情報」の右側にある「情報を変更」を押下します。
  5. 下記のような画面が表示されるので、「Invitation送信通知処理設定」を選択します。
7. 「Subscriber Callback URI (Sandbox用)」に、友達招待が送信されたときに Platform から送られる通知の、通知先 URL を登録してください。 ※ここでは、「sent\_async\_invitation.php」へのリンクを設定します。
info

なお、Mobage 内の友達に招待を送信した場合にのみ、Platform から友達招待の送信通知が送られます。

  1. 次に、「Invitation 成立通知処理設定」を選択します
  2. 「Subscriber Callback URI (Sandbox用)」に、友達招待が成立したときに Platform から送られる通知の、通知先 URL を登録してください。
    ※ここでは、「accepted_async_invitation.php」へのリンクを設定します。

これらの設定により、友達招待が送信された時と、友達招待が成立した時に Platform から Game Server に通知が送られるようになります。

info

なお、送信通知の場合と違って、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";
}
});
}
info

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
}
warning

なお、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)) {
    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 から送信された 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の値
sandboxhttps://sb-widget.mobage.jp
servicehttps://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);
}
info

なお、この処理のhttp_status != 200 での処理は、Game Server 側で正常にインセンティブ付与を行えなかったときに表示されます。
この場合、この後に紹介する Platform からの通知によってユーザーにインセンティブ付与を行ってください。
また、Game Server としては、Client と Platform から二重に通知が来ることになるので、インセンティブの二重付与に気を付けてください。

TOC

Server にて Platform からの通知を処理する​

友達招待に関して、Platform から Game Server に以下の2種類の通知が来ます。

  • 友達招待が送信されたことの通知

  • 友達招待が成立したことの通知
     
    それぞれの通知は、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
    }
    warning

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
}
warning

invitedUserId は後方互換のために残しているので利用せず、代わりに inviteeUserId を利用してください。

 
上記2つの通知は署名アルゴリズムが 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の値
sandboxhttps://sb-hub.mobage.jp
servicehttps://hub.mobage.jp

JWT の検証が完了したら、ゲームの要件にしたがったインセンティブ付与などの処理を実施します。
(ユーザにアイテムを付与したり、何かインセンティブを提供するなどの要件が考えられます)
 
TOC

友達招待の準備​

動作確認のため、招待する側(以下、User1) と招待される側(以下、User2) の2つ分のテストアカウントを作成しておきます。
既に1つぶんのアカウントは作成済みですので、こちら のチュートリアルと同様の手順でもう1つのアカウントである User2 を作成します。

warning

User1 に招待されるまで、User2 でゲームをインストールしないように注意してください。

作成した2人ぶんののテストアカウントを友達に設定するには、以下のSandbox 支援機能を利用します。

もし User1 以外のアカウントでログインしている場合は、いったんログアウトして再度 User1 でログインしてください。
「アカウント一覧」をクリックします。

テストアカウントの一覧が表示されますので、招待される側である User2 を選択します。

プロフィール画像が開きますので、「友達希望する」のリンクを選択して友達申請を行います。

次に、 User1 をログアウトし、 User2 で Sandbox 支援機能ページにログインします。
マイページを表示し、「チャット」のリンクを選択して友達申請を承諾します。

 
画面の遷移に従って申請を承諾します。



これで User1 と User2 は友達になりました。

動作確認​

では、開発したプログラムを下記のように Game Server に配置します。

ファイル名URL
config.phphttp://example.com/mobage-jssdk-sample-others/config.php
invite.phphttp://example.com/mobage-jssdk-sample-others/invitation/invite.php
invite.jshttp://example.com/mobage-jssdk-sample-others/invitation/invite.js
sent_invitation.phphttp://example.com/mobage-jssdk-sample-others/invitation/sent_invitation.php
sent_async_invitation.phphttp://example.com/mobage-jssdk-sample-others/invitation/sent_async_invitation.php
received_async_invitation.phphttp://example.com/mobage-jssdk-sample-others/invitation/received_async_invitation.php
info

このチュートリアルを進めるためには、Platformからのリクエストを受け取れる Game Server の用意が必要となります。このチュートリアルでは、example.comというドメインでPlatformからのリクエストを受け取れるGame Serverを用意した前提で説明を進めます。

まだログインしていない場合は、以下のURLでアクセスします。

「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 側で確認したら、ゲームの要件に従って招待を送信したユーザーにインセンティブの付与などを行います。

これで、友達を招待してインセンティブを付与するチュートリアルは終了です。

注意事項​

  • JS SDK のバージョンは2.5.0以上をご利用ください。

開発したコード​

このチュートリアルで開発したコードは Github から clone できます。

$ git clone https://github.com/DeNADev/mobage-jssdk-sample-others.git

利用したライブラリは下記になります。

  • 概要
  • 作成するファイル一覧
  • チュートリアルをはじめる前に
    • サンプルコードのダウンロード
  • 開発のステップ
    • Mobage Developers Japan(デベロッパーサイト)で 友達招待の通知先 URL を登録をする
    • Client にて友達招待サービスを呼び出す
    • Server にて Client から送られた友達招待送信結果を処理する
    • Server にて Platform からの通知を処理する
  • 友達招待の準備
  • 動作確認
    • 友達招待送信の動作確認を行う
    • 友達招待成立の動作確認を行う
  • 注意事項
  • 開発したコード