Cordova プラグインを使用して Cordova ベースのアプリケーションをインストゥルメント化すると、API を使用してコントローラの UI に表示されるアプリケーションのデータをカスタマイズすることもできます。以下のセクションでは、Cordova プラグイン SDK API を使用してインストゥルメンテーションをカスタマイズする方法について説明します。

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);
    }
);
JS

SDK API を呼び出すメソッドの追加

SDK API を使用するには、次に示すように SDK API を呼び出すクラスメソッドを作成することをお勧めします。

export class HomePage {
    ...
    someMethod(event) {
         window.plugins.ADEUMMobilePlugin.<method>(<arg1>, <success_function>, <failure_function>);
    }
    ...
}
JS

そのため、HomePage.js ファイルの場合は、HomePage クラスに、次に示す SDK API メソッド screenshot を呼び出すメソッド takeScreenshot を含めることができます。

export class HomePage {
    ...
    takeScreenshot(event) {
      // Call the Cordova plugin SDK methods
      window.plugins.ADEUMMobilePlugin.screenshot(
       (success) =&gt; {
        this.showAlert("crash return: success");
       },
      (error) =&gt; {
        this.showAlert("crash error:" + error);
      });
    }
    ...
}
JS

アプリケーションキーの変更

EUM アプリケーションキーを変更するには、次のパラメータを使用してメソッド changeAppKey を使用します。

パラメータ名データ タイプ説明
appKeystringEUM アプリケーションキー。
success機能changeAppKey が成功したときに呼び出されるユーザ定義関数。
error機能changeAppKey が失敗したときに呼び出されるユーザ定義関数。

たとえば、新しいアプリケーションキーを取得して SDK API メソッド changeAppKey に渡す新しいメソッドを作成できます。

changeAppKey(event, newAppKey) {
    window.plugins.ADEUMMobilePlugin.changeAppKey(newAppKey,
        (success) =&gt; {
            this.showAlert("changeAppKey return: success");
        },
        (error) =&gt; {
            this.showAlert("changeAppKey error:" + error);
        }
    );
}
JS

データの追加タイプの収集

ADEUMMobilePlugin クラスで使用可能なメソッドを使用して、次の 5 つのタイプのデータを収集できます。

情報ポイント

情報ポイントを使用すると、独自のコードがどのように実行されているかを追跡できます。メソッドが呼び出される頻度と、beginCall を呼び出して実行される時間を確認できます。コールバック success または error が呼び出されると、情報ポイントを追跡するためのコールが終了します。

  • beginCall(name, functionName, args, success, error)

Parameters

次の表では、2 つの方法のパラメータについて説明します。

名前タイプ説明
namestring情報ポイントが記録されているファイルまたはモジュールの名前。
functionNamestring情報ポイントを追跡するために beginCall を呼び出す関数。
success機能ユーザ定義のコールバックの成功例。
error機能ユーザ定義のコールバックの失敗例。

たとえば、次のようなコードを使用して情報ポイントを作成すると、メソッドの起動方法、および実行にかかる時間を決定できます。

beginCall(event) {
    window.plugins.ADEUMMobilePlugin.beginCall("home.ts", "callTrackerFunction", "event",
        (tracker) =&gt; {
            tracker.reportCallEndedWithReturnValue("Return from home.ts",
                (success) =&gt; { console.log("End call with return value success:" + success);},
                (error) =&gt; { console.log("End call with return value error:" + error); });
            },
            (error) =&gt; {
                console.log("Begin call error:" + error);
        }
    );
}
JS

カスタムタイマー

カスタムタイマーを作成して、コード内の任意のイベントシーケンスに時間をかけることができます。これには、複数のメソッドがあります。カスタムタイマーを作成するには、SDK API メソッド startTimerstopTimer を使用します。

  • startTimerWithName(name, success, error)

  • stopTimerWithName(name, success, error)

パラメータ

2 つのメソッドは、次のパラメータを使用します。

