リモート通知機能の使い方

2014/03/19 より Grade 1 のユーザーでも User to User のリモート通知機能が利用可能となりました。
リモート通知は定型文のみの利用が可能です。

はじめに

リモート通知機能は、Apple 社から提供される APNs (Apple Push Notification service) や Google 社から提供されるC2DM (Cloud to Device Messaging) を利用して、ユーザ間での通知、ゲームサーバーからの通知を行うことができる機能です。通知されたメッセージは、端末の通知領域に通知されます。アプリケーション内で通知内容を受け取ることも可能です。
 
以下の SDK バージョン以降で使用が可能です。

SDK

Version

Mobage ngCore SDK

1.7

デベロッパーサイトでアプリケーション詳細よりAndroidアプリ設定もしくはiOSアプリ設定を登録することで、下図左下のようなリモート通知設定へのリンクが表示されますので、こちらをクリックします。

使用の際の注意点

  • リモート通知機能は必ずユーザに通知が送信されるのを保証するものではないことをご了承ください。
  • リモート通知機能の通知内容を、ユーザに自由に入力・編集させることを禁止します。そのためUser to Userの通知では通知内容を必ず定型文で構成してください。

Android での設定方法 (GCM/C2DMの設定)

ngCore 1.10 未満、Native/Unity SDK 1.4 未満、ShellApp 1.0.1 未満をご利用の場合のみ下記設定が必要となります。

Android の場合、下図のように GCM/C2DM 設定タブを選びます。

「C2DMを利用する」の項目にチェックを入れ、「入力内容確認」ボタンをクリックすることで、利用申請を行うことができます。

C2DM 設定で「入力内容確認」ボタンをクリックすると、下図のように Gloogle C2DM のサービスステータスが「未設定」から「利用可能」になり、リモート通知機能が使用可能になります。

iOS での設定方法

iOS の場合、下図のように APN 設定タブを選びます。

Sandbox用と本番用のリモートSSL証明書をアップロードすることができます。アップロードするファイルは.pemファイルとなります。

.pemファイルの作成方法につきましては下記を参考にされるか、こちら(日本語)をご確認ください。

  1. iOS Dev Center の iOS Provisioning Portal へアクセスします。
  2. 左側のメニューより、App IDs をクリックします。
  3. 既にアプリケーションを作成している場合には、対象の App ID をクリックし、展開された画面の『Edit』ボタンをクリックします。新規にアプリケーションを作成する場合には、右上の New App ID をクリックして、新規 App ID を作成後に対象の App ID をクリックし、展開された画面の『Edit』ボタンをクリックします。(新規 App ID 作成につきまして、詳しくは Topic 内の『iTunes Connect へのアップロード方法』をご確認ください)
  4. 画面内の『Push Notifications』をチェックします。
  5. Sandbox用は Development Push SSL Certificate の「Configure」ボタンをクリックします。本番用の場合は Production Push SSL Certificate の「Configure」ボタンをクリックします。 クリックすると、『About Creating a Certificate Signing Request (CSR)』画面が起動します。
  6. キーチェーンアクセスを起動し、以下の手順に従って CertificateSigningRequest.certSignningRequest を作成します。
    1. 上部メニューバーより、[キーチェーンアクセス]→[証明アシスタント]→[認証局に証明書を要求]をクリックします。
    2. [ユーザのメールアドレス]と[通称]を入力、[要求の処理]に「ディスクの保存」を選択し、「続ける」ボタンをクリックします。(CAのメールアドレスと、鍵ペア情報を指定のチェックボックスは空で結構です)
    3. 任意の保存先を選び、「保存」ボタンをクリックして CertificateSigningRequest.certSignningRequest を保存します。
  7. 『About Creating a Certificate Signing Request (CSR)』 画面に戻り、「Generate」ボタンをクリックします。
  8. 『Generate your certificate.』画面へ遷移しますので、「ファイルを選択」ボタンをクリックし、先程作成した CertificateSigningRequest.certSignningRequest を選択します。
  9. Your APNs SSL Certificate has been generated. と表示されますので、「Continue」ボタンをクリックします。
  10. 「Download」ボタンをクリックすると、証明書がダウンロードされます。ダウンロード後は右下の「Done」ボタンをクリックしてください。Push SSL Certificate の Status が Enabled になっていることを確認してください。
  11. ダウンロードした証明書をダブルクリックして、キーチェーンに登録します。
  12. キーチェーンアクセスの左下の「分類」より「証明書」を選択、登録した Apple Development IOS Push Servicesを選択し、メニューバーより、[ファイル]→[書き出す]で任意の場所に「個人情報交換ファイル(p12)」を保存します。書き出す際には任意のパスワードの設定が必要です。
  13. ターミナルから以下のコマンドで、「個人情報交換ファイル(p12)」を.pemファイルに変換します。

