ヘッダーをスキップ

Oracle® Mobile Application Framework Oracle Mobile Application Frameworkでのモバイル・アプリケーションの開発 2.1.1.0.0 E64867-01 |
| 目次

前 | 次 |

# 24 通知の有効化と使用方法

この章では、MAFアプリケーションでローカル通知を表示する方法と、プッシュ通知メッセージを登録および処理する方法を説明します。

この章の内容は次のとおりです。

- 第24.1項「通知の概要」

- 第24.2項「プッシュ通知の有効化」

- 第24.3項「ローカル通知の管理」

## 24.1 通知の概要

通知は、モバイル・アプリケーションの標準のユーザー・インタフェースの外部のエンド・ユーザーに提供されるシグナルです。これらの通知は、アプリケーションの状態とユーザー設定に応じて、アラート・メッセージやバナーとして表示できます。通知は、視覚的に表示するか、音声として、またはその両方として提示できます。

次に、2つの主なタイプの通知を示します。

- プッシュ通知は、サーバーなどの外部ソースからモバイル・デバイス上のアプリケーションに送信されます。通知を受信したエンド・ユーザーは、アプリケーションを起動するか、その通知を無視でき、無視した場合はアプリケーションがアクティブになりません。

  図24-1は、iOSデバイスにおけるプッシュ通知アラートを示しています。

  図24-1 プッシュ通知

  プッシュ通知を受信するには、アプリケーションを通知サービスに登録する必要があります。登録が成功すると、通知サービスからアプリケーションにトークンが発行されます。アプリケーションでは、このトークンを(リモート・サーバー上の)プロバイダと共有します。これにより、プロバイダから、通知サービスを通じてアプリケーションに通知を送信できるようになります。MAFでは、アプリケーションによって提供された登録構成を使用して、そのアプリケーションのかわりに登録を行います(第24.2項「プッシュ通知の有効化」を参照)。登録は、MAFアプリケーションが起動するたびに、トークンの有効性を保証する目的で行われます。登録が成功すると、MAFでは、プラットフォーム固有の通知サービスから取得したトークンをプロバイダと共有します。iOSの場合、この通知サービスはApple Push Notification Service (APNs)です。Google Cloud Messaging (GCM) for Androidでは、Androidデバイスにインストールされたアプリケーション用の通知サービスが提供されます。

  MAFアプリケーションでは、その状態にかかわらずプッシュ通知を受信できます。これらのメッセージは、アプリケーションがフォアグラウンドで実行されていなくても表示される場合があり、その表示形式はMAFアプリケーションの状態とユーザー設定によって異なります。表24-1では、iOSオペレーティング・システムで、MAFアプリケーションの状態に応じて、どのようにプッシュ通知が処理されるかを説明します。

  表24-1 iOSデバイスにおけるプッシュ通知の処理

  状態 | アクション
  --- | ---
  MAFアプリケーションはインストールされているが、実行されていない。 | 通知メッセージが登録済の通知スタイル(なし、バナーまたはアラート)で表示されます。ユーザーがメッセージをタップ(バナー・スタイルの通知の場合)するか、アクション・ボタンをタッチ(メッセージがアラートとして表示される場合)すると、MAFアプリケーションが起動し、アプリケーション通知ハンドラが呼び出されます。
  MAFアプリケーションがバックグラウンドで実行されている。 | 通知メッセージが登録済の通知スタイル(なし、バナーまたはアラート)で表示されます。ユーザーがメッセージをタップ(バナー・スタイルの通知の場合)するか、アクション・ボタンをタッチ(メッセージがアラートとして表示される場合)すると、MAFアプリケーションが起動し、アプリケーション通知ハンドラが呼び出されます。
  MAFアプリケーションがフォアグラウンドで実行されている。 | 通知メッセージは表示されません。アプリケーション通知ハンドラが呼び出されます。

  iOSおよびAndroidプラットフォームでは、アプリケーションがフォアグラウンドで実行されていない場合、そのアプリケーションに関連付けられているすべてのプッシュ通知メッセージが、iOS Notification CenterやAndroidデバイス上の通知ドロワーなど、特定の場所に格納されます。

