Download PDF
Download page Cordova インストゥルメンテーションのカスタマイズ.
Cordova インストゥルメンテーションのカスタマイズ
Cordova プラグインを使用して Cordova ベースのアプリケーションをインストゥルメント化すると、API を使用してコントローラの UI に表示されるアプリケーションのデータをカスタマイズすることもできます。
Cordova プラグイン SDK API の使用
構文
SDK API メソッドを呼び出すには、次の構文を使用します。window.plugins.ADEUMMobilePlugin.<method>
引き数
すべての SDK API メソッドの最後の 2 つの引数は、常に 2 つの関数を使用する必要があります。最初の機能で成功したケースを処理し、最後の方法で障害を処理する必要があります。
例:
window.plugins.ADEUMMobilePlugin.changeAppKey("<EUM_APP_KEY>",
(success) => {
this.showAlert("changeAppKey return: success");
},
(error) => {
this.showAlert("changeAppKey error:" + error);
}
);
SDK API を呼び出すメソッドの追加
SDK API を使用するには、次に示すように SDK API を呼び出すクラスメソッドを作成することをお勧めします。
export class HomePage {
...
someMethod(event) {
window.plugins.ADEUMMobilePlugin.<method>(<arg1>, <success_function>, <failure_function>);
}
...
}
例
そのため、HomePage.js
ファイルの場合は、HomePage
クラスに、次に示す SDK API メソッド screenshot
を呼び出すメソッド takeScreenshot
を含めることができます。
export class HomePage {
...
takeScreenshot(event) {
// Call the Cordova plugin SDK methods
window.plugins.ADEUMMobilePlugin.screenshot(
(success) => {
this.showAlert("crash return: success");
},
(error) => {
this.showAlert("crash error:" + error);
});
}
...
}
アプリケーションキーの変更
EUM アプリケーションキーを変更するには、次のパラメータを使用してメソッド changeAppKey
を使用します。
パラメータ名 | データ タイプ | 説明 |
---|---|---|
appKey | string | EUM アプリケーションキー。 |
success | 機能 | changeAppKey が成功したときに呼び出されるユーザ定義関数。 |
error | 機能 | changeAppKey が失敗したときに呼び出されるユーザ定義関数。 |
たとえば、新しいアプリケーションキーを取得して SDK API メソッド changeAppKey
に渡す新しいメソッドを作成できます。
changeAppKey(event, newAppKey) {
window.plugins.ADEUMMobilePlugin.changeAppKey(newAppKey,
(success) => {
this.showAlert("changeAppKey return: success");
},
(error) => {
this.showAlert("changeAppKey error:" + error);
}
);
}
データの追加タイプの収集
ADEUMMobilePlugin
クラスで使用可能なメソッドを使用して、次の 5 つのタイプのデータを収集できます。
情報ポイント
Information points allow you to track how your own code is running. メソッドが呼び出される頻度と、beginCall
を呼び出して実行される時間を確認できます。コールバック success
または error
が呼び出されると、情報ポイントを追跡するためのコールが終了します。
beginCall(name, functionName, args, success, error)
Parameters
次の表では、2 つの方法のパラメータについて説明します。
名前 | タイプ | 説明 |
---|---|---|
name | string | 情報ポイントが記録されているファイルまたはモジュールの名前。 |
functionName | string | 情報ポイントを追跡するために beginCall を呼び出す関数。 |
success | 機能 | ユーザ定義のコールバックの成功例。 |
error | 機能 | ユーザ定義のコールバックの失敗例。 |
例
たとえば、次のようなコードを使用して情報ポイントを作成すると、メソッドの起動方法、および実行にかかる時間を決定できます。
beginCall(event) {
window.plugins.ADEUMMobilePlugin.beginCall("home.ts", "callTrackerFunction", "event",
(tracker) => {
tracker.reportCallEndedWithReturnValue("Return from home.ts",
(success) => { console.log("End call with return value success:" + success);},
(error) => { console.log("End call with return value error:" + error); });
},
(error) => {
console.log("Begin call error:" + error);
}
);
}
カスタムタイマー
カスタムタイマーを作成して、コード内の任意のイベントシーケンスに時間をかけることができます。これには、複数のメソッドがあります。カスタムタイマーを作成するには、SDK API メソッド startTimer
と stopTimer
を使用します。
startTimerWithName(name, success, error)
stopTimerWithName(name, success, error)
パラメータ
2 つのメソッドは、次のパラメータを使用します。
名前 | タイプ | 説明 |
---|---|---|
name | string | カスタムタイマーの名前。使用できる文字は [A-Za-z\s0-9] です。Illegal characters are replaced by their ASCII hex value. |
success | 機能 | ユーザ定義のコールバックの成功例。 |
error | 機能 | ユーザ定義のコールバックの失敗例。 |
例
For example, to track the time a user spends viewing a screen, the instrumentation could look like this:
startTimer(event) {
window.plugins.ADEUMMobilePlugin.startTimerWithName(data.name,
(success) => {
this.showAlert("startTimerWithName return: success");
},
(error) => {
this.showAlert("startTimerWithName error:" + error);
}
);
}
stopTimer(event) {
window.plugins.ADEUMMobilePlugin.stopTimerWithName(data.name,
(success) => {
this.showAlert("stopTimerWithName return: success");
},
(error) => {
this.showAlert("stopTimerWithName error:" + error);
}
);
}
Custom Metrics
カスタムメトリックをレポートすることもできます。
reportMetricWithName
を使用してカスタムメトリックを作成します。
reportMetricWithName(name, value, success, error)
パラメータ
reportMetricWithName
メソッドは、次のパラメータを使用します。
名前 | タイプ | 説明 |
---|---|---|
name | string | カスタムメトリックの名前。メトリック名には英数字を使用する必要があります。Illegal characters are replaced by their ASCII hex value. |
value | number | 値が整数ではない場合は、エラーが返されます。 |
success | 機能 | ユーザ定義の成功コールバック。 |
error | 機能 | ユーザ定義のエラーコールバック。 |
例
たとえば、次のメソッドを使用してカスタムメトリックをレポートすることができます。
reportMetric(event, data) {
window.plugins.ADEUMMobilePlugin.reportMetricWithName(data.name, parseInt(data.value),
(success) => {
this.showAlert("reportMetricWithName : success");
},
(error) => {
this.showAlert("reportMetricWithName error:" + error);
}
);
};
トピックパス(パンくずリスト)
Breadcrumbs allow you to situate a crash in the context of your user's experience. Set a breadcrumb when something interesting happens. If your application crashes at some point in the future, the breadcrumb will be displayed along with the crash report. Each crash report displays the most recent 99 breadcrumbs.
次の SDK API メソッドを使用して、トピックパスを作成して残します。
leaveBreadcrumb(breadcrumb, mode, success, error)
パラメータ
メソッド leaveBreadcrumb
では、次のパラメータを使用します。
名前 | タイプ | 説明 |
---|---|---|
breadcrumb | string | クラッシュレポートおよびセッションに含める文字列。2048 文字で切り捨てられます。空の値は無視されます。 |
mode | number | トピックパスが表示される場所を決定するモードは次のとおりです。
値が解析できない場合、モードはデフォルトでクラッシュします。 |
success | 機能 | ユーザ定義のコールバックの成功例。 |
error | 機能 | ユーザ定義のコールバックの失敗例。 |
例
次のコード例は、SDK API を使用して、トピックパスを残す方法を示しています。
breadcrumb(mode) {
window.plugins.ADEUMMobilePlugin.leaveBreadcrumb( "breadcrumb1", mode,
(success) => {
this.showAlert("leaveBreadcrumb return: success");
},
(error) => {
this.showAlert("leaveBreadcrumb error:" + error);
}
)
カスタムユーザデータの追加
次のメソッドで役立つ任意の文字列キー/値のペアを設定し、後で削除することができます。
setUserData(key, value, success, error)
removeUserData(key, success, error)
パラメータ
次の表で、パラメータについて説明します。
名前 | タイプ | 説明 |
---|---|---|
key | string | キーと値のペアを識別するキー。 |
value | string | キーに関連付けられている値。 |
success | 機能 | ユーザ定義のコールバックの成功例。 |
error | 機能 | ユーザ定義のコールバックの失敗例。 |
例
次のコード例は、SDK API を使用してユーザデータを設定および削除する方法を示しています。
setCustomData(event, data) {
window.plugins.ADEUMMobilePlugin.setUserData(data.name, data.value,
(success) => {
this.showAlert("setUserData return: success");
},
(error) => {
this.showAlert("setUserData error:" + error);
}
);
};
removeUserData(event, key) {
window.plugins.ADEUMMobilePlugin.removeUserData(key,
(success) => {
this.showAlert("removeUserData return: success");
},
(error) => {
this.showAlert("removeUserData error:" + error);
}
);
}
Programmatically Control Sessions
デフォルトでは、ユーザが非アクティブになってからモバイルセッションが終了します。たとえば、ユーザがアプリケーションを開くと、セッションは開始され、ユーザが設定した期間にアプリケーションを使用しなくなった後にのみ終了します。ユーザがアプリケーションの再使用を開始すると、新しいセッションが開始されます。
ただし、セッションの期間を定義するのに非アクティブな期間を設定する代わりに、次の API を使用して、セッションの開始と終了をプログラムで制御できます。
startNextSession(success, error)
ADEUMMobilePlugin
からメソッド startNextSession
を呼び出すと、現在のセッションが終了し、新しいセッションが開始されます。API を使用すると、セッションを定義してフレーム化することができます。これにより、ビジネス目標と予想されるユーザフローをより厳密に合わせることができます。たとえば、API を使用して、製品の購入を追跡するセッションを定義したり、新しいユーザを登録したりすることができます。
この API を過剰に使用すると、セッションが調整されます(過剰使用は 1 分あたり 10 コールを超えた場合になりますが、変更される可能性があります)。API を使用しない場合、セッションは、ユーザが非アクティブになった後、デフォルトの終了にフォールバックします。
プログラムによって制御されるセッションの例
In the example below, the current session ends and a new one begins when the check out is made.
completeCheckout() {
if (this.validateAddress() && this.validatePayment()){
let loader = this.loader.create({
content: "Completing the checkout..."
});
loader.present();
return this.order.create({
shipping_address: this.address,
billing_address: this.address,
cart_id: Number(this.configuration.get('cart_id'))
})
...
window.plugins.ADEUMMobilePlugin.startNextSession(
(success) => {
console.log("startNextSession return: success");
},
(error) => {
console.log("startNextSession error:" + error);
}
);
}
Start and End Session Frames
セッションアクティビティに表示されるセッションフレームを作成するために、Cordova プラグインを使用できます。セッションフレームは、セッション中にユーザが実行している内容のコンテキストを提供します。API を使用すると、ビジネスコンテキスト内のユーザ画面の名前とユーザフローの記録を向上させることができます。
使用例
セッションフレームの一般的な使用方法は次のとおりです。
- 1 つのページで複数の関数を実行し、個々の関数をより詳細に追跡する必要があります。
- ユーザフローは、複数のページまたはユーザのインタラクションに及びます。たとえば、API を使用してセッションフレーム「Login」、「Product Selection」、および「Purchase」を作成して、ユーザが購入のためにフローを記録することができます。
- ユーザの操作に基づいて動的情報をキャプチャし、オーダー ID などのセッションフレームに名前を付けることができます。
SessionFrame API
The table below lists the three methods you can use with session frames. つまり、startSessionFrame
を使用してセッションフレームを開始してから、updateName
と end
を使用してセッションフレームの名前を変更し、終了します。
メソッド | パラメータ | 説明 | |
---|---|---|---|
|
| セッションフレームを開始して名前を付けるには、これを使用します。 このメソッドは | |
|
| Rename the session frame name.
| |
|
| セッションフレームを終了します。
|
セッションフレームの例
次の例では、チェックアウトプロセス中にユーザアクティビティを追跡するためにセッションフレームが使用されます。
declare var window: any;
@Component({
...
})
export class OrderPage {
sessionFrame: any;
...
checkoutCartButtonClicked() {
// The user starting to check out starts when the user clicks the checkout button
// this may be after they have updated quantities of items in their cart, etc.
window.plugins.ADEUMMobilePlugin.startSessionFrame("Checkout",
(sessionFrame) => {
// The returned object is saved to the class property 'sessionFrame' so
// the SessionFrame API methods 'updateName' and 'end' can be called from it later.
this.sessionFrame = sessionFrame;
},
(error) => {
console.log("startSessionFrame call error:" + error);
}
);
}
confirmOrderButtonClicked() {
// Once they have confirmed payment info and shipping information, and they
// are clicking the "Confirm" button to start the backend process of checking out
// we may know more information about the order itself, such as an Order ID.
this.sessionFrame.updateName("Checkout: Order ID " + this.orderId,
(success) => {
console.log("Order has been placed and sessionFrame updated:" + this.orderId);
},
(error) => {
console.log("Order has been placed but sessionFrame couldn't be updated because of the error " + error);
}
);
}
processOrderCompleted() {
// Once the order is processed, the user is done "checking out" so we end
// the session frame.
this.sessionFrame.end(
(success) => {
console.log("Order was completed and sessionFrame ended: " + success);
},
(error) => {
console.log("Order was completed but sessionFrame couldn't be ended because of: " + error);
}
);
}
checkoutCancelled() {
// If they cancel or go back, you'll want to end the session frame also, or else
// it will be left open and appear to have never ended.
this.sessionFrame.end(
(success) => {
console.log("Order was cancelled and sessionFrame ended: " + success);
},
(error) => {
console.log("Order was cancelled but sessionFrame couldn't be ended because of: " + error);
}
);
}
} // end of export class OrderPage
Configure and Take Screenshots
Mobile screenshots are enabled by default. これらのスクリーンショットは Sessions Details ダイアログに表示されます。
次に示すように、スクリーンショットを自動的に作成するか、または Cordova プラグインを使用して手動でスクリーンショットを作成するようにコントローラ UI を設定できます。
screenshot(event) {
// make a call to plugin
console.log("screenshot click handler");
window.plugins.ADEUMMobilePlugin.takeScreenshot(
(success) => {
this.showAlert("screenshot return: success");
},
(error) => {
this.showAlert("screenshot error:" + error);
});
}
これにより、個人情報を含むすべてがキャプチャされるため、スクリーンショットを作成するタイミングに注意する必要があります。
Block and Unblock Screenshots
コードブロックの実行中にスクリーンショットが作成されるのをブロックすることもできます。This just temporarily blocks screenshots from being taken until you unblock screenshots. This enables you to stop taking screenshots in situations where users are entering personal data, such as on login and account screens.
logInScreen(event) {
// Block Screen while getting user input
window.plugins.ADEUMMobilePlugin.blockScreenshots(
(success) => {
console.log("blockScreenshots return: success");
this.getUserInput();
this.submitUserInput();
},
(error) => {
console.log("blockScreenshots error:" + error);
}
);
// Unblock screen and return to home page
window.plugins.ADEUMMobilePlugin.unblockScreenshots(
(success) => {
console.log("unblockScreenshots return: success");
this.homePage()
},
(error) => {
console.log("unblockScreenshots error:" + error);
}
);
}
ロギングの有効化とロギングレベルの設定
You use the method loggingLevel
to enable and set the logging level. ロギングは、次のいずれかのレベルに設定できます。
値 | ログ レベル | 説明 |
---|---|---|
0 | なし | ログは表示されません。 This level disables logging. |
1 | エラー | エラーメッセージのみが表示されます。 This is the default logging level. |
2 | [警告(Warn)] | 警告メッセージとエラーメッセージが表示されます。 |
3 | 情報 | 警告、エラー、および開発者に焦点を当てたメッセージが表示されます。 |
4 | [デバッグ(Debug)] | エラー、警告、開発者情報、およびデバッグメッセージが表示されます。 |
5 | Verbose | エラー、警告、開発者の情報、デバッグ、およびトラブルシューティング メッセージが表示されます。 |
6 | すべて | サポート対象のすべてのログメッセージが表示されます。 |
ロギングを有効にするには、インストゥルメンテーションの構成でロギングレベルを設定します。たとえば、この例では、ロギングを有効にし、ログレベルを Info
に設定します。
window.plugins.ADEUMMobilePlugin.initWithConfiguration(
{
"appKey": "<EUM_APP_KEY>",
"loggingLevel": 3
},
(success) => {
this.showAlert("initWithConfiguration return: success");
},
(error) => {
this.showAlert("initWithConfiguration error:" + error);
}
);
Cordova SDK のドキュメント
Cordova SDK API リファレンスのマニュアルについては、最新の JSDoc のマニュアルまたは以下に記載されている以前のバージョンを参照してください。
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.1/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.2/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.3/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.4/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.5/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.6/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.7/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.8/
- https://sdkdocs.appdynamics.com/javadocs/cordova-plugin/1/1.9/
Cordova プラグインのバージョン番号は、コントローラおよび AppDynamics プラットフォーム コンポーネントのバージョン番号とは異なります。この違いがあるため、すべての Cordova プラグイン機能を完全にサポートするために必要な最小バージョンのコントローラおよび EUM サーバについては、『 Mobile Agent Version and Deployment Support Matrix』を参照してください。