プッシュ通知(Android)
基本的な使い方(SDK v2版)
Contents |
概要
このページでは、プッシュ通知の基本的な使い方について説明していきます。
こちらはAndroid SDK v2のドキュメントになります。
設定の流れ
ニフクラ mobile backendのプッシュ通知機能は、
Googleが提供しているGoogle Cloud Messaging(以下、GCM)と連携することで、通知の配信を行っています。
※ Android SDK v2のプッシュ送信はFirebase Cloud Messaging(以下、FCM)ではなく、Google Cloud Messaging(以下、GCM)を使用しています。
※ 2019年5月29日以降 Google Cloud Messaging が終了するため、このページでお伝えしている配信端末を新規登録する方法ができなくなると考えられます。GCM対応のプッシュ通知を使用しているお客様は移行対応とv3のプッシュ通知の基本的な使い方の手順を参考に、FCM対応したプッシュ通知への移行をお願いいたします。
※ ドキュメント内の設定でFirebaseプロジェクトを作成しますが、機能としてはGCMを用いています。
Androidアプリでプッシュ通知を受信するまでの設定は以下のような流れとなっています。
- Firebaseプロジェクトの作成とAPIキーの取得
- ニフクラ mobile backendでの設定
- アプリでの設定
Firebaseプロジェクトの作成とAPIキーの取得
まず、ニフクラ mobile backendと連携させるためのAPIキーを取得する必要があります。
以下のドキュメントを参考に、Firebaseプロジェクトの作成とAPIキーの取得を行ってください。
ニフクラ mobile backendでの設定
次に、ニフクラ mobile backendでプッシュ通知の設定を行います。
プッシュ通知の有効化
アプリ設定から、左メニューのプッシュ通知の項目を選択してください。
プッシュ通知の許可設定を行う部分があるので、「許可する」に変更して変更を保存してください。
Firebaseプロジェクトで取得したAPIキーの追加
こちらの内容は現在設定できません
Firebaseプロジェクトで取得したAPIキー(サーバーキー)を設定し、変更を保存してください。
以上の設定で、ニフクラ mobile backendとFirebaseを連携することができました。
ここからは、アプリ側でプッシュ通知を受信するための実装を行っていきます。
アプリでの設定
アプリ側では、以下のような設定を行います。
- 必要なライブラリのインストール
- AndroidManifestの編集
- 端末をニフクラ mobile backendに登録する処理の実装
なお、ニフクラ mobile backendのAndroid SDKは
インストールと初期化が済んでいるものとして説明しますので、
未実施の場合はクイックスタートをご覧ください。
ライブラリのインストール
プッシュ通知をmobile backendで送受信するためには、以下のライブラリが必要です。
- Google Play Services SDK
- プッシュ通知を受信するために必要です
- Support Library
- 通知を表示させるために必要です
これらのライブラリは以下の手順でインストールします
- SDK Managerで必要なライブラリをインストールする
- Android Support Library
- Android Support Repository(Android Studioの場合)
- Google Play Services
- アプリケーションモジュール(appフォルダ内)のbuild.gradleファイルを編集する
- repositoriesを追加
repositories {
maven {
url 'https://maven.google.com'
}
}
- デフォルトで書かれているdependenciesに追加(ない場合は、追記してください)
dependencies {
compile fileTree(dir: 'libs', include: ['*.jar'])
compile 'com.android.support:appcompat-v7:26.0.2'
compile 'com.google.android.gms:play-services-gcm:11.0.0'
api files('libs/NCMB.jar')
}
詳細な手順については、Googleが提供しているドキュメントをご覧ください
Android Manifestの編集
AndroidManifest.xmlにて、利用するパーミッションの宣言と
レシーバー、サービスの登録を行います。
まずは、manifestタグの要素として以下のパーミッションの利用を宣言してください。
android.permission.VIBRATEが不要な場合は削除しても構いません。
パッケージ名は、各自のプロジェクトのものに適宜変更してください。
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<permission android:name="パッケージ名.permission.C2D_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="パッケージ名.permission.C2D_MESSAGE" />
次に、applicationタグの要素としてreceiverとserviceの登録を行います。
- receiverの登録
- パッケージ名は適宜変更してください
<receiver
android:name="com.nifty.cloud.mb.core.NCMBGcmReceiver"
android:exported="true"
android:permission="com.google.android.c2dm.permission.SEND">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE"/>
<category android:name="パッケージ名"/>
</intent-filter>
</receiver>
- serviceの登録
<service
android:name="com.nifty.cloud.mb.core.NCMBGcmListenerService"
android:exported="false">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE"/>
</intent-filter>
</service>
- meta-dataの設定
v2より以下の項目がAndroidManifestで設定可能となりました。
プッシュ通知タップ時に起動するActivityの設定は必須の設定となります。
<!-- プッシュ通知タップ時に起動するActivityの設定 -->
<meta-data android:name="openPushStartActivity" android:value=".MainActivity"/>
<!-- 通知エリアに表示されるアイコンの設定 -->
<meta-data android:name="smallIcon" android:resource="@drawable/icon"/>
<!-- 通知エリアに表示されるアイコンカラーの設定 -->
<meta-data android:name="smallIconColor" android:value="@color/カラー名"/>
<!-- 通知エリアにプッシュ通知を複数表示する設定 0:最新のみ表示 , 1:複数表示 -->
<meta-data android:name="notificationOverlap" android:value="0"/>
<!-- カスタムダイアログプッシュを利用する場合のみ背景画像の設定 -->
<meta-data android:name="dialogPushBackgroundImage" android:resource="@drawable/balloon"/>
配信端末情報の登録
GCMでは、プッシュ通知の配信端末を一意に識別するRegistration IDを利用し、
各端末への配信を行っています。
そのため、GCMからRegistration IDを取得したあとで、
データストアに配信端末情報として登録する必要があります。
以下の端末情報の登録処理を、プッシュ通知を受信するアクティビティのonCreateメソッド内に記入してください。
「YOUR_SENDER_ID」の部分には、Firebaseプロジェクト作成時に発行されたSender ID(送信者ID)を設定します。
//端末情報を扱うNCMBInstallationのインスタンスを作成
final NCMBInstallation installation = NCMBInstallation.getCurrentInstallation();
//GCMからRegistrationIdを取得
installation.getRegistrationIdInBackground("YOUR_SENDER_ID", new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e == null) {
//端末情報をデータストアに登録
installation.saveInBackground(new DoneCallback() {
@Override
public void done(NCMBException saveErr) {
if (saveErr != null) {
//端末情報登録時のエラー処理
}
}
});
} else {
//RegistrationId取得時のエラー処理
}
}
});
アプリの再インストールを考慮する場合
アプリが再インストールされた場合などに、
前回のインストール時に保存された端末情報がデータスト上に残ったままの場合が考えられます。
その場合、端末情報の登録でRegistration IDの重複エラーが発生するため、
エラーが発生したときの処理を実装する必要があります。
final NCMBInstallation installation = NCMBInstallation.getCurrentInstallation();
//GCMからRegistrationIdを取得しinstallationに設定する
installation.getRegistrationIdInBackground("YOUR_SENDER_ID", new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e == null) {
installation.saveInBackground(new DoneCallback() {
@Override
public void done(NCMBException e) {
if(e == null){
//保存成功
}else if(NCMBException.DUPLICATE_VALUE.equals(e.getCode())){
//保存失敗 : registrationID重複
updateInstallation(installation);
}else {
//保存失敗 : その他
}
}
});
} else {
//ID取得失敗
}
}
});
端末情報の更新を行うupdateInstallationメソッドでは
同じRegistration IDの端末情報を取得して、更新を行っています。
public static void updateInstallation(final NCMBInstallation installation) {
//installationクラスを検索するクエリの作成
NCMBQuery<NCMBInstallation> query = NCMBInstallation.getQuery();
//同じRegistration IDをdeviceTokenフィールドに持つ端末情報を検索する
query.whereEqualTo("deviceToken", installation.getDeviceToken());
//データストアの検索を実行
query.findInBackground(new FindCallback<NCMBInstallation>() {
@Override
public void done(List<NCMBInstallation> results, NCMBException e) {
//検索された端末情報のobjectIdを設定
try {
installation.setObjectId(results.get(0).getObjectId());
} catch (NCMBException searchErr) {
}
//端末情報を更新する
installation.saveInBackground();
}
});
}
installationが削除された時を考慮する場合
以下の例のように、何らかの理由により有効な installation が削除されてしまった場合、通常の実装では installation の再登録は行われず、該当の端末へはプッシュ通知を配信することができなくなってしまいます。
- 管理者の操作ミスによる削除
- コントロールパネル上の操作ミスなど
- 管理者が意図しない操作による削除
- mobile backend ではアプリがアンインストールされた端末情報(installation)の自動削除機能において、配信依頼時のレスポンスとして返却される「無効なレジスタレーションID」を削除しています。 「有効なレジスタレーションID」であっても、GCMの判断で返却された場合は、mobile backend 側では削除対象となります。
そのため、 installation を再度登録するには、以下の処理を追加実装する必要があります。
final NCMBInstallation installation = NCMBInstallation.getCurrentInstallation();
//GCMからRegistrationIdを取得しinstallationに設定する
installation.getRegistrationIdInBackground("YOUR_SENDER_ID", new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e == null) {
installation.saveInBackground(new DoneCallback() {
@Override
public void done(NCMBException e) {
if(e == null){
//保存成功
}else if(NCMBException.DATA_NOT_FOUND.equals(e.getCode())){
//保存失敗 : 端末情報の該当データがない
reRegistInstallation(installation);
}else {
//保存失敗 : その他
}
}
});
} else {
//ID取得失敗
}
}
});
installation が削除された場合(端末情報の該当データがmoble backend 上に存在しない場合)は、以下のように installation を再作成します。
public static void reRegistInstallation(final NCMBInstallation installation) {
//objectIdと作成日・更新日のみ削除し、installationが再生成されるようにする
installation.setObjectId(null);
installation.remove("createDate");
installation.remove("updateDate");
//データストアの端末情報の再登録を実行
installation.saveInBackground(new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e == null) {
//登録成功
} else {
//登録失敗
}
}
});
}
以上でアプリ側での設定は完了です。
アプリをAndroid端末で実行し、端末情報がデータストアに登録されるか確認してください。
プッシュ通知をアプリから送信する
管理画面だけでなく、アプリからも他の端末へプッシュ通知を送信することができます。
deliveryTime未設定の場合は即時配信設定になります。
プッシュ通知の設定を行う
- iOS端末へのプッシュ通知を行う場合は、バッジの増加フラグや、着信音の設定などが可能です。
private void sendPush() throws JSONException {
NCMBPush push = new NCMBPush();
push.setBadgeIncrementFlag(true); //バッジ数増加フラグ(iOS端末のみ設定可能)設定
push.setSound("default"); //音楽ファイル(iOS端末のみ設定可能)設定
push.setCategory("CATEGORY001"); //カテゴリ設定
push.setTarget(new JSONArray("[ios]")); //ターゲット(ios, android のどちらか、もしくは両方の値の配列)を設定
push.setMessage("send push!"); //メッセージを設定
push.sendInBackground(new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e != null) {
// エラー処理
} else {
// プッシュ通知登録後の処理
}
}
});
}
- Android端末へのプッシュ通知を行う場合は、タイトルや起動画面、ダイアログプッシュ通知の有効フラグを設定できます。
private void sendPush() throws JSONException {
NCMBPush push = new NCMBPush();
push.setAction("com.sample.pushsample.RECEIVE_PUSH"); //アクション(Android端末のみ設定可能)設定
push.setTitle("test title"); //タイトルを設定
push.setMessage("send push!"); //メッセージを設定
push.setTarget(new JSONArray("[android]")); //ターゲット(ios, android のどちらか、もしくは両方の値の配列)を設定
push.setDialog(true); //ダイアログ表示
push.sendInBackground(new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e != null) {
// エラー処理
} else {
// プッシュ通知登録後の操作
}
}
});
}
プッシュ通知のスケジューリング
プッシュ通知の配信時刻を指定することができます。
Date date = new Date();
date.setTime(date.getTime() + 60 * 60 * 3 * 1000);//3時間後に設定
NCMBPush push = new NCMBPush();
push.setMessage("test Push Notification"); //メッセージ設定
push.setDeliveryTime(date); //配信時刻設定
push.sendInBackground();
配信端末の絞り込み
setSearchConditionメソッドでクエリを設定することにより、
プッシュ通知を配信する端末を絞り込むことができます。
端末情報をmobile backendに登録する時に任意の値を設定可能ですので、
installationクラスの既存フィールド以外でも絞り込み条件を設定することができます。
以下はsetChannelsメソッドを使用して、channelsフィールドに絞込み条件として["Ch1"]を設定する例です。
private void setChannel(){
NCMBInstallation installation = NCMBInstallation.getCurrentInstallation();
JSONArray channels = new JSONArray();
channels.put("Ch1");
installation.setChannels(channels);
installation.saveInBackground(new DoneCallback() {
@Override
public void done(NCMBException e) {
if (e != null) {
//エラー発生時の処理
} else {
//成功時の処理
}
}
});
}
channelsに"Ch1"が設定されている端末に絞り込んだプッシュ通知は、以下のように配信できます。
private void testPushWithSearchCondition(){
NCMBPush push = new NCMBPush();
NCMBQuery<NCMBInstallation> query = new NCMBQuery<>("installation");
query.whereEqualTo("channels", "Ch1");
push.setSearchCondition(query); //検索条件設定
push.setMessage("test SearchCondition"); //メッセージを設定
push.setTarget(new JSONArray("[android]"));
push.sendInBackground();
}
管理画面からプッシュ通知を配信する
ここからは、管理画面からプッシュ通知を配信する方法を説明します。
プッシュ通知を送信する
管理画面左側メニューのプッシュ通知をクリックし、プッシュ通知の画面を開きます。
新しいプッシュ通知ボタンをクリックすると、プッシュ通知作成画面が表示されます。
このページで新たなプッシュ通知を作成できます。タイトル、メッセージ、JSONデータを記入してください。
※プッシュ通知の設定でメッセージとタイトルを入力しなかった場合は、端末にプッシュ通知が表示されません。
(上記の場合でも、ダイアログ表示やJSONデータの取得は可能です。)
※iOS宛プッシュ通知の設定は、iOS8未満は合計256バイトまで、iOS8以降は合計2Kバイトまでがサポート対象となります。
配信日時の指定を行います。以下の例では、作成されたプッシュ通知が即時に配信される設定になっています。
プッシュ通知送信日時を指定する場合は、配信日時の欄で日時を選択し、希望する日時を指定してください。
配信期限の指定では電源が切れているなどの事情により通知を受け取れなかった端末への再送信期間を設定できます。デフォルトの設定では再送信できる期間が10日間となっていますが1~28日間、1~24時間の間で、期間を指定できます。
また、配信期限を日時で指定する場合は、日時の指定画面が表示されます。
次に、配信を行うプラットフォームを選択してください。AndroidとiOSの両方にプッシュ通知を送信することも可能です。
Androidを選択した場合は、以下のようにアクション設定と、ダイアログ表示の設定画面が表示されます。
iOSを選択した場合は、以下のようなiOS端末へのプッシュ通知を行うための設定画面が開きます。
最後に「プッシュ通知を作成する」ボタンをクリックすると、プッシュ通知が作成されます。
テンプレートを使用する
プッシュ通知作成画面上部にあるテンプレート機能では、プッシュ通知作成時に入力・設定した内容を保存しておくことができます。
毎回同一内容のプッシュ通知を作成している場合、テンプレート機能を使用することで、プッシュ作成時の手間を省くことができます。
タイトルやメッセージを入力した後、「テンプレートとして保存する」ボタンをクリックしてください。
すると、以下のようなポップアップが表示されます。
テンプレート名を入力し、「保存する」ボタンをクリックすると、テンプレートとして保存されます。
保存されたテンプレートはプルダウンから選択可能です。
- 注意
- 1アプリにつき20テンプレートの保存が可能です。
- 配信日時、配信期限、パーミッションの内容は、テンプレートとして保存されません。
配信エラーとなった場合
プッシュ通知一覧の画面で、配信状況が配信エラーになる場合がございます。
エラーが発生する場合の主な理由と対策は、以下の通りです。
- iOSプッシュ通知証明書またはAPIキーを設定していないのに、両方のOSを対象にしてプッシュ通知を登録
- 配信対象はデフォルトでiOS/Androidの両方なので、iOSプッシュ通知証明書とAPIキーのどちらかを設定していないとエラーになります。
- また、iOSプッシュ通知証明書に不具合があったり、有効期限が切れていた場合も、エラーとなります。iOSプッシュ通知証明書の有効期限切れについては、こちらもご参考ください。
※配信エラーでは無いにも関わらずプッシュ通知が届かない場合は、省電力モードの設定が影響している場合がございます。端末の設定をご確認ください。
プッシュ通知でJSONデータを取得する
プッシュ通知にはJSON形式で任意のデータを含めることができるので、
プッシュ通知を受信した時に、そのデータを受け取って処理を行うことができます。
カスタムサービスを用意
SDKが用意しているNCMBGcmListenerServiceを継承して、
カスタムサービスを作成してください。
AndroidManifest.xmlのサービスを定義している部分を書き換えてください。
<service
android:name="com.nifty.cloud.mb.core.CustomGcmListenerService"
android:exported="false">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE"/>
</intent-filter>
</service>
JSONデータの取得を実装
CustomGcmListenerServiceクラスでonMessageReceivedメソッドをオーバーライドして、
プッシュ通知に含まれているJSONデータを取得します。
ペイロードからJSONデータを取得する場合は、
com.nifty.DataキーからJSONオブジェクトを作成してください。
@Override
public void onMessageReceived(String from, Bundle data) {
//ペイロードデータの取得
if (data.containsKey("com.nifty.Data")) {
try {
JSONObject json = new JSONObject(data.getString("com.nifty.Data"));
Iterator keys = json.keys();
while (keys.hasNext()) {
String key = (String) keys.next();
String value = json.getString(key);
Log.d("tag", "key: " + key);
Log.d("tag", "value: " + value);
}
} catch (JSONException e) {
//エラー処理
}
}
//デフォルトの通知が必要なければコメントアウトする
super.onMessageReceived(from, data);
}
ペイロードの内容について
Android端末へのプッシュ通知では、以下のペイロードが受信されます。
v2よりパラメータ名に変更がありますのでご注意ください
パラメータ名 | 説明 | データ型 |
---|---|---|
com.nifty.PushId | プッシュ通知ID | 文字列 |
com.nifty.Data | ユーザー設定値 | オブジェクト |
title | タイトル | 文字列 |
message | メッセージ | 文字列 |
action | アクション | 文字列 |
com.nifty.Channel | チャネル | 文字列 |
com.nifty.Dialog | ダイアログ | 1(固定) |
com.nifty.RichUrl | リッチプッシュ通知用URL | 文字列 |
JSONデータのパラメータに使用可能な文字の制限
JSONデータのパラメータには、以下の文字が使用できません。
- ダブルクォーテーション「"」
- ドット「.」
- 先頭にドル記号「$」
お探しの内容が見つからなかった場合はユーザーコミュニティ
もご活用ください。(回答保証はいたしかねます)
なお、 Expertプラン以上のお客様はテクニカルサポートにてご質問を承らせて頂きます。
推奨画面サイズ1024×768px以上