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

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

• 参考：SDKを導入する

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

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

Installation procedure

1. FCM SDK を導入する

1. Install SDK
   Please refer to the following document for introduction.
   Set up a Firebase Cloud Messaging client app on Android

2. Testing Notifications with Notification Composer
   Send a notification message from Firebase's Notification Composer and check if you can receive the message.
   Send a notification message

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

In order for KARTE to send a notification transmission request to FCM, it is necessary to set up a service account on KARTE.
Set up a service account

3. KARTE SDK を導入する

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

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

Implementation procedure

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

To send push notifications from KARTE, you need an FCM token.
Therefore, implement the process of sending the FCM token from the application to KARTE.

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() を呼び出してください。

In addition, the KARTE SDK automatically sends the FCM token when the app starts to keep it up to date.

[参考]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以外のシステムを起点に送信されたプッシュ通知の場合の処理を書く
    }
  }
}

📘

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

If no deep link is specified or an invalid deep link is specified in the notification message, the screen transitions to the top screen of the application by default.

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

🚧

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

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

• Package visibility filtering on Android | Android Developers

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

またKARTEの管理画面上で設定した通知メッセージのurl等の値は、extractKarteAttributesを介して参照可能です。
その他の変数の取得についてはデフォルト変数とペイロード値の対応関係についてをご確認ください。

別途通知の表示をカスタマイズする場合は、通知の表示をカスタマイズするを御覧ください。

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

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

<!-- 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/drawable に android:resource で指定したものに対応する画像ファイルを配置します。

🚧

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

If notification_icon is not set, the launcher icon of the app will be inserted by default.
However, if the default launcher icon does not include an alpha channel, the icon will be grayed out.

回避するには、アルファチャンネルを利用して描かれたアイコンを 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) を指定して通知を行います。

Operation check

Finally, send a test message to confirm that the installation has been performed correctly.

For details, see the following document.
Send a test message

trouble shooting

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