- ローカル通知は、モバイル・アプリケーション内で発生し、同じアプリケーションによって受信されます。通知は、モバイル・デバイス・プラットフォームによってサポートされる標準メカニズム(バナーやサウンドなど)を通じてエンド・ユーザーに配信されます。

  MAFが提供するローカル通知抽象化APIを使用して、通知を即時に起動するか、将来の日時に通知をスケジュールするようにアプリケーションを構成できます。また、通知の繰返しパターン(毎日や毎週など)を設定したり、スケジュールされた通知をキャンセルできます。

  iOSとAndroidプラットフォームの両方で、MAFアプリケーションがフォアグラウンドで実行されている場合、通知はエンド・ユーザーとの対話なしでアプリケーションに直接配信されます。アプリケーションがバックグラウンドで実行されているか、まったく実行されていない場合、通知はエンド・ユーザーが通知をタップした後でアプリケーションに配信されます。

## 24.2 プッシュ通知の有効化

次のタスクを実行することで、プッシュ通知を有効にできます。

1. 図24-2に示すとおりに、`maf-application.xml`概要エディタの「デバイス・アクセス」ページで「プッシュ通知」を選択し、MAFアプリケーションでプッシュ通知を受信できるようにします。

   注意: デフォルトでは、MAFアプリケーションはプッシュ通知を許可しません(また、いずれのデバイス・タイプのデバイス・アクセスも許可しません)。

   図24-2 プッシュ通知の許可

2. アプリケーション・コントローラ・プロジェクトで、アプリケーション・ライフサイクル・イベント・リスナー(ALCL)・クラスを登録します。詳細は、第3.3項「アプリケーション機能の表示プロパティの設定」および第11章「MAFアプリケーションでのライフサイクル・リスナーの使用方法」を参照してください。

3. ALCLに`oracle.adfmf.application.PushNotificationConfig`インタフェースを実装します。このインタフェースにより、プッシュ通知サービスに正常に登録するために必要な構成が提供されます。

   `PushNotificationConfig`インタフェースの`getNotificationStyle`および`getSourceAuthorizationId`メソッドをオーバーライドおよび実装します。`getNotificationStyle`メソッドにより、アプリケーションを登録する通知スタイルを指定できます。`getSourceAuthorizationId`メソッドを使用すると、MAFアプリケーションへのメッセージの送信を許可されたアカウントのGoogleプロジェクト番号を入力できます。詳細は、Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスを参照してください。

4. アプリケーション・コントローラ・プロジェクトで、プッシュ通知イベントを処理するプッシュ通知イベント・リスナー・クラス(`NativePushNotificationListener`など)を作成します。このクラスには、イベント・リスナーを定義する`oracle.adfmf.framework.event.EventListener`インタフェースを実装する必要があります。`oracle.adfmf.framework.event.EventListener`インタフェースの詳細は、Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスを参照してください。

   通知イベントに登録して通知イベントを受信するには、`onOpen`、`onMessage`および`onError`メソッドをオーバーライドおよび実装します。プッシュ通知サービスへの登録が成功すると、MAFでは、アプリケーション開発者がプロバイダと共有する必要がある登録トークンを使用して、`onOpen`メソッドをコールします。通知サービスへの登録時にエラーが発生した場合は、プッシュ通知サービスにより戻される`AdfException`としてカプセル化されたエラーを使用して、`onError`メソッドが呼び出されます。

   MAFでは、アプリケーションが通知を受信するたびに、通知ペイロードを使用して`onMessage(Event e)`メソッドをコールします。`Event`オブジェクトを使用すると、通知ペイロードおよびアプリケーションの状態に関する有用な情報を取得できます。通知ペイロードを取得するには、`Event.getPayload`メソッドを使用します。通知時のアプリケーションの状態を取得するには、`Event.getApplicationState`メソッドを使用します。詳細は、``Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスのEventクラスに関する項を参照してください。

5. ALCLクラスの`start`メソッド内にある、ネイティブ・プッシュ通知イベントのソースを表す`EventSource`オブジェクトを取得します。

       EventSource evtSource = EventSourceFactory.getEventSource(
               EventSourceFactory.NATIVE_PUSH_NOTIFICATION_REMOTE_EVENT_SOURCE_NAME);

6. プッシュ通知イベント・リスナー・クラスのオブジェクトを作成し、イベント・ソースに追加します。

       evtSource.addListener(new NativePushNotificationListener());

