クライアント・アプリケーションでの Analytics API の使用

概説

IBM MobileFirst Foundation Operational Analytics は、アプリケーションについての Analytics データの収集を開始するのを支援するクライアント・サイド API を提供します。このチュートリアルでは、クライアント・アプリケーション上での Analytics サポートのセットアップ方法について説明し、使用可能な API をリストします。

ジャンプ先

クライアント・サイドでの Analytics の構成
Analytics データの送信
クライアント・イベントの有効化/無効化
カスタム・イベント
ユーザーのトラッキング
アプリ内ユーザー・フィードバックのキャプチャーおよび送信

クライアント・サイドでの Analytics の構成

MobileFirst Analytics が提供する事前定義データの収集を開始するには、事前に Analytics サポートを初期設定するために対応するライブラリーをインポートする必要があります。

JavaScript (Cordova)

Cordova アプリケーションではセットアップは必要なく、初期設定は組み込まれています。

JavaScript (Web)

Web アプリケーションでは、分析 JavaScript ファイルを参照する必要があります。最初に必ず MobileFirst Web SDK を追加しておいてください。詳細については、『Web アプリケーションへの MobileFirst SDK の追加』チュートリアルを参照してください。

MobileFirst Web SDK を追加した方法に応じて、以下のいずれかの方法で進めます。

以下のように、HEAD エレメント内の MobileFirst Analytics を参照します。

<head>
    ...
    <script type="text/javascript" src="node_modules/ibm-mfp-web-sdk/lib/analytics/ibmmfpfanalytics.js"></script>
    <script type="text/javascript" src="node_modules/ibm-mfp-web-sdk/ibmmfpf.js"></script>
</head>

または、RequireJS を使用している場合は、以下を作成します。

require.config({
	'paths': {
		'ibmmfpfanalytics': 'node_modules/ibm-mfp-web-sdk/lib/analytics/ibmmfpfanalytics',
		'mfp': 'node_modules/ibm-mfp-web-sdk/ibmmfpf'
	}
});

require(['ibmmfpfanalytics','mfp'], function(ibmmfpfanalytics, WL) {
    // application logic.
});

ユーザー独自の名前空間を選択して、「ibmmfpfanalytics」と置き換えることができることに留意してください。

ibmmfpfanalytics.logger.config({analyticsCapture: true});

重要: Cordova と Web SDK 間には JavaScript API においていくつかの相違点があります。ユーザー資料の『API リファレンス』トピックを参照してください。

iOS

WLAnalytics ライブラリーのインポート

Objective-C

import "WLAnalytics.h"

Swift

import IBMMobileFirstPlatformFoundation

Analytics の初期設定

Objective-C
セットアップは不要です。デフォルトで事前に初期設定されています。

Swift
WLAnalytics クラスの他のメソッドを呼び出す前に、WLAnalytics.sharedInstance() を呼び出します。

Android

WLAnalytics のインポート

import com.worklight.common.WLAnalytics;

Analytics の初期設定

メイン・アクティビティーの onCreate メソッド内に以下を含めます。

WLAnalytics.init(this.getApplication());

クライアント・イベント・タイプの有効化/無効化

Analytics API では、開発者は MobileFirst Analytics Console 上で視覚化したいイベントについての Analytics の収集を自由に有効または無効にすることができます。

MobileFirst Analytics API により、以下のメトリックのキャプチャーが可能になります。

ライフサイクル・イベント: アプリケーション使用比率、使用所要時間、アプリケーション異常終了比率
ネットワーク使用: API 呼び出し頻度の明細、ネットワーク・パフォーマンス・メトリック
ユーザー: 指定されたユーザー ID で識別されるアプリケーション・ユーザー
カスタム分析: アプリケーション開発者によって定義されるカスタム・キー/値ペア

Analytics API の初期設定は、Cordova アプリケーションであっても、ネイティブ・コードで作成されなければなりません。