上記で作成した.pemファイルを、APN設定タブのリモートSSL証明書のリンクよりアップロードします。Sandbox用は Development Push SSL Certificate 、本番用は Production Push SSL Certificate をアップロードします。

アップロードすると、下図のような有効期間が表示され、利用状況と「入力確認」ボタンがアクティブになり、Apple Push Notification のサービスステータスが「利用不可」になります。

iOSのリモート通知機能を使用するためには、利用状況を「利用する」に設定し、「入力内容確認」ボタンをクリックします。入力内容確認画面の後、下図のように Apple Push Notification サービスステータスが「利用可能」になり、リモート通知機能が使用可能になります。

iOS の appファイル側でリモート通知機能を使用するためには、特別なre-signツールを使用して再署名する必要があります。
リモート通知用の re-sign ツールに関しましてはこちらにアップロードされております。また、使用方法につきましても上記URLに記載がありますのでご参照ください。
本番、Sandbox ともに、 SSL 証明書 (pem ファイル) の有効期限が切れた場合には、リモート通知が送信できなくなりますのでご注意下さい。有効期限が切れた場合には SSL 証明書 (pem ファイル) を入れ替えると、再び送信が可能となります。
リモート通知機能を試すだけであれば、Mobage Developers Japan に設定している CFBundleIdentifier と SSL 証明書 (pem ファイル) の整合性がとれている必要はありません。 SSL 証明書 (pem ファイル) と署名されている Provisioning Profile の整合性がとれていれば動作します。

リモート通知機能の使用方法

概要

リモート通知機能は、APNs や C2DM を使用して実現されます。以下の概念図において、パートナー様の実装が必要な部分は、端末やサーバーから通知内容を送信する部分(1)、端末上で受信する部分(2)です。

送信側の実装について

リモート通知機能の送信側には以下のケースが存在します。

Location

API

User to User

Client API or RESTful API

Game to User

RESTful API

Client APIとはSDKに含まれているAPIです。例えば、ngCore SDKの場合はJavaScriptのAPIのことを指します。
RESTful API に関しまして、こちらもご参照下さい。

リモート通知内容について

リモート通知の送信内容は、payload ( JSON 形式) で指定できます。payload の フォーマットについて以下に説明します。送信された payload 内の内容は全て受信側で受け取ることが可能です。

Name

必須

説明

message

String

Required

リモート通知のメッセージ内容です。通知バーに表示されます。UTF-8の文字列で指定してください。

badge

Integer

Optional

iOS端末にリモート通知が送信された場合、badge の数値は受信側のアイコンのバッジとして使用されます。badge が指定されない場合は数字は特に送信されません。Android端末の場合は、badge が送信されても影響は有りません。

sound

String

Optional

iOS端末にリモート通知が送信された場合、受信側の警告音として使用されます。sound はアプリケーションに含まれた音声ファイル名になります。音声ファイルが存在しない場合、"default"が指定された場合、デフォルトの警告音が再生されます。Android端末の場合は、sound が指定されていても無視され音は再生されません。

collapseKey

String

Optional

Android端末にリモート通知が送信された場合、対象端末がオフラインのときに、最後のメッセージだけが送信されるようにするための任意の文字列になります。Android端末上では、任意の文字列で上書きされて表示されます。ただし、リモート通知は通知の順序の保証がありませんので、本当に最後のメッセージかというのは保証できません。また、collapseKey が指定されていない場合は、全て同じ文字列が指定されます。iOS端末の場合は、collapseKey が指定されていても無視されます。

