サーバー構築不要!スマートフォンアプリ向けの新クラウド

トップ >ドキュメント >プッシュ通知(Kotlin):基本的な使い方

プッシュ通知(Kotlin)

基本的な使い方

概要

このページでは、プッシュ通知の基本的な使い方について説明していきます。

設定の流れ

ニフクラ mobile backendのプッシュ通知機能は、
Googleが提供しているFirebase Cloud Messaging(以下、FCM)と連携することで、通知の配信を行っています。

Androidアプリでプッシュ通知を受信するまでの設定は以下のような流れとなっています。

  1. google-services.jsonとFirebase秘密鍵の設定
  2. ニフクラ mobile backendでの設定
  3. アプリでの設定

google-services.jsonとFirebase秘密鍵の設定

FCM対応したプッシュ通知を送信する場合、google-services.jsonをアプリに配置してただくのと、Firebaseプロジェクトの秘密鍵をmobile backendにアップロードしていただく必要があります。
以下のドキュメントを参考に、google-services.jsonとFirebase秘密鍵の設定を行ってください。

ニフクラ mobile backendでの設定

次に、ニフクラ mobile backendでプッシュ通知の設定を行います。

プッシュ通知の有効化

アプリ設定から、左メニューのプッシュ通知の項目を選択してください。
プッシュ通知の許可設定を行う部分があるので、「許可する」に変更して変更を保存してください。

プッシュ通知の有効化

以上の設定で、ニフクラ mobile backendとFirebaseを連携することができました。
ここからは、アプリ側でプッシュ通知を受信するための実装を行っていきます。

アプリでの設定

アプリ側では、以下のような設定を行います。

  • google-services.jsonの配置
  • 必要なライブラリのインストール
  • AndroidManifestの編集
  • 端末をニフクラ mobile backendに登録する処理の実装

なお、ニフクラ mobile backendのKotlin SDKは
インストールと初期化が済んでいるものとして説明しますので、
未実施の場合はクイックスタートをご覧ください。

google-services.jsonの配置

もし、google-services.jsonとFirebase秘密鍵の設定を行った際、google-services.jsonをまだアプリに配置していない場合は、ここで配置してください。

ライブラリのインストール

プッシュ通知をmobile backendで送受信するためには、以下のライブラリが必要です。

  • Google Play Services SDK
    • プッシュ通知を受信するために必要です
  • Support Library
    • 通知を表示させるために必要です

これらのライブラリは以下の手順でインストールします

  • SDK Managerで必要なライブラリをインストールする
    • Android Support Library
    • Android Support Repository(Android Studioの場合)
    • Google Play Services
    • プロジェクトのbuild.gradleファイルを編集する
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.0.0"
        classpath "com.google.gms:google-services:4.3.4"
    }
}

  • appフォルダ内のbuild.gradleファイルのpluginsに追加する
plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'com.google.gms.google-services' //追加
}

  • デフォルトで書かれているdependenciesに追加(ない場合は、追記してください)