名前タイプ説明
namestringカスタムタイマーの名前。使用できる文字は [A-Za-z\s0-9] です。不正な文字は、ASCII 16 進値に置き換えられます。
success機能ユーザ定義のコールバックの成功例。
error機能ユーザ定義のコールバックの失敗例。

たとえば、ユーザが画面を表示する際にかかった時間を追跡する場合、インストゥルメンテーションは次のようになります。

startTimer(event) {
    window.plugins.ADEUMMobilePlugin.startTimerWithName(data.name,
        (success) =&gt; {
            this.showAlert("startTimerWithName return: success");
        },
        (error) =&gt; {
            this.showAlert("startTimerWithName error:" + error);
        }
    );
}
stopTimer(event) {
    window.plugins.ADEUMMobilePlugin.stopTimerWithName(data.name,
        (success) =&gt; {
            this.showAlert("stopTimerWithName return: success");
        },
        (error) =&gt; {
            this.showAlert("stopTimerWithName error:" + error);
        }
    );
}
JS

Custom Metrics

カスタムメトリックをレポートすることもできます。 

reportMetricWithName を使用してカスタムメトリックを作成します。

  • reportMetricWithName(name, value, success, error) 

パラメータ

reportMetricWithName メソッドは、次のパラメータを使用します。

名前タイプ説明
namestringカスタムメトリックの名前。メトリック名には英数字を使用する必要があります。不正な文字は、ASCII 16 進値に置き換えられます。
valuenumber値が整数ではない場合は、エラーが返されます。
success機能ユーザ定義の成功コールバック。
error機能ユーザ定義のエラーコールバック。

たとえば、次のメソッドを使用してカスタムメトリックをレポートすることができます。

reportMetric(event, data) {
    window.plugins.ADEUMMobilePlugin.reportMetricWithName(data.name, parseInt(data.value),
        (success) =&gt; {
            this.showAlert("reportMetricWithName : success");
        },
        (error) =&gt; {
            this.showAlert("reportMetricWithName error:" + error);
        }
    );
};
JS

トピックパス(パンくずリスト)

トピックパスを使用すると、ユーザエクスペリエンスのコンテキストでクラッシュの場所を特定できます。問題が発生したときに、トピックパスを設定します。その後のある時点でアプリケーションがクラッシュした場合、トピックパスはクラッシュレポートとともに表示されます。各クラッシュレポートには、最近の 99 件のトピックパスが表示されます。

次の SDK API メソッドを使用して、トピックパスを作成して残します。

  • leaveBreadcrumb(breadcrumb, mode, success, error)

パラメータ

メソッド leaveBreadcrumb では、次のパラメータを使用します。

名前タイプ説明
breadcrumbstringクラッシュレポートおよびセッションに含める文字列。2048 文字で切り捨てられます。空の値は無視されます。
modenumber

トピックパスが表示される場所を決定するモードは次のとおりです。

  • 0:クラッシュのみ
  • 1:クラッシュおよびセッション用。

値が解析できない場合、モードはデフォルトでクラッシュします。

success機能ユーザ定義のコールバックの成功例。
error機能ユーザ定義のコールバックの失敗例。

次のコード例は、SDK API を使用して、トピックパスを残す方法を示しています。