MAFサンプル・アプリケーション(PushDemoおよびPushServer)によって、プッシュ通知の処理方法を示します。これらのサンプル・アプリケーションは、開発コンピュータ上の`jdev_install``/jdeveloper/jdev/extensions/oracle.maf/Samples`ディレクトリの`PublicSamples.zipファイル`内にあります。

### 24.2.1 プッシュ通知ペイロードに関する必知事項

MAFでは、JSON形式のペイロードに対して、次のキーを尊重します。

- `alert`: 通知プロンプトに表示されるテキスト・メッセージ。

- `sound`: 通知を受信したときに再生されるサウンド。

- `badge`: iOSのアプリケーション・アイコンに表示する番号。

  注意: Androidでは、ペイロードをキーと値のペアを持つJSONオブジェクトにすることができます。GCMサーバーではアプリケーションに値を送信する前に、文字列以外の値を文字列に変換するため、値は常に文字列化されます。APNでは値のタイプが保持されるため、これは当てはまりません。詳細は、『Google Cloud Messaging』の「Implementing GCM Server」で、dataメッセージ・パラメータの説明を参照してください。このドキュメントは、`http://developer.android.com/index.html`にあるAndroid開発者のWebサイトまたはAndroid SDKドキュメントから入手できます。

## 24.3 ローカル通知の管理

次のものを使用して、ローカル通知を管理できます。

- MAFによって提供されるJava API (第24.3.1項「Javaを使用したローカル通知の管理方法」を参照)。

- MAFによって提供されるJavaScript API (第24.3.2項「JavaScriptを使用したローカル通知の管理方法」を参照)。

- アプリケーション設計時にすべてのMAFアプリケーションで使用可能なDeviceFeaturesデータ・コントロールのメソッド(第24.3.3項「DeviceFeaturesデータ・コントロールを使用したローカル通知の管理方法」を参照)。

LocalNotificationDemoというMAFサンプル・アプリケーションは、ローカル通知のスケジュールおよび処理方法を示します。このサンプル・アプリケーションは、開発コンピュータ上の``jdev_install`/jdeveloper/jdev/extensions/oracle.maf/Samples`ディレクトリ内の`PublicSamples.zip`ファイル内にあります。

### 24.3.1 Javaを使用したローカル通知の管理方法

`oracle.adfmf.framework.api.AdfmfContainerUtilities`クラスの次のメソッドを使用して、ローカル通知をスケジュールできます。

- `addLocalNotification(MafNativeLocalNotificationOptions options)`。このメソッドは、スケジュールされる通知のIDを表す`String`を戻します。

  Javaコードでは、このメソッドは次のような方法で使用します。

      try {
        // Configure local notification
        MafNativeLocalNotificationOptions options =
                      new MafNativeLocalNotificationOptions();

        options.setTitle("some title text");
        options.setAlert("some alert text");

        // Set the date in UTC
        options.setDate(LocalDateTime.now(Clock.systemUTC()).plusSeconds(5));
        // Set the notification to repeat every minute
        options.setRepeat(MafNativeLocalNotificationOptions.RepeatInterval.MINUTELY);
        // Set the application badge to be '1' everytime notification is triggered
        options.setBadge(1);
        // Play the default system sound when notification triggers
        options.setSound(MafNativeLocalNotificationOptions.SYSTEM_DEFAULT_SOUND);
        // Vibrate using default system vibration motion when notification triggers
        options.setVibration(
                   MafNativeLocalNotificationOptions.SYSTEM_DEFAULT_VIBRATION);

        // Add custom payload that is to be delivered through the local notification
        HashMap<String,Object> payload = new HashMap<String, Object>();

        payload.put("somenumber", 1);
        payload.put("somestring", "value2");
        payload.put("someboolean", true);
        options.setPayload(payload);

        // Schedule local notification
        String notificationID = AdfmfContainerUtilities.
                                addLocalNotification(options);
        System.out.println("Notification added successfully. ID is "+notificationID);
      }
      catch(Exception e) {
        System.err.println("There was a problem adding notification");
      }

  通知オプションがアプリケーションの動作に与える影響は、ターゲット・プラットフォームによって異なります。詳細は、第24.3.5項「ローカル通知オプションとアプリケーションの動作に関する必知事項」を参照してください。

