プッシュ通知を受信する

プッシュ通知を受信したい場合は、リモート通知機能を利用することで実現可能です。

リモート通知機能は、KARTE SDKの導入及びnotifications モジュールを導入することで利用可能です。

なお KARTE ではプッシュ通知の送信に、Firebase Cloud Messaging(以下FCM)を利用しています。
そのためFCM経由でプッシュ通知を送信するために各種設定を行う必要があります。

また受信側アプリケーションでも FCM SDK の導入が必要となります。

導入手順

1. FCM SDK を導入する

  1. SDKを導入する
    導入に関しては、下記ドキュメントをご覧ください。
    Set up a Firebase Cloud Messaging client app on Android

  2. Notification Composer で通知のテストを行う
    Firebase の Notification Composer から通知メッセージを送信し、メッセージが受信できるか確認してください。
    Send a notification message

2. サービスアカウントの設定を行う

KARTEからFCMに対して通知の送信リクエストを行うために、KARTE側にサービスアカウントの設定を行う必要があります。
サービスアカウントを設定する

3. KARTE SDK を導入する

アプリの build.gradle (app) を任意のエディタで開き、dependencies ブロックに notifications モジュールを追加します。

dependencies {
  implementation 'io.karte.android:notifications:2.+'
}

実装手順

1. FCMトークンを送信する

KARTE からプッシュ通知を送信するためには、FCMトークンが必要となります。
そのためアプリケーションからKARTEにFCMトークンを送信する処理を実装します。

FirebaseMessagingService クラスを継承したクラスを作成し、onNewToken() メソッド内にトークンの送信処理を実装します。

import com.google.firebase.messaging.FirebaseMessagingService
import io.karte.android.KarteApp
import io.karte.android.notifications.registerFCMToken

class MyFirebaseMessagingService : FirebaseMessagingService() {
  override fun onNewToken(token: String) {
    super.onNewToken(token)
    KarteApp.registerFCMToken(token)
    
    // Notificationsクラスのメソッドを直接呼ぶことも可能です。
    // Notifications.registerFCMToken(token)
  }
}
import com.google.firebase.messaging.FirebaseMessagingService;
import io.karte.android.notifications.Notifications;

public class MyFirebaseMessagingService extends FirebaseMessagingService {
  @Override
  public void onNewToken(String token) {
    super.onNewToken(token)
    Notifications.registerFCMToken(token)
  }
}

📘

古い Firebase Cloud Messaging SDK を利用している場合

v17.1.0 未満の Firebase Cloud Messaging SDK を利用してる場合は、代わりに FirebaseInstanceIdService を使い onTokenRefresh()trackFcmToken() を呼び出してください。

また、KARTE SDK では FCM トークンを最新に保つために、アプリ起動時に自動で送信します。

[参考]FCM登録トークンや、アプリPUSH通知許可設定がKARTEに送信されるタイミング

2. 通知の表示処理を実装する

受信したメッセージのハンドリング

※プッシュ通知のタップ時に、任意の画面に遷移させる等の処理をさせたい場合には必須の実装です。

受信した通知を通知ドロワーに表示するために、FirebaseMessagingService クラスを継承したクラスの onMessageReceived() メソッド内に、下記の実装を行う必要があります。
またこの実装をすることで通知タップ時に自動で message_click イベントが発生するようになります。

class MyFirebaseMessagingService : FirebaseMessagingService() {
  override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // handled の値が `true` の場合は KARTE を起点に送信されたプッシュ通知
    // `false` の場合は KARTE 以外を起点に送信されたプッシュ通知
    val handled = MessageHandler.handleMessage(this, remoteMessage)
      if (!handled) {
      // KARTE以外のシステムを起点に送信されたプッシュ通知の場合の処理を書く
    }
  }
}
public class MyFirebaseMessagingService extends FirebaseMessagingService {
  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
    // handled の値が `true` の場合は KARTE を起点に送信されたプッシュ通知
    // `false` の場合は KARTE 以外を起点に送信されたプッシュ通知
    boolean handled = MessageHandler.handleMessage(this, remoteMessage);
    if (!handled) {
      // KARTE以外のシステムを起点に送信されたプッシュ通知の場合の処理を書く
    }
  }
}