style

String

Optional

Android端末にリモート通知が送信された場合、通知領域のスタイルとして使用されます。スタイルが指定されていない、またはスタイルが使用できない場合は、デフォルトのスタイルが指定されます。有効なスタイルは"normal"と"largeIcon"になります。Native / Unity SDK の場合、Android 2.3以上でのみ使用できます。詳細につきましては、こちらをご確認下さい。iOS端末の場合は、style が指定されていても無視されます。

iconUrl

String

Optional

Android端末にリモート通知が送信された場合、かつ style が指定されている場合、iconUrl は、Androidの通知領域に表示されるイメージを決定するために使用されます。iOS端末の場合は、iconUrl が指定されていても無視されます。

extras

Object

Optional

任意の1階層分の連想配列を Key/Value の形式で設定することができます。 例){ "foo" : "1", "bar" : "twenty one" }

User to User

User to User の通知送信方法について説明します。
User to User のリモート通知の送信は以下のように Client API と RESTful API でそれぞれ行うことができます。

  • ngCore Client API :
  • RESTful API : 3-legged の認証が必要になります。ゲームサーバーから以下の EndPoint に POST してください。
RESTful API に関しまして、こちらもご参照下さい。
POST /social/api/restful/v2/remote_notification/@app/@all/{recipientId}
POST /social/api/restful/v2/remote_notification/@app/@all/10258
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="b9a19f5ceac92a7b99b7", oauth_signature="yY0IRUStlDYw1qcyPuz8fsD%2BIrs%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798387", oauth_token="sp_client_id%3A58cee178e5ea60732d2b6fae0294da9d", oauth_version="1.0"

{
    "payload" : {
        "message": "Simon! Come join my quest.",
        "extras": {
            "foo": "1",
            "bar": "twenty one!"
        }
    }
}

201 Created
  • recipientId には、送信先の UserId を指定します。
  • payload には、送信内容を JSON 形式で指定します。

 

Game to User

Game to Single User のリモート通知の送信方法について説明します。
2-legged での OAuth Request (Consumer Request) を行なってください。具体的には以下のように POST します。Game to User には以下の 3 パターンでの送信が可能です。

RESTful API に関しまして、こちらもご参照下さい。
  • Game to Single User
    • 既にゲームを始めている単体のユーザーに対してのリモート通知の送信
    • 送信制限はありません。(以前は 4 時間に 1 度の送信制限がありましたが、現在はありません)
  • Game to Multiple User
    • 既にゲームを始めている複数のユーザーに対してのリモート通知の送信
    • 送信制限はありません。ただし、1 度の通信で送信できる件数の上限は 1000 件です。
  • Game to All User
    • 既にゲームを始めている全てのユーザーに対してのリモート通知の一斉送信
    • 1 時間に 1 度のみ送信できます。もし制限を超えた場合には、 429 Too Many Requests が返却されます。
Single User への送信: RESTful API 2-legged OAuth Request (Consumer Request)
POST /social/api/restful/v2/remote_notification/@app/@all/{recipientId}
POST /social/api/restful/v2/remote_notification/@app/@all/10258
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="5f5ae6a5688795cab25d", oauth_signature="tuLm4o%2FvwzdQK%2FuWAGii9ab3ZiI%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798463", oauth_version="1.0"

{
    "payload" : {
        "message": "Simon! Come join my quest.",
        "extras": {
            "foo": "1",
            "bar": "twenty one!"
        }
    }
}

201 Created

 

Multiple User (複数ユーザー)への送信: RESTful API 2-legged OAuth Request (Consumer Request)
POST /social/api/restful/v2/remote_notification/@app/@all
POST /social/api/restful/v2/remote_notification/@app/@all
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="5f5ae6a5688795cab25d", oauth_signature="tuLm4o%2FvwzdQK%2FuWAGii9ab3ZiI%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798463", oauth_version="1.0"
 
