メインコンテンツまでスキップ

ショートカットアイコン作成支援機能

概要​

スマートフォン Web の弱点として、ホームスクリーン上に配置するショートカットアイコンの作成が困難であることがあげられます。
ダウンロード時にショートカットアイコンが必ず作成される Native アプリと比較すると、明確な弱点であると考えられます。

Mobage JS SDKでは、「ショートカットアイコン作成を促す」ガイドをどのページからも呼び出すことが可能となる機能を提供しています。
この機能を利用して作成したショートカットアイコンを利用すれば、事前に指定したURLに遷移できるだけでなく、ショートカット経由の起動を検知することもできます。
この検知機能を利用して、ショートカットアイコンを作成してくれたユーザーにインセンティブを付与することも可能です。

ここでは、この「ショートカットアイコン作成支援機能」を組み込み、ショートカット経由での起動が行われたことを Game Server で検知する機能を開発していきます。

作成するファイル一覧​

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

ファイル名概要
config.php各種設定値をまとめます
show_guide.phpClient側での画面の UI を実装しています
show_guide.jsClient側でショートカットアイコン作成支援サービスを実行します
receive_notification.phpPlatformからの通知によりショートカットアイコンのユーザー利用記録を残します

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

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

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

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

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

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

開発のステップ​

「ショートカットアイコン作成支援機能」を実現するために、大きく以下の3ステップで進めます。

  1. Mobage Developers Japan で Shortcut Icon の登録をする

  2. Client にて ショートカットアイコン作成支援サービスを呼び出す

  3. Server にて Platform からの通知を処理する※

    備考

※ Platform からの通知を受け取る機能はオプショナルであるため、インセンティブ付与など Game 要件に沿って実装してください。。 :::

Mobage Developers Japan で Shortcut Icon の登録をする​

ショートカットアイコン作成支援機能で利用するショートカットアイコンの設定を行います。

  1. ダッシュボードの左メニューより「アプリケーション」>「アプリケーション一覧」画面を開きます。
  2. 「アプリケーション一覧」から開発しているアプリケーションを選択します。
  3. 表示されたページの上部にある「SPWeb」タブを選択します。
  4. SPWebのページ中央部、「Mobage Connect 情報」の右側にある「情報を変更」を押下します。
  5. Mobage Connect情報の複数あるタブの中から、「画像設定」を選択します。
  1. デフォルトで設定されている top について、「ショートカット起動時の通知先URL」やショートカットアイコンの「タイトル」、ショートカットアイコンの「画像」を登録します。

  2. 必要な情報を入力後、「ステータス」のショートカットステータス「有効化」を押下します。

  3. 登録したショートカットアイコンについて、Mobage JS SDK を利用して「ショートカットアイコン作成支援機能」を利用することが出来るようになります。

Client にて ショートカットアイコン作成支援サービスを呼び出す​

Client では、 Mobage JS SDK の mobage.ui.show() メソッドを用いて、shortcut_icon サービスを利用します。

備考

このサービスは、Mobage 非会員ユーザーでも利用することができます。

ここではボタンをクリックした際のイベントをトリガーに、mobage.ui.show() メソッドの shortcut_icon サービスを実行するよう、実装します。
なお、以下の shortcutType には先ほど登録したデフォルト識別子の top を指定します。

mobage-jssdk-sample-others/shortcut_icon/show_guide.js

showShortcut = document.getElementById('show_shortcut');

showShortcut.addEventListener('click', function() {
mobage.ui.show('shortcut_icon', {shortcutType : 'top'});
}, false);

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

この機能を利用してユーザーが作成したショートカットアイコンから、ユーザーがゲームを起動すると、以下のタイミングで Platform から Game Server に通知が送られます。

ユーザーの状態Platform からの通知が送られるタイミング
Mobage Connect からログアウトしている(もしくは非会員である)Mobage Connect にログインした時
Mobage Connect へログインしているショートカットアイコンからゲームを起動した時
備考

Mobage Connect にログインしていない場合は、ショートカットアイコンを利用した後に、ユーザーがログインしたタイミングで通知が来ます。
Mobage Connect にログインしている場合とのタイミングの違いに注意してください。