アプリケーションの使用をキャプチャーするには、関連イベントが発生してそのデータがサーバーに送信される前にアプリケーション・ライフサイクル・イベント・リスナーを登録する必要があります。
ファイル・システムまたはネイティブ言語およびデバイス機能を使用するには、API を初期設定する必要があります。ネイティブ・デバイス機能 (ファイル・システムなど) を必要とする方法で API が使用されるが、初期設定されていないと、API 呼び出しは失敗します。 Android では特に、この動作になります。

注: Cordova アプリケーションを構築するにあたり、JavaScript Analytics API には LIFECYCLE イベントおよび NETWORK イベントの収集を有効にしたり無効にしたりするメソッドがありません。言い換えると、Cordova アプリケーションは、LIFECYCLE イベントおよび NETWORK イベントがデフォルトで事前に有効になった状態で出荷されます。これらのイベントを無効にしたい場合は、『クライアント・ライフサイクル・イベント』および『クライアント・ネットワーク・イベント』を参照してください。

クライアント・ライフサイクル・イベント

Analytics SDK が構成された後、ユーザーのデバイス上でアプリケーション・セッションの記録が開始します。 MobileFirst Analytics でのセッションは、アプリケーションがフォアグラウンドからバックグラウンドに移動され、これにより、Analytics Console でセッションが作成されたときに記録されます。

セッションを記録するようにデバイスがセットアップされ、ユーザーがデータを送信するとすぐに、以下に示すようにデータが Analytics Console に設定されているのを確認できます。

セッション-グラフ

Analytics API を使用して、アプリケーション・セッションの収集を有効または無効にします。

JavaScript

Web
クライアント・ライフサイクル・イベントを使用するには、以下のようにして Analytics を初期設定します。

ibmmfpfanalytics.logger.config({analyticsCapture: true});

Cordova
ライフサイクル・イベントのキャプチャーを有効にするには、Cordova アプリケーションのネイティブ・プラットフォームで初期設定する必要があります。

iOS プラットフォームの場合:
- 「[Cordova application root folder]」→「platforms」→「ios」→「Classes」フォルダーを開き、AppDelegate.m (Objective-C) ファイルまたは AppDelegate.swift (Swift) ファイルを見つけます。
- 下記の iOS ガイドに従って、LIFECYCLE アクティビティーを有効または無効にします。
- コマンド cordova build を実行して、Cordova プロジェクトを作成します。
Android プラットフォームの場合:
- 「[Cordova application root folder]」→「platforms」→「android」→「src」→「com」→「sample」→「[app-name]」→「MainActivity.java」ファイルを開きます。
- onCreate メソッドを探し、下記の Android ガイドに従って、LIFECYCLE アクティビティーを有効または無効にします。
- コマンド cordova build を実行して、Cordova プロジェクトを作成します。

Android

クライアント・ライフサイクル・イベントのロギングを有効にするには、以下のようにします。

WLAnalytics.addDeviceEventListener(DeviceEvent.LIFECYCLE);

クライアント・ライフサイクル・イベントのロギングを無効にするには、以下のようにします。

WLAnalytics.removeDeviceEventListener(DeviceEvent.LIFECYCLE);

iOS

クライアント・ライフサイクル・イベントのロギングを有効にするには、以下のようにします。

Objective-C:

[[WLAnalytics sharedInstance] addDeviceEventListener:LIFECYCLE];

Swift:

WLAnalytics.sharedInstance().addDeviceEventListener(LIFECYCLE);

クライアント・ライフサイクル・イベントのロギングを無効にするには、以下のようにします。

Objective-C:

[[WLAnalytics sharedInstance] removeDeviceEventListener:LIFECYCLE];

Swift:

WLAnalytics.sharedInstance().removeDeviceEventListener(LIFECYCLE);

クライアント・ネットワーク・アクティビティー

アダプターおよびネットワークについての収集は、クライアントとサーバーの 2 つの異なるロケーションで発生します。

ユーザーが NETWORK デバイス・イベントについて収集を開始すると、クライアントは往復時間およびペイロード・サイズなどの情報を収集します。
サーバーは、サーバー処理時間、アダプターの使用状況、使用されたプロシージャーなどのバックエンド情報を収集します。