{
  "recipientId": ["10000", "10001", "10002"],
  "payload": {
    "message": "A New update is available.  Please download now!",
    "extras": {           
            "foo": "1",
            "bar": "twenty one!"
    }
  }
}
 
 
202 Accepted
Content-Type: application/json; charset=utf-8
 
{
   "published" : "2013-09-17T06:55:53",
   "payload" : {
      "extras" : {           
            "foo": "1",
            "bar": "twenty one!"
      },
      "message" : "A New update is available.  Please download now!"
   },
   "groupId" : "@all",
   "recipientId" : [
      "sb.mbga.jp:10000",
      "sb.mbga.jp:10001",
      "sb.mbga.jp:10002"
   ]
}

 

All User (全ユーザー) への送信: RESTful API 2-legged OAuth Request (Consumer Request)
POST /social/api/restful/v2/remote_notification/@app/@all
POST /social/api/restful/v2/remote_notification/@app/@all
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="5f5ae6a5688795cab25d", oauth_signature="tuLm4o%2FvwzdQK%2FuWAGii9ab3ZiI%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798463", oauth_version="1.0"

{
    "payload" : {
        "message": "Simon! Come join my quest.",
        "extras": {
            "foo": "1",
            "bar": "twenty one!"
        }
    }
}

202 Accepted
  • 制限事項
    • Game to All User の場合、1 時間に 1 度しかリモート通知ができません。もし制限を超えた場合には、 429 Too Many Requests が返却されます。

受信側の実装について

リモート通知の受信側の実装について説明します。

初期設定について

リモート通知を受け取るために、以下の様な初期設定をする必要があります。

  • ngCore Client API :

リモート通知の受信設定を有効にするために、Client API の setRemoteNotificationsEnabled() に true が設定されている必要があります。また、setRemoteNotification() はログイン後に呼び出さないと効果がありません。実装例は以下のようになります。

  • ngCore Client API :

この処理が実行されるまでにはリモート通知の受信機能が有効にならないため、アプリケーションの初回起動時の早いタイミングで行うことを推奨します。
また、上記フラグは、常にgetRemoteNotificationsEnabled() で取得することができます。

リモート通知機能の受信側には以下のケースが存在します。

  • アプリケーションがフォアグラウンドの時にリモート通知を受信した場合
  • アプリケーションがバックグラウンドの時にリモート通知を受信した場合
  • アプリケーションが起動していない時にリモート通知を受信した場合

以下にそれぞれのケースの実装方法について説明します。通知内容を取得しない場合は、実装する必要はありません。

ngCore Client API

アプリケーションがフォアグラウンドの場合

Device.NotificationEmitter.addListener() で MessageListener を登録することで、アプリケーションがフォアグラウンドの場合は、通知内容が直接 Listener に Emit されます。OS の通知領域には通知されません。

アプリケーションがバックグラウンドの場合

アプリケーションがバックグラウンドの場合にも、アプリがフォアグラウンドの場合のように MessageListener を登録する必要があります。バックグラウンドの場合、まず端末の通知領域にメッセージが表示されます。メッセージをタップすると、アプリケーションがフォアグラウンドになり、通知内容が Listener に Emit されます。

アプリケーションが起動していない場合

端末の通知領域にメッセージが表示されますので、メッセージをタップするとアプリケーションが起動します。起動時に、Device.NotificationEmitter.getPendingNotification() を実行して通知内容を取得してください。

通知領域のタップ時の挙動について

通知領域のメッセージをタップしたものの通知内容が addListener に登録された Listener または getPendingNotification() で取得できます。通知メッセージが最新の内容で上書きされている場合、最新の内容のみ Listener か getPendingNotification() で取得できます。その場合、古い内容は既に削除されていますので、取得できません。

リモート通知が送信される端末について

リモート通知が送信される端末は、以下の様なルールに基づいています。

  • Mobage へのログイン時に Mobage の UserId と端末の DeviceId (デバイストークン) が紐付き、端末へのリモート通知が送信可能な状態となります。
  • Mobage からログアウトすると、UserId と端末の DeviceId (デバイストークン) が紐付いた情報は削除され、端末へのリモート通知は送信不可能な状態となります。
  • 同じ UserId を用いて複数端末でログインしているような場合、最後にアプリを起動した端末にリモート通知が送られるようになります。ログアウト時の挙動は、Android 端末でログアウトした場合には Android 端末、iOS 端末でログアウトした場合には iOS 端末でリモート通知が送信されなくなります。