dependencies {
  implementation 'androidx.appcompat:appcompat:1.3.1'
  implementation 'com.google.code.gson:gson:2.3.1'
  api files('libs/NCMB.jar')
  implementation platform('com.google.firebase:firebase-bom:28.4.0') //追加
  implementation 'com.google.firebase:firebase-messaging-ktx' //追加
  implementation 'com.google.firebase:firebase-analytics-ktx' //追加
  implementation 'com.google.android.gms:play-services-base:17.6.0' //追加

詳細な手順については、Googleが提供しているドキュメントをご覧ください

Android Manifestの編集

AndroidManifest.xmlにて、利用するパーミッションの宣言とレシーバー、サービスの登録を行います。

まずは、applicationタグの直前に、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" />

次に、applicationタグの要素としてserviceの登録を行います。

  • serviceの登録
 <service
     android:name="com.nifcloud.mbaas.core.NCMBFirebaseMessagingService"
     android:exported="false">
     <intent-filter>
         <action android:name="com.google.firebase.MESSAGING_EVENT"/>
     </intent-filter>
 </service>

  • meta-dataの設定

次に、meta-dataの設定もapplicationタグの要素として追加します。 プッシュ通知タップ時に起動するActivityの設定のみ必須ですが、channelの設定は任意です。

プッシュ通知タップ時に起動するActivityの設定は必須の設定となります。

<!-- プッシュ通知タップ時に起動するActivityの設定 ※必須の設定 -->
<meta-data android:name="openPushStartActivity" android:value=".MainActivity"/>
<!-- プッシュ通知のchannel idの設定 default(com.nifcloud.mbaas.push.channel)-->
<meta-data android:name="ChannelId" android:value="YOUR_CHANNEL_ID"/>
<!-- プッシュ通知のchannel名の設定 default(NCMB Push Channel) -->
<meta-data android:name="ChannelName" android:value="YOUR_CHANNEL_NAME"/>
<!-- プッシュ通知のchannel 説明の設定 default(com.nifcloud.mbaas.push.channel) -->
<meta-data android:name="ChannelDescription" android:value="YOUR_CHANNEL_DESCRIPTION"/>

配信端末情報の登録

MainActivity.ktのonCreateに書く場合は以下のようになります。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // APIキーの設定とSDK初期化
    NCMB.initialize(this.applicationContext, "APP_KEY", "CLIENT_KEY")
    // 配信端末の登録
    NCMB.initializePush(this.applicationContext)
    setContentView(R.layout.activity_main)
}

以上でアプリ側での設定は完了です。
アプリをAndroid端末で実行し、端末情報がデータストアに登録されるか確認してください。

プッシュ通知をアプリから送信する

管理画面からだけでなく、アプリからも他の端末へプッシュ通知を送信することができます。
immediateDeliveryFlagを設定すると即時配信設定になります。

import com.nifcloud.mbaas.core.NCMBPush

<省略>

fun sendPush() {
    val push = NCMBPush()
    push.title = "test title"
    push.message = "send push!"
    push.immediateDeliveryFlag = true
    //Androidに送る場合
    push.isSendToAndroid = true
    //iOSに送る場合
    //push.isSendToIOS = true
    try {
        push.save()
    }
    catch (error:NCMBException){
        throw error
    }
}

プッシュ通知の配信期限

プッシュ通知の配信期限を指定することができます。

  • パターン1 (文字列で配信期限指定)

時間指定("x hour") や 日数指定("x day")で配信期限を設定できます。

    push.deliveryExpirationTime = "3 day"
    push.immediateDeliveryFlag = true

  • パターン2 (Dateのインスタンスを作成し配信期限指定)
    var date = Date()
    var df = SimpleDateFormat("yyyy-MM-dd HH:mm:ss")
    try {
        date = df.parse("2022-04-01 15:00:00")
    } catch (e: ParseException) {
        e.printStackTrace()
    }
    push.deliveryExpirationDate = date
    push.immediateDeliveryFlag = true

プッシュ通知のスケジューリング

プッシュ通知の配信時刻を指定することができます。
ご利用方法にあった指定方法をご活用ください。
タイムゾーンを指定しない場合はシステムのタイムゾーンが指定されます。

  • パターン1 (現在時刻からの時刻指定)
    var date = Date()
    date.time = date.time + 60 * 60 * 3 * 1000
    push.deliveryTime = date

  • パターン2 (Dateのインスタンスを作成し日付指定)
    var date = Date()
    var df = SimpleDateFormat("yyyy-MM-dd HH:mm:ss")
    try {
        date = df.parse("2022-04-01 15:00:00")
    } catch (e: ParseException) {
        e.printStackTrace()
    }
    push.deliveryTime = date

  • パターン3 (文字列で日付指定)
    push.setDeliveryTimeString("2022-04-01 13:00:00")
    push.deliveryTime = date

また、以下のようにTimeZoneも設定可能です。

    val timeZone: TimeZone  = TimeZone.getTimeZone("Etc/UTC")
    push.setDeliveryTimeString("2022-04-01 13:00:00", timeZone)

管理画面からプッシュ通知を配信する

ここからは、管理画面からプッシュ通知を配信する方法を説明します。

プッシュ通知を送信する

管理画面左側メニューのプッシュ通知をクリックし、プッシュ通知の画面を開きます。