breadcrumb(mode) {
      window.plugins.ADEUMMobilePlugin.leaveBreadcrumb( "breadcrumb1", mode,
     (success) =&gt; {
        this.showAlert("leaveBreadcrumb return: success");
      },
      (error) =&gt; {
        this.showAlert("leaveBreadcrumb error:" + error);
    }
)  
JS

カスタムユーザデータの追加

次のメソッドで役立つ任意の文字列キー/値のペアを設定し、後で削除することができます。

  • setUserData(key, value, success, error)

  • removeUserData(key, success, error)

パラメータ

次の表で、パラメータについて説明します。

名前タイプ説明
keystringキーと値のペアを識別するキー。
valuestringキーに関連付けられている値。
success機能ユーザ定義のコールバックの成功例。
error機能ユーザ定義のコールバックの失敗例。

次のコード例は、SDK API を使用してユーザデータを設定および削除する方法を示しています。

setCustomData(event, data) {
    window.plugins.ADEUMMobilePlugin.setUserData(data.name, data.value,
        (success) =&gt; {
            this.showAlert("setUserData return: success");
        },
        (error) =&gt; {
            this.showAlert("setUserData error:" + error);
        }
    );
};
removeUserData(event, key) {
    window.plugins.ADEUMMobilePlugin.removeUserData(key,
        (success) =&gt; {
            this.showAlert("removeUserData return: success");
        },
        (error) =&gt; {
            this.showAlert("removeUserData error:" + error);
        }
    );
}
JS

プログラムによるセッションの制御

デフォルトでは、ユーザが非アクティブになってからモバイルセッションが終了します。たとえば、ユーザがアプリケーションを開くと、セッションは開始され、ユーザが設定した期間にアプリケーションを使用しなくなった後にのみ終了します。ユーザがアプリケーションの再使用を開始すると、新しいセッションが開始されます。 

ただし、セッションの期間を定義するのに非アクティブな期間を設定する代わりに、次の API を使用して、セッションの開始と終了をプログラムで制御できます。

startNextSession(success, error)
JS

ADEUMMobilePlugin からメソッド startNextSession を呼び出すと、現在のセッションが終了し、新しいセッションが開始されます。API を使用すると、セッションを定義してフレーム化することができます。これにより、ビジネス目標と予想されるユーザフローをより厳密に合わせることができます。たとえば、API を使用して、製品の購入を追跡するセッションを定義したり、新しいユーザを登録したりすることができます。  

この API を過剰に使用すると、セッションが調整されます(過剰使用は 1 分あたり 10 コールを超えた場合になりますが、変更される可能性があります)。API を使用しない場合、セッションは、ユーザが非アクティブになった後、デフォルトの終了にフォールバックします。 

プログラムによって制御されるセッションの例

次の例では、現在のセッションが終了し、チェックアウトが行われると新しいセッションが開始されます。

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);
                      }
       );
}
JS

セッションフレームの開始と終了

セッションアクティビティに表示されるセッションフレームを作成するために、Cordova プラグインを使用できます。セッションフレームは、セッション中にユーザが実行している内容のコンテキストを提供します。この API を使用すると、ユーザ画面の命名方法が向上し、ビジネスコンテキスト内のユーザフローを記録できます。 

使用例

セッションフレームの一般的な使用方法は次のとおりです。

  • 1 つのページで複数の関数を実行し、個々の関数をより詳細に追跡する必要があります。
  • ユーザフローは、複数のページまたはユーザのインタラクションに及びます。たとえば、API を使用してセッションフレーム「Login」、「Product Selection」、および「Purchase」を作成して、ユーザが購入のためにフローを記録することができます。
  • ユーザの操作に基づいて動的情報をキャプチャし、オーダー ID などのセッションフレームに名前を付けることができます。

SessionFrame API

次の表に、セッションフレームで使用できる3つの方法を示します。つまり、startSessionFrame を使用してセッションフレームを開始してから、updateNameend を使用してセッションフレームの名前を変更し、終了します。 

メソッド
パラメータ
説明
startSessionFrame(name, success, error)
  • name (文字列):セッションフレームの名前。
  • success(関数):ユーザ定義の成功コールバック。
  • error(関数):ユーザ定義のエラーコールバック。

セッションフレームを開始して名前を付けるには、これを使用します。

このメソッドは window.plugins.ADEUMMobilePlugin から呼び出します。

updateName(name, success, error)
  • name (文字列):セッションフレームの名前。
  • success(関数):ユーザ定義の成功コールバック。
  • error (関数):ユーザ定義のエラーコールバック。

セッションフレーム名の名前を変更します。

ADEUMMobilePlugin オブジェクトからこのメソッドを呼び出します。

 


end(success, error)
  • success(関数):ユーザ定義の成功コールバック。
  • error (関数):ユーザ定義のエラーコールバック。

セッションフレームを終了します。 

ADEUMMobilePlugin オブジェクトからこのメソッドを呼び出します。

セッションフレームの例