- `cancelLocalNotification(String notificationId)`。このメソッドは、正常に取り消された通知のIDを表す`String`を戻します。

  Javaコードで、次のような方法でこのメソッドを使用します。

      try {
        String cancelledNotificationId = AdfmfContainerUtilities.
               cancelLocalNotification("a83b696d-53e7-4242-ab4d-4a771d8d178f");
        System.out.println("Notification successfully canceled");
      }
      catch(AdfException e) {
        System.err.println("There was a problem canceling notification");
      }

詳細は、Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスを参照してください。

### 24.3.2 JavaScriptを使用したローカル通知の管理方法

MAFでは、`adf.mf.api.localnotification`ネームスペースでJavaScript APIを使用してローカル通知を管理できます。次のメソッドを使用できます。

- 次のように定義される`add`。

      /**
      * Schedule a local notification
      *
      * @param {Object} options - notification options
      * @param {string} options.title - notification title
      * @param {string} options.alert - notification alert
      * @param {Date} options.date - date at which notification is to be triggered
      * @param {Number} options.badge - application icon is to be badged by this
      *                                 number when notification is triggered
      * @param {string} options.sound - set it to 'SYSTEM_DEFAULT' to play the
      *                                 default system sound upon a notification
      * @param {string} options.vibration - set it to 'SYSTEM_DEFAULT' for default
      *                                     system vibration upon a notification
      * @param {Object} options.payload - custom payload to be sent via notification
      * @param {successCallback} scb - success callback
      * @param {errorCallback} ecb - error callback
      */
      adf.mf.api.localnotification.add(options,scb,ecb);

      {Object} options : json representing notification options
              {
                 "title" : String,  // notification title (Android only)
                 "alert" : String,  // notification alert text
                 "date" : Date,  // date-time at which notification
                                 // should be fired (UTC time zone)
                 "repeat" : String,  // either 'minutely', 'hourly', 'daily',
                                     // 'weekly', 'monthly', or 'yearly'
                 "badge" : Number,  // badge application icon on iOS with this number
                 "sound" : "SYSTEM_DEFAULT",  // if set, the default system
                                              // sound is played
                 "vibration" : String,  // if set to "SYSTEM_DEFAULT", the default
                                        // vibration is enabled upon
                                        // an incoming notification (Android only)
                 "payload" : Object,  // custom JSON data to be passed
                                      // through the notification
              }

      /**
      * Success Callback
      *
      * @param {Object} request - request
      * @param {Object} response - response
      * @param {string} response.id - id of the scheduled notification
      */
      function scb(request, response) {}

      /**
      * Error Callback
      *
      * @param {Object} request - request
      * @param {Object} response - response
      */
       function fcb(request, response) {}

  通知オプションがアプリケーションの動作に及ぼす影響は、ターゲット・プラットフォームによって異なります。詳細は、第24.3.5項「ローカル通知のオプションとアプリケーションの動作に関する必知事項」を参照してください。

- 次のように定義される`cancel`。

      /**
      * Cancel a scheduled local notification
      *
      * @param {string} notificationId - id of the scheduled notification
      *                                  that needs to be canceled
      * @param {successCallback} scb - success callback
      * @param {errorCallback} ecb - error callback
      */
      adf.mf.api.localnotification.cancel(notificationId, scb, ecb);

      {var} notificationId : id of notification that is to be canceled.

      /**
      * Success Callback
      *
      * @callback successCallback
      * @param {Object} request - request
      * @param {Object} response - response
      * @param {string} response.id - id of the notification
      */

      /**
      * Error Callback
      *
      * @callback errorCallback
      * @param {Object} request - request
      * @param {Object} response - response
      */

  詳細は、Oracle Fusion Middleware Oracle Mobile Application Framework JSDocリファレンスを参照してください。

### 24.3.3 DeviceFeaturesデータ・コントロールを使用したローカル通知の管理方法

図24-3に示すDeviceFeaturesデータ・コントロールの`addLocalNotification`および`cancelLocalNotification`メソッドを使用してローカル通知をスケジュールおよび取消しできます。

図24-3 DeviceFeaturesデータ・コントロールのメソッド