新しいプッシュ通知ボタンをクリックすると、プッシュ通知作成画面が表示されます。
このページで新たなプッシュ通知を作成できます。タイトル、メッセージ、JSONデータを記入してください。
※プッシュ通知の設定でタイトルとメッセージを入力しなかった場合は、端末にプッシュ通知が表示されません。
(上記の場合でも、ダイアログ表示やJSONデータの取得は可能です。)
※iOS宛プッシュ通知の設定は、iOS8未満は合計256バイトまで、iOS8以降は合計2Kバイトまでがサポート対象となります。
新規プッシュ通知作成

配信日時の指定を行います。以下の例では、作成されたプッシュ通知が即時に配信される設定になっています。

プッシュ通知送信日時を指定する場合は、配信日時の欄で日時を選択し、希望する日時を指定してください。

配信期限の指定では電源が切れているなどの事情により通知を受け取れなかった端末への再送信期間を設定できます。デフォルトの設定では再送信できる期間が10日間となっていますが1~28日間、1~24時間の間で、期間を指定できます。

また、配信期限を日時で指定する場合は、日時の指定画面が表示されます。

次に、配信を行うプラットフォームを選択してください。AndroidとiOSの両方にプッシュ通知を送信することも可能です。

Androidを選択した場合は、以下のようにアクション設定と、ダイアログ表示の設定画面が表示されます。
Android独自設定

iOSを選択した場合は、以下のようなiOS端末へのプッシュ通知を行うための設定画面が開きます。
iOS独自設定

絞り込みを行いたい場合には、配信端末を「installationクラスから絞り込み」とし、条件を設定してください。
絞り込み配信設定

最後に「プッシュ通知を作成する」ボタンをクリックすると、プッシュ通知が作成されます。

テンプレートを使用する

プッシュ通知作成画面上部にあるテンプレート機能では、プッシュ通知作成時に入力・設定した内容を保存しておくことができます。
毎回同一内容のプッシュ通知を作成している場合、テンプレート機能を使用することで、プッシュ作成時の手間を省くことができます。

タイトルやメッセージを入力した後、「テンプレートとして保存する」ボタンをクリックしてください。
プッシュテンプレート保存ボタン

すると、以下のようなポップアップが表示されます。
プッシュテンプレート保存
テンプレート名を入力し、「保存する」ボタンをクリックすると、テンプレートとして保存されます。

保存されたテンプレートはプルダウンから選択可能です。
プッシュテンプレート選択時

  • 注意
    • 1アプリにつき20テンプレートの保存が可能です。
    • 配信日時、配信期限、パーミッションの内容は、テンプレートとして保存されません。

プッシュ通知の配信ステータスについて

プッシュ通知一覧の画面では、プッシュ通知のタイトルの右側に、配信ステータスが表示されます。

こちらのステータスが「未配信」、「配信済み」、「配信中」以外だった場合、プッシュ通知の配信が失敗した端末が存在しています。
配信ステータスの詳細は こちらの「プッシュ通知のステータスについて」項目にてご参考ください。
※以下の画像では、「配信済み(一部エラー)」と表示されている部分がステータスに該当します。
プッシュステータス

配信ステータスが「配信済み(一部エラー)」の場合は、該当のプッシュ通知をクリックすると表示される、画面右側のプッシュ通知詳細画面最下部の「配信エラー内容」にエラーの詳細が出力されていますので、ご確認ください。

また、配信ステータスが「配信エラー」になる場合の主な理由と対策は、以下の通りです。

  • iOSプッシュ通知証明書、またはAndroidプッシュ通知設定ファイルを設定していないのに、両方のOSを対象にしてプッシュ通知を登録
    • 配信対象はデフォルトでiOS/Androidの両方なので、iOSプッシュ通知証明書と、Androidプッシュ通知設定ファイルのいずれかを設定していないとエラーになります。
    • また、iOSプッシュ通知証明書に不具合があったり、有効期限が切れていた場合も、エラーとなります。iOSプッシュ通知証明書の有効期限切れについては、こちらもご参考ください。

※配信エラーでは無いにも関わらずプッシュ通知が届かない場合は、省電力モードの設定が影響している場合がございます。端末の設定をご確認ください。

過去のプッシュ通知データについて