この通知は、Mobage Developers Japan で Shortcut Icon の登録をするで先ほど登録したURLに、JSON Web Token(JWT)というフォーマットで送られます。

この JWT は署名アルゴリズムが RS256 となっています。ここでは JWT の検証として、以下のライブラリを利用します。

  • https://github.com/firebase/php-jwt
     
    Platform から送られたリクエストは Platform 側の秘密鍵で署名がつけられているため、X.509 形式の公開鍵を利用して署名の妥当性を検証します。
    (署名の検証で利用する公開鍵)
    ここでは、以下のように検証します。

    mobage-jssdk-sample-others/shortcut_icon/receive_notification.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) {
    render_error_json();
    }

    Platform から送られる JWT の payload(JWT Claims Set)は以下のようなデータ構造をしています。

    {
    "sub" : "12341234" ,
    "iat" : 1411625625 ,
    "jti" : "12123312" ,
    "typ" : "shortcut_icon_start_application" ,
    "aud" : "12000129-4" ,
    "iss" : "`https://sb-hub.mobage.jp"` ,
    "event" : {
    "iconId" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" ,
    "type" : "top"
    }
    }

    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 の検証が完了したら、ゲームの要件にしたがった処理を実施します。
(ユーザにアイテムを付与したり、何かインセンティブを提供するなどの要件が考えられます)
ここでは以下のようにログだけを残します。

mobage-jssdk-sample-others/shortcut_icon/receive_notification.php

error_log('iconId:' . $jwt_claims->event->iconId . ',type:' . $jwt_claims->event->type . "\n", 3, '../log/shortcut_icon.log');

Platformへのレスポンス送信​

Platformからのリクエストに対して、以下の場合に 成功レスポンス を返します。

  • JWT の検証を通過した場合
  • Game Server の内部処理が成功した場合

また、以下の場合には 失敗レスポンス を返します。

  • Platformからのリクエストに異常があった場合
  • JWTの検証を通過することが出来なかった場合
  • その他、Game Server の内部処理で異常があった場合
Platformへ成功レスポンス送信する​

JWT の検証を通過し、意図した Game Server の内部処理が成功した場合に、成功レスポンスを返します。
成功レスポンスのhttp status code は 200 OK とします。

備考

Platformからのリクエストは、最大10回まで再送処理が行われます。Platformに成功レスポンスを返すと、この再送処理は止まり、それ以上リクエストは送られません。

Platformへ失敗レスポンスを送信する​

Game Server の内部処理で異常があった場合など、Platformへ失敗レスポンスを返します。
失敗レスポンスのhttp status code は 4xxもしくは5xxなどの適切なレスポンスを返します。
 
 

動作確認​

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

ファイル名URL
config.phphttp://example.com/mobage-jssdk-sample-others/config.php
show_guide.phphttp://example.com/mobage-jssdk-sample-others/shortcut_icon/show_guide.php
show_guide.jshttp://example.com/mobage-jssdk-sample-others/shortcut_icon/show_guide.js
receive_notification.phphttp://example.com/mobage-jssdk-sample-others/shortcut_icon/receive_notification.php
備考

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

Game Server に配置したプログラムに、以下のURLでアクセスします。

表示されているガイドに従って、「ホーム画面に追加」を押下します。

以下のような画面が表示されるので、右上の「追加ボタン」を押下してアイコンを追加します。

ショートカットアイコンがホームスクリーンに追加されることが確認できます。
このショートカットアイコンを押下します。

ショートカットアイコンから以下のように事前に設定したページに遷移することが確認できます。

 
ここでは、ユーザーがショートカットアイコンからゲームを起動すると、Platformからの通知が来てログを残す処理を実装しているので、ログを監視します。

iconId:17b6093e-2584-3c4c-8796-b3807f26a531,type:top

上記のようにショートカットアイコンを使ってゲームを起動すると、Platformからの通知が来てログがはかれることを確認できました。

開発したコード​

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

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

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

  • 概要
  • 作成するファイル一覧
  • チュートリアルをはじめる前に
    • サンプルコードのダウンロード
  • 開発のステップ
    • Mobage Developers Japan で Shortcut Icon の登録をする
    • Client にて ショートカットアイコン作成支援サービスを呼び出す
    • Server にて Platform からの通知を処理する
  • 動作確認
  • 開発したコード