こんにちは。内藤です。

Monacaバックエンドに新しく個別Push通知機能が搭載されました。
この機能の使い方について、簡単に紹介します。

個別Push通知機能

個別Push通知機能では、特定のユーザー（またはグループ、デバイス）だけに通知を送ることが可能になります。たとえば、会員登録しているアプリであれば、２０代女性会員だけに通知するとか、３０代男性会員だけに通知するということが可能になる、ということですね。

Monacaバックエンドによる個別Push通知機能には、大きく３パターンの呼び出し方があります。

(パターンA) ユーザの絞り込み条件を指定
Monacaバックエンドのユーザのプロパティ値として任意の値を保存しておくと、それらの値をプッシュ通知のユーザ絞り込み条件に用いることができます。この場合、条件に合致するユーザに対してのみ、プッシュ通知が行われます。

(パターンB) ユーザIDを指定(複数指定可)
Monacaバックエンドの「ユーザID」を外部サーバにあらかじめ記憶しておきます。そのユーザIDのリストを指定すると、特定のユーザに対してのみ、プッシュ通知が行われます。

(パターンC) Monacaフレームワークが生成した端末IDを指定(複数指定可)
Monacaフレームワークはアプリ初回起動時にユニークな端末IDを自動生成します。この端末IDを外部サーバへ送り、独自のユーザ情報と紐付けておくことにより、特定の端末に対してのみ、プッシュ通知を行うことができます。

この記事では、パターンCついて取り上げてみます。

プロジェクトの作成と設定

まずは、Monacaの最小のプロジェクトを新しく作成します。

次に、通知機能が使えるように、以下の設定をしていきます。（これは個別Push通知でなくても、Monacaバックエンドから通知機能を使う場合には設定が必要です）
IDEの左サイドの上部にある「雲」アイコンをクリックして、「バックエンドを利用する」をクリックします。選択肢が出てくるので、「Monacaバックエンドを新規作成する」を選び新規バックエンドを作成するか、「既存のMonacaバックエンドを使用する」を選びます。

【2014/8/15追記】
現在のMonaca Backendでは、jQueryプラグインを有効化する必要はなくなりました。
以下のjQueryの有効化の記述は飛ばして、先へ進んでください。

jQueryの有効化を求めるダイアログが出てきますので、「はい」を押してプラグイン設定画面を開き、jQueryプラグインを有効化して「保存する」を押します。なお、すでにjQueryやZepto.jsを利用中のプロジェクトでは、jQueryプラグインを有効化する必要はありません。

再度、左サイトの上部にある「雲」アイコンをクリックして、次に「歯車」アイコンをクリックし、バックエンド設定を選択します。

次に、マネジメントAPIタブを開きます。
「有効にする」ボタンを押し、マネジメントAPIを有効にします。マネジメントAPIとは、HTTPS経由でJSON形式のリクエストを送るだけでご自分のサーバからMonacaバックエンドを操作できる便利なWeb APIです。個別Push通知機能を利用するためには、マネジメントAPIの有効化が必須となります。

マネジメントAPIのエンドポイントURLをテキストエディタ等に記録しておきます。

APIを呼び出すためにはまず、認証に用いるマネジメントAPIキーの発行が必要です。呼び出しを許可するクライアントマシンのIPアドレスを記述し、「作成する」ボタンを押すと、キーが発行されます。

作成されたキーをテキストエディタ等に記録しておきます。

ここまでで、IDE上での準備が完了しました。

アプリの実装

次に、アプリの方の実装に入ります。

今回は個別Push通知の基本的な実装の確認が目的なので、単に通知が来たら通知により
指定されたWebページを表示するだけの簡単なアプリを作ることにします。

この場合、index.htmlのヘッダ部分のscriptタグ内に以下を記述します。

monaca.cloud.Push.setHandler(function(data){ 
    monaca.invokeBrowser(data.url);  // Open url in default browser
});

上記は、Push通知を受け取るハンドラーで、受け取ったJSONのうち、urlで指定されたWebページをブラウザにより開きます。

また、個別Push通知用にデバイスIDを取得する必要があるので、コンソールログ（および画面）にデバイスIDを表示する機能を記述しておきます。

monaca.getDeviceId( function(deviceId) { 
    console.log( "deviceId = " + deviceId );
    $('#deviceId').text(deviceId);
});