次の例では、チェックアウトプロセス中にユーザアクティビティを追跡するためにセッションフレームが使用されます。

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) =&gt; {
                // 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) =&gt; {
                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) =&gt; { 
                console.log("Order has been placed and sessionFrame updated:" + this.orderId); 
            },
            (error) =&gt; { 
                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) =&gt; { 
                console.log("Order was completed and sessionFrame ended: " + success);
            },
            (error) =&gt; { 
                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) =&gt; { 
                console.log("Order was cancelled and sessionFrame ended: " + success);
            },
            (error) =&gt; { 
                console.log("Order was cancelled but sessionFrame couldn't be ended because of: " + error); 
            }
        );
    }
} // end of export class OrderPage
JS

スクリーンショットの設定および作成

デフォルトでは、モバイルスクリーンショットはエージェント側で有効になりますが、コントローラ側では無効になります。これらのスクリーンショットはコントローラの [Sessions Details] ダイアログに表示されます。プログラムで手動でスクリーンショットを取得するには、コントローラ UI でスクリーンショットを有効にし、次のスクリーンショット API を追加する必要があります。 


screenshot(event) {
     // make a call to plugin
     console.log("screenshot click handler");
      window.plugins.ADEUMMobilePlugin.takeScreenshot(

     (success) =&gt; {
        this.showAlert("screenshot return: success");
      },
      (error) =&gt; {
        this.showAlert("screenshot error:" + error);
      });
}
JS

これにより、個人情報を含むすべてがキャプチャされるため、スクリーンショットを作成するタイミングに注意する必要があります。 


スクリーンショットのブロックとブロック解除

コードブロックの実行中にスクリーンショットが作成されるのをブロックすることもできます。これにより、スクリーンショットのブロックを解除するまで、スクリーンショットの作成が一時的にブロックされます。これにより、ユーザがログインやアカウント画面などで個人データを入力する状況でのスクリーンショットの作成を停止できます。 

logInScreen(event) {
    // Block Screen while getting user input 
    window.plugins.ADEUMMobilePlugin.blockScreenshots(
        (success) =&gt; {
            console.log("blockScreenshots return: success");
            this.getUserInput();
            this.submitUserInput();
        },
        (error) =&gt; {
            console.log("blockScreenshots error:" + error);
         }
    );
    // Unblock screen and return to home page
    window.plugins.ADEUMMobilePlugin.unblockScreenshots(
        (success) =&gt; {
            console.log("unblockScreenshots return: success");
            this.homePage()
        },
        (error) =&gt; {
            console.log("unblockScreenshots error:" + error);
        }
    );
}
JS


ロギングの有効化とロギングレベルの設定

ロギングレベルを有効にして設定するには、メソッド loggingLevel を使用します。ロギングは、次のいずれかのレベルに設定できます。

ログ レベル説明
0なし(None)ログは表示されません。 This level disables logging.
1エラーエラーメッセージのみが表示されます。 This is the default logging level.
2[警告(Warn)]警告メッセージとエラーメッセージが表示されます。
3情報警告、エラー、および開発者に焦点を当てたメッセージが表示されます。
4[デバッグ(Debug)]エラー、警告、開発者情報、およびデバッグメッセージが表示されます。
5Verboseエラー、警告、開発者の情報、デバッグ、およびトラブルシューティング メッセージが表示されます。
6すべてサポート対象のすべてのログメッセージが表示されます。

ロギングを有効にするには、インストゥルメンテーションの構成でロギングレベルを設定します。たとえば、この例では、ロギングを有効にし、ログレベルを Info に設定します。

window.plugins.ADEUMMobilePlugin.initWithConfiguration(
    {
        "appKey": "<EUM_APP_KEY>",
        "loggingLevel": 3
     },
     (success) => {
        this.showAlert("initWithConfiguration return: success");
     },
     (error) => {
        this.showAlert("initWithConfiguration error:" + error);
     }
);
JS

Cordova SDK のドキュメント

Cordova SDK API リファレンスのマニュアルについては、最新の JSDoc のマニュアルまたは以下に記載されている以前のバージョンを参照してください。