ヘッダーをスキップ

Oracle Enterprise Pack for Eclipse Oracle Mobile Application Framework (OEPE Edition)でのモバイル・アプリケーションの開発 リリース2.1.2 E64870-01 |
| 目次

前 | 次 |

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

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

この章には次の項が含まれます:

- 第25.1項「プッシュ通知の概要」

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

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

## 25.1 プッシュ通知の概要

通知とは、モバイル・アプリケーションの通常のユーザー・インタフェース以外でエンド・ユーザーに配信される合図です。これらの通知は、アプリケーションの状態とユーザー設定に応じて、アラート・メッセージやバナーとして表示されます。通知は、視覚的に、または音で(あるいはその両方で)配信できます。

主な通知のタイプには、次の2つがあります。

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

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

  図25-1 プッシュ通知

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

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

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

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

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

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

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

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

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

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

1. モバイル・アプリケーションでプッシュ通知を受信できるようにするには、MAFアプリケーション・エディタのプラグイン有効化セクションでコア・プラグインのPushPluginを有効化し、そのプラグインを1つ以上のアプリケーション機能に関連付けます。詳細は、第10章「MAFアプリケーションでのプラグインの使用方法」を参照してください。

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

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

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

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

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

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

   MAFでは、アプリケーションが通知を受信するたびに、通知ペイロードを使用して`onMessage(Event e)`メソッドをコールします。`Event`オブジェクトは、通知ペイロードおよびアプリケーションの状態に関する有用な情報を取得するために使用できます。通知ペイロードを取得するには、`Event.getPayload`メソッドを使用します。通知時にアプリケーションの状態を取得するには、`Event.getApplicationState`メソッドを使用します。詳細は、``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());

PushDemoというMAFサンプル・アプリケーションは、プッシュ通知の処理方法を示しています。これは、「ファイル」→「新」→「MAFサンプル」にあります(付録G「サンプルのMAFアプリケーション」を参照)。

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

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

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

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

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

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

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

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

- MAFの提供するJava API (第25.3.1項「Javaを使用してローカル通知を管理する方法」を参照)。

- MAFの提供するJavaScript API (第25.3.2項「JavaScriptを使用してローカル通知を管理する方法」を参照)。

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

LocalNotificationというMAFサンプル・アプリケーションは、ローカル通知のスケジュール方法と処理方法を示しています。これは、「ファイル」→「新」→「MAFサンプル」にあります(付録G「サンプルのMAFアプリケーション」を参照)。

### 25.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");
      }

  通知オプションがアプリケーションの動作に与える影響は、ターゲット・プラットフォームに応じて異なります。詳細は、第25.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 Mobile Application Framework Java APIリファレンスを参照してください。

### 25.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) {}

  通知オプションがアプリケーションの動作に与える影響は、ターゲット・プラットフォームに応じて異なります。詳細は、第25.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リファレンスを参照してください。

### 25.3.3 DeviceFeaturesデータ・コントロールを使用してローカル通知を管理する方法

ローカル通知は、DeviceFeaturesデータ・コントロールの`addLocalNotification`および`cancelLocalNotification`メソッドを使用して、スケジュールしたり取り消すことができます。

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

### 25.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`メソッドのリスナーを追加する必要があります。

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

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

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

表25-2で、ローカル通知オプションをリストし、各オプションに特定の値を設定した場合または値を設定しない場合にMAFアプリケーションの通知動作がどのような影響を受けるかについて説明します。

表25-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 バイブレーションを制御することはできません。設定は無視されます。ただし、デフォルトのシステム・サウンドを通知の着信時に再生するように指定している場合や、エンド・ユーザーがモバイル・デバイスで着信時にバイブレートする設定を有効にしている場合、デバイスは通知を受信するとバイブレートします。