クライアントとサーバーはそれぞれ独自の情報を収集するため、クライアントが収集を行うように構成されるまでグラフにはデータが表示されません。クライアントを構成するには、NETWORK デバイス・イベントの収集を開始し、それをサーバーに送信する必要があります。

JavaScript

Web
クライアント・ネットワーク・イベントを使用するには、以下のようにして Analytics を初期設定します。

ibmmfpfanalytics.logger.config({analyticsCapture: true});

Cordova
ネットワーク・イベントのキャプチャーを有効にするには、Cordova アプリケーションのネイティブ・プラットフォームで初期設定する必要があります。

iOS プラットフォームの場合:
- 「[Cordova application root folder]」→「platforms」→「ios」→「Classes」フォルダーを開き、AppDelegate.m (Objective-C) ファイルまたは AppDelegate.swift ファイルを見つけます。
- 下記の iOS ガイドに従って、NETWORK アクティビティーを有効または無効にします。
- コマンド cordova build を実行して、Cordova プロジェクトを作成します。
Android プラットフォームの場合: 無効にするメイン・アクティビティーのサブアクティビティーにナビゲートします。
- 「[Cordova application root folder]」→「platforms」→「ios」→「src」→「com」→「sample」→「[app-name]」→「MainActivity.java」ファイルを開きます。
- onCreate メソッドを探し、下記の Android ガイドに従って、NETWORK アクティビティーを有効または無効にします。
- コマンド cordova build を実行して、Cordova プロジェクトを作成します。

iOS

クライアント・ネットワーク・イベントのロギングを有効にするには、以下のようにします。

Objective-C:

[[WLAnalytics sharedInstance] addDeviceEventListener:NETWORK];

Swift:

WLAnalytics.sharedInstance().addDeviceEventListener(NETWORK);

クライアント・ネットワーク・イベントのロギングを無効にするには、以下のようにします。

Objective-C:

[[WLAnalytics sharedInstance] removeDeviceEventListener:NETWORK];

Swift:

WLAnalytics.sharedInstance().removeDeviceEventListener(NETWORK);

Android

クライアント・ネットワーク・イベントのロギングを有効にするには、以下のようにします。

WLAnalytics.addDeviceEventListener(DeviceEvent.NETWORK);

クライアント・ネットワーク・イベントのロギングを無効にするには、以下のようにします。

WLAnalytics.removeDeviceEventListener(DeviceEvent.NETWORK);

カスタム・イベント

カスタム・イベントを作成するには、以下の API メソッドを使用します。

JavaScript (Cordova)

WL.Analytics.log({"key" : 'value'});

JavaScript (Web)

Web API では、addEvent メソッドでカスタム・データが送信されます。

ibmmfpfanalytics.addEvent({'Purchases':'radio'});
ibmmfpfanalytics.addEvent({'src':'App landing page','target':'About page'});

Android

最初の 2 つの構成を設定した後、以下の例のようにしてデータをログに記録し始めることができます。