今回は、上記で得られるデバイスIDを用いて、サーバー側からデバイスID指定でのPush通知を送ります。このため、まずはアプリを一度起動し、コンソールログにデバイスIDが表示されることを確認して下さい。表示されたデバイスIDは、コピーして、テキストエディタ等に記録しておきます。

なお、実際のアプリ開発では、デバイスIDはAjaxなどであらかじめサーバー側に送っておき、Push通知時にその値を利用することになります。

さて、これでアプリの実装が完成しました。

サーバー側の準備

それでは、実際にマネジメントAPIを呼び出し、個別Push通知を行ってみましょう。ここで利用するAPI名は、Push.sendです。

今回は簡単のため、MonacaバックエンドのマネジメントAPIを直接ターミナルから呼び出してみます。

このAPIを使う場合、Push通知プロジェクトIDが必要になります。IDEからバックエンドの「歯車」アイコンを押して、プッシュ通知タブを開き、ページ一番下の「プッシュ通知プロジェクトID」をテキストエディタ等にコピーしておきます。

呼び出すコマンドは以下のようになります。

iOSデバッガー宛ての場合

curl https://cloud.monaca.mobi/manage/json-rpc/************************ --data '{"jsonrpc": "2.0", "id": 1, "method": "Push.send" , "params": { "pushProjectId": "【プッシュ通知プロジェクトID】", "platform": "ios", "target": "debugger", "buildType": "debug",  "message": "manage sample"  , "json" : "{ \"url\" : \"http://www.google.co.jp\" }", "deviceIdList": [ "【デバイスID】" ] } }' --header 'X-Monaca-Backend-Management-API-Key: ************'

Androidデバッガー宛ての場合

curl https://cloud.monaca.mobi/manage/json-rpc/************************ --data '{"jsonrpc": "2.0", "id": 1, "method": "Push.send" , "params": { "pushProjectId": "【プッシュ通知プロジェクトID】", "platform": "android", "target": "debugger", "buildType": "debug", "title": "hello", "message": "manage sample"  , "json" : "{ \"url\" : \"http://www.google.co.jp\" }", "deviceIdList": [ "【デバイスID】" ] } }' --header 'X-Monaca-Backend-Management-API-Key: ************'

マネジメントAPIのリクエストボディはJSON形式で指定しますが「"jsonrpc": "2.0", "id": 1」の部分は固定ですので、重要なのは「"method": ... , "params": ...」の部分となります。****になっている部分は、マネジメントAPIのエンドポイントURLとキーの値を記述して下さい。

マネジメントAPIの呼び出しに成功すると

{"jsonrpc":"2.0","id":1,"result":{"queueIdList":["【キューのID】"]}}

といったレスポンスが返ってきます。

存在しないデバイスIDを指定すると、以下のようなエラーが返ってきます。

{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"Internal error: \"Failed to add to push queue: There are no target devices.\""}}

エラーが生じた場合は、paramsの指定に問題がないかチェックしてみてください。

デバイス側にPush通知が届くと、通知エリアに通知が表示されます。

それをタップすると、アプリがフォアグラウンドに立ち上がり、ハンドラー関数が実行されます。

以上のように、個別Push通知機能を簡単に実現することが出来ました。
ぜひ、この記事を参考に、個別Push通知機能の実装を試してみて下さい。

他のパターンについて

今回は、最初に述べた３つのパターンのうち、パターンCを取り上げました。パターンA、パターンBの場合も設定等は同じになりますが、サーバ側から呼び出すパラメータ(params)が変わります。

パターンAの場合

  userQuery : string
  userQueryBindParams : Array

userQueryにMonaQL形式のクエリ文字列を記述します。userQueryBindParamsに、userQuery内のプレースホルダ「?」に埋め込まれる値のリストを記述します。

パターンBの場合

  userOidList : string[]

userOidListに、ユーザIDのリストを記述します。

パターンCの場合（今回の記事）

  deviceIdList : string[]

deviceIdListに、デバイスIDのリストを記述します。

ビルドアプリ宛ての場合

デバッガーではなく、ビルドアプリの場合には、IDE上からプッシュ通知の設定がもう少し必要になります。詳しくは
http://docs.monaca.mobi/ja/manual/backend/push_config/gcm/#android-app-push-settings
http://docs.monaca.mobi/ja/manual/backend/push_config/apns/#ios-app-push-settings
を参照して下さい。