DeviceFeaturesデータ・コントロールの詳細は、第14.11項「DeviceFeaturesデータ・コントロールの使用方法」を参照してください。

### 24.3.4 ローカル通知の処理方法

ローカル通知の処理を有効にするために、MAFは次のものを提供しています。

- ローカル通知イベントのリスナーを作成するために実装する必要がある`EventListener`インタフェース。通知がトリガーされると、`onMessage`メソッドは通知詳細を指定してコールされます。

      NativeLocalNotificationListener implements EventListener {
         @Override
         public void onOpen(String id) {
         }

         @Override
         public void onMessage(Event event) {
               //Application state at the time of this notification
               int appState = event.getApplicationState();

               //Get local notification event details
               if (event instanceof NativeLocalNotificationEvent) {
               NativeLocalNotificationEvent localNotificationEvent =
                                         (NativeLocalNotificationEvent) event;
               HashMap<String, Object> notification =
                                         localNotificationEvent.getPayloadObject();

               // do something with the notification payload, such as navigate
               // to an application feature, call a web service, and so on
         }

         @Override
         public void onError(AdfException error) {
         }
      }

- `oracle.adfmf.framework.event.Event`を拡張する`NativeLocalNotificationEvent`クラス。

ローカル通知に関連するイベントを受け取るには、次のように、登録された`ApplicationLifeCycleEventListener#start`メソッドにリスナーを追加する必要があります。

例24-1 ローカル通知リスナーの追加

    EventSource evtSource = EventSourceFactory.getEventSource(
                EventSourceFactory.NATIVE_LOCAL_NOTIFICATION_EVENT_SOURCE_NAME);
    evtSource.addListener(new NativeLocalNotificationListener());

詳細は、Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスを参照してください。

### 24.3.5 ローカル通知オプションとアプリケーションの動作に関する必知事項

表24-2に、ローカル通知オプションをリストし、各オプションに対する特定の値の設定と不適切な設定がMAFアプリケーションの通知動作に与える影響を説明します。

表24-2 ローカル通知オプション

オプション | 値 | iOSでの動作 | Androidでの動作
--- | --- | --- | ---
`title` | 次のいずれかです。 `null` 未指定 | NA脚注 1 | 通知センターの通知タイトルは空白で表示されます。
`alert` | 次のいずれかです。 `null` 未指定 | アプリケーションがバックグラウンドで実行されているか、または一切実行されていない場合、通知は通知センターで表示されることもキューに入れられることもありません。 アプリケーションがフォアグラウンドで実行されている場合、通知の詳細はアプリケーションのローカル通知リスナーに直接渡されます。 | 通知はタイトルのあるバナーとして表示されますが、アラート・テキストはありません。
`date` | 次のいずれかです。 `null` 未指定 過去の時刻または日付 | 通知は即時にトリガーされます。 | 通知は即時トリガーされます。
`repeat` | 次のいずれかです。 `null` 未指定 | 通知は繰り返されません。 | 通知は繰り返されません。
`badge` | 次のいずれかです。 `null` 未指定 負の数値 | 通知はアプリケーション・アイコンのバッジを設定しません。 既存のバッジが維持されます。 | NA 脚注2
`badge` | 0 | 既存のバッジがアプリケーション・アイコンから削除されます。 | NA 脚注3
`sound` | 次のいずれかです。 `SYSTEM_DEFAULT_SOUND`以外 未指定 | 通知はサウンドを再生しません。 | サウンドは再生されません。
`vibration` | `SYSTEM_DEFAULT_VIBRATION`以外 | NA 脚注4 | 通知はモバイル・デバイスのバイブレーションをトリガーしません。

脚注1 タイトルは常にアプリケーション名であるため、通知は影響を受けません。

脚注2 アプリケーション・バッジ設定の概念はありません。設定は無視されます。

脚注3 アプリケーション・バッジ設定の概念はありません。設定は無視されます。

脚注4 バイブレーションは制御できません。設定は無視されます。ただし、通知の受信時にデフォルトのシステム・サウンドを再生することを指定した場合、また、エンド・ユーザーがモバイル・デバイスの「着信時のバイブレーション」設定を有効にした場合、デバイスは通知の受信時にバイブレーションも適用します。