JSONObject json = new JSONObject();
try {
    json.put("key", "value");
} catch (JSONException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

WLAnalytics.log("Message", json);

iOS

WLAnalytics をインポートした後、以下のようにして API を使用してカスタム・データを収集できるようになります。

Objective-C:

NSDictionary *inventory = @{
    @"property" : @"value",
};

[[WLAnalytics sharedInstance] log:@"Custom event" withMetadata:inventory];
[[WLAnalytics sharedInstance] send];

Swift:

let metadata: [NSObject: AnyObject] = ["foo": "bar"];  
WLAnalytics.sharedInstance().log("hello", withMetadata: metadata);

ユーザーのトラッキング

個々のユーザーをトラッキングするには、以下のように setUserContext メソッドを使用します。

Cordova

サポートされません。

Web アプリケーション

ibmmfpfanalytics.setUserContext(user);

iOS

Objective-C

[[WLAnalytics sharedInstance] setUserContext:@"John Doe"];

Swift

WLAnalytics.sharedInstance().setUserContext("John Doe")

Android

WLAnalytics.setUserContext("John Doe");

個々のユーザーのトラッキングを解除するには、以下のように unsetUserContext メソッドを使用します。

Cordova

サポートされません。

Web アプリケーション

MobileFirst Web SDK に unsetUserContext はありません。ユーザー・セッションは、別のユーザー・セッションが ibmmfpfanalytics.setUserContext(user) に作成されない限り、30 分活動が無ければ終了します。

iOS

Objective-C

[[WLAnalytics sharedInstance] unsetUserContext];

Swift

WLAnalytics.sharedInstance().unsetUserContext

Android

WLAnalytics.unsetUserContext();

Analytics データの送信

Analytics の送信は、Analytics サーバー上でクライアント・サイドの分析を表示するための重要なステップです。構成済みのイベント・タイプのデータが Analytics のために収集されると、分析ログはクライアント・デバイス上のログ・ファイルに保管されます。ファイルのデータは、Analytics API の send メソッドを使用して MobileFirst Analytics Server に送信されます。

キャプチャーされたログを定期的にサーバーに送信することを検討してください。定期的にデータを送信することにより、MobileFirst Analytics Console で常に最新の分析データを参照できるようになります。

JavaScript (Cordova)

Cordova アプリケーションで、以下の JavaScript API メソッドを使用します。

WL.Analytics.send();

JavaScript (Web)

Web アプリケーションで、以下の JavaScript API メソッドを使用します (内容は選択した名前空間に応じて異なります) 。

ibmmfpfanalytics.send();

iOS

Objective-C

[[WLAnalytics sharedInstance] send];

Swift

WLAnalytics.sharedInstance().send();

Android

Android アプリケーションで、以下の Java API メソッドを使用します。

WLAnalytics.send();

アプリ内ユーザー・フィードバックのキャプチャーおよび送信

アプリ内ユーザー・フィードバックを使用して、アプリケーションのパフォーマンス分析を深めることができます。アプリケーションのユーザーおよびテスターからアプリの所有者にコンテキスト・フィードバックが豊富に提供されるようになります。アプリの所有者が、アプリケーションの使用体験に関するフィードバックをユーザーからリアルタイムで取得し、アプリ所有者や開発者が、そのフィードバックに対処することができます。この機能により、非常に俊敏にアプリケーションを刷新できます。例えばボタンのクリックやメニュー項目の選択を処理する際に、アプリケーションのアクション・ハンドラー内で、以下の API を使用して、アプリケーションを対話式フィードバック・モードに切り替えます。

この機能は、Web アプリケーションではサポートされていません。

JavaScript (Cordova)

まず、次のプラグインを追加して、Cordova アプリケーションにアプリ内フィードバック機能を組み込み、プラグインが正常に追加されていることを確認します。

cordova plugin add cordova-plugin-mfp-analytics

次に、Cordova アプリケーションのアクション・ハンドラーで、次の JavaScript API メソッドを使用します。

WL.Analytics.triggerFeedbackMode();

JavaScript (Web)

サポートされません

iOS

Swift

まず、アプリケーションの Podfile に以下を追加します。

pod 'IBMMobileFirstPlatformFoundationAnalytics'

次に、XCode プロジェクトのルートで次のコマンドを実行して、ポッドを更新してください。

pod update

次に、アプリケーションのアクション・ハンドラーで次の API を呼び出します。

WLAnalytics.sharedInstance().triggerFeedbackMode();

Android

まず、アプリケーションの Gradle スクリプトに次の依存関係を追加します。

compile 'com.ibm.mobile.foundation:ibmmobilefirstplatformfoundationanalytics:8.0.+@aar'

次に、Android アプリケーションで、アクション・ハンドラーで次の Java API メソッドを使用します。

WLAnalytics.triggerFeedbackMode();

▲

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.

Last modified on November 27, 2019