プッシュ通知配信履歴自動バックアップ機能によってバックアップされたデータは、「過去のプッシュ通知データ一覧」画面にてダウンロード/削除が可能です。

過去のプッシュ通知データ

過去のプッシュ通知データ一覧

プッシュ通知配信履歴自動バックアップ機能

バックアップ機能概要

プッシュ通知の配信に伴い、配信済みのプッシュ通知オブジェクトは内部データベースに累積いたします。
こちらはプッシュ通知の登録ごとに作成されますので、個通のプッシュ通知を多用されるなど、プッシュ通知登録数が多い場合につきましては、オブジェクトの容量肥大が考えられます。
容量が肥大しますと、プッシュ通知の配信パフォーマンス低下やストレージ容量の逼迫に繋がります。
上記現象を防ぐため、プッシュ通知オブジェクトが約100万件(※)を超過した場合、超過分の配信済みのプッシュ通知オブジェクト(開封率データ含む)は自動でバックアップされます。
※レコード件数ではなく、データサイズ(非公開情報)での制限を設けているため、約100万件の制限と表記しております。

  • バックアップデータ(CSV)は管理画面よりダウンロード/削除が可能です。
  • バックアップデータは、プッシュ通知データの場合は配信時刻(JST)の年月ごとにファイルが分けられ、 push_YYYYMM.csv という形式のファイル名となります。開封率データの場合は登録日時(JST)の年月ごとにファイルが分けられ、 push_open_state_YYYYMM.csv という形式のファイル名となります。例としてプッシュ通知の配信時刻が 2022年3月15日09:00(JST)だった場合、そのデータは push_202203.csv というファイル名のファイルに出力されます。
  • バックアップデータは、API経由でのアクセスは行えません。 (該当プッシュ通知データへのアクセスもしくは開封通知登録を行った場合、E404001エラーが返却されます)

以上より、配信済みのプッシュ通知オブジェクトへAPIアクセスする処理を組み込まれる場合は、自動バックアップによりエラーが発生する可能性があることを考慮した実装をお願いいたします。

過去のプッシュ通知データに関する注意事項
  • バックアップデータの容量も、ストレージ容量にカウントされます。
  • バックアップデータはエクスポート機能のエクスポート対象外です。
  • バックアップデータ内のデータには、APIアクセスできません。
  • 自動バックアップは内部で随時行われています(実施タイミングについては非公開)ので、以下の点にご注意ください。
    • 自動バックアップが行われている際に削除されたプッシュ通知データについては、バックアップデータ(CSV)に存在する可能性がございます。何卒ご了承ください。
    • 一度ダウンロードされたバックアップデータであっても、中身が更新されていることがございます。削除する際には必ず最新版のバックアップデータをダウンロードしておくことを推奨いたします。一度削除してしまったバックアップデータの復元は不可能ですので、ご注意ください。(有償での復元対応も致しかねます。)

プッシュ通知でJSONデータを取得する

プッシュ通知にはJSON形式で任意のデータを含めることができるので、
プッシュ通知を受信した時に、そのデータを受け取って処理を行うことができます。

ペイロードの内容について

Android端末へのプッシュ通知では、以下のペイロードが受信されます。

パラメータ名 説明 データ型
com.nifcloud.mbaas.PushId プッシュ通知ID 文字列
com.nifcloud.mbaas.Data ユーザー設定値 オブジェクト
title タイトル 文字列
message メッセージ 文字列
action アクション 文字列
com.nifcloud.mbaas.Channel チャネル 文字列
com.nifcloud.mbaas.Dialog ダイアログ 1(固定)
com.nifcloud.mbaas.RichUrl リッチプッシュ通知用URL 文字列
JSONデータのパラメータに使用可能な文字の制限

JSONデータのパラメータには、以下の文字が使用できません。

  1. ダブルクォーテーション「"」
  2. ドット「.」
  3. 先頭にドル記号「$」

お探しの内容が見つからなかった場合はユーザーコミュニティ もご活用ください。(回答保証はいたしかねます)
なお、 Expertプラン以上のお客様はテクニカルサポートにてご質問を承らせて頂きます。

推奨画面サイズ1024×768px以上

ページの先頭へ