デバイストークンの登録状態確認機能について

リモート通知機能は、SDK がスマートフォン端末毎にデバイストークンを取得し、プラットフォーム側に登録することで該当のアプリを遊んでいる端末を特定し、リモート通知を送ることができます。デバイストークンの登録状態確認機能は、デバイストークンが既にプラットフォームに登録されているかどうかを確認することができます。デバイストークンは以下のケースで登録されたり削除されたりします。一度に登録されるデバイストークンの数は Android 端末、iOS 端末で それぞれ 1 端末分のみです。

  • デバイストークンがプラットフォームに登録されるタイミング
    • アプリへのログイン時に登録されます。
    • 既にログインしている場合、アプリ起動時に毎回登録されます。
  • デバイストークンがプラットフォームから削除されるタイミング
    • アプリからログアウトした場合に削除されます。

デバイストークンの登録状態確認機能の仕様

デバイストークンの登録状態確認機能の詳細は以下になります。

  • リクエスト形式
    GET  /social/api/restful/v2/remote_notification/@app/@all/{userId}/state
    
  • URI Template パラメータ
    • userId
      • userId パラメータは下記のいずれかの値を指定します。

        説明

        備考

        {userId}

        ユーザー ID

        string or array

        必須

  • 指定できるクエリパラメータ
    • fields

      Field Name

      Type

      Description

      userId

      String

      ユーザー ID

      enabled

      Boolean

      デバイストークンの登録有無(true/false)

      appId

      String

      アプリ ID

      updated

      Date

      デバイストークンの登録状態の最終更新日 (YYYY-MM-DDThh:mm:ss)

サンプル

1 User のデバイストークンの登録状態を確認する

  • リクエスト例
    GET   /social/api/restful/v2/remote_notification/@app/@all/10001/state?fields=appId,updated
    
  • レスポンス例
    200 OK
    Content-Type: application/json
    {
        "userId": "10001",
        "enabled": true,
        "appId": "120XXXXX",
        "updated": "2013-06-05T12:00:00"
    }
    
  • 1 User で指定した場合のレスポンス形式

    Field Name

    Type

    Description

    userId

    String

    ユーザー ID

    enabled

    Boolean

    デバイストークンの登録有無(true/false)

    appId

    String

    アプリ ID

    updated

    Date

    デバイストークンの登録状態の最終更新日 (YYYY-MM-DDThh:mm:ss)

複数 User のデバイストークンの登録状態を確認する

  • リクエスト例
    GET   /social/api/restful/v2/remote_notification/@app/@all/10001,10002,10003/state?fields=appId,updated
    
  • レスポンス例
    200 OK
    Content-Type: application/json
    {
        "entry": [
            { "userId": "10001", "enabled": true },
            { "userId": "10002", "enabled": false },
            { "userId": "10003", "enabled": true }
        ],
        "itemsPerPage": 3,
        "totalResults": 3,
        "startIndex": 1
    }
    
  • 複数 User 指定した場合のレスポンス形式

    Field Name

    Type

    Description

    entry

    Array

     

    entry[].userId

    string

    ユーザー ID

    entry[].enabled

    string

    デバイストークンの登録有無(true/false)

    entry[].appId

    string

    アプリ ID

    entry[].updated

    string

    デバイストークンの登録状態の最終更新日 (YYYY-MM-DDThh:mm:ss)

    totalResults

    Integer

    総エントリ数

    itemsPerPage

    Integer

    ページ当たりのエントリ数 (必ず件数と同じ値が返ります)

    startIndex

    Integer

    開始インデックス値 (常に 1 を返します)

    1000 件以上のリクエストを送っても常に 1000 件までのレスポンスが返ります
     

参考資料

  • RESTful API に関しまして、こちらもご参照下さい。

PREVIOUS

アイテムをプラットフォームに登録する方法

NEXT

リモート通知予約機能の使い方