📘

通知タップ時のデフォルトの遷移先について

通知メッセージにディープリンクの指定がされていないもしくは不正なディープリンクが指定されていた場合は、デフォルトでアプリのTOP画面に遷移します。

デフォルトの遷移先を変更したい場合は、 MessageHandler.handleMessage() の第3引数に Intent 指定することで変更することが可能です。

🚧

Android 11以降における通知タップ時の外部アプリ起動について

targetSdkVersion 30以上のアプリの場合、Android 11以降の端末ではmanifestでの宣言無しには外部アプリのActivity情報を取得できないため、通知タップ時に直接外部アプリを起動できず、デフォルトの遷移を行うケースがあります。

notifications: 2.8.0以降では、デフォルトでhttp/httpsのスキーマに関して起動できるよう、manifestに宣言を追加しています。
notifications: 2.8.0未満を使用する場合や、http/https以外のスキーマの外部アプリを起動したい場合は、AndroidManifest.xmlqueriesタグを宣言するか、一度アプリを起動してから外部アプリを起動する必要があります。

またKARTEの管理画面上で設定した通知メッセージのurl等の値は、extractKarteAttributesを介して参照可能です。
別途通知の表示をカスタマイズする場合は、通知の表示をカスタマイズするを御覧ください。

通知アイコン・アイコンカラーの設定

通知のアイコン・ラージアイコン・カスタムカラーを設定するには、AndroidManifest.xmlapplication タグ内に下記を追加します。

<!-- setSmallIcon に対応 -->
<meta-data
    android:name="io.karte.android.Tracker.notification_icon"
    android:resource="@drawable/ic_notification" />

<!-- setLargeIcon に対応 -->
<meta-data
    android:name="io.karte.android.Tracker.notification_large_icon"
    android:resource="@drawable/ic_notification_large" />

<!-- setColor に対応 -->
<meta-data
    android:name="io.karte.android.Tracker.notification_color"
    android:resource="@color/colorAccent" />

次に src/drawableandroid:resource で指定したものに対応する画像ファイルを配置します。

🚧

通知アイコンのデフォルト画像について

notification_icon の設定を行わなかった場合、デフォルトではアプリのランチャーアイコンが挿入されます。
ただし、デフォルトのランチャーアイコンにアルファチャンネルが含まれない場合は、アイコンがグレーになってしまいます。

回避するには、アルファチャンネルを利用して描かれたアイコンを io.karte.android.Tracker.notification_icon に指定してもらうことで解決できます。

通知チャンネルの作成

通知テンプレート内でチャンネルの指定を行う場合は、あらかじめチャンネルを作成しておく必要があります。

val channel = NotificationChannel("my_channel", "通知テストチャンネル", NotificationManager.IMPORTANCE_DEFAULT)
channel.description = "テストの説明です"
channel.setShowBadge(true)

// create or update the Notification channel
val notificationManager = applicationContext.getSystemService(Context.NOTIFICATION_SERVICE)
if (notificationManager is NotificationManager) {
  notificationManager.createNotificationChannel(channel)
}
NotificationChannel channel = new NotificationChannel("my_channel", "通知テストチャンネル", NotificationManager.IMPORTANCE_DEFAULT);
channel.setDescription("テストの説明です");
channel.setShowBadge(true);

// create or update the Notification channel
NotificationManager notificationManager = (NotificationManager)context.getSystemService(Context.NOTIFICATION_SERVICE);
notificationManager.createNotificationChannel(channel);

📘

指定されたチャンネルが存在しない場合

通知テンプレートにて指定されたチャンネルが存在しない場合は、SDK 内で作成したデフォルトチャンネル (krt_default_channel) を指定して通知を行います。

動作確認

最後に正しく導入が行われているか確認を行うためにテストメッセージを送信して確認を行います。

詳細については、下記ドキュメントをご覧ください。
テストメッセージを送信する

トラブルシューティング

プッシュ通知に問題がある場合は、KARTE for Appプッシュ通知で問題が発生した時のチェックリストを参考にしてください。


What’s Next

通知の表示を独自にカスタマイズしたい場合は、以下のドキュメントをご覧ください。