Cordova インストゥルメンテーションのカスタマイズ

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

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文字列EUM アプリケーションキー。
successfunctionchangeAppKey が成功したときに呼び出されるユーザー定義関数。
errorfunctionchangeAppKey が失敗したときに呼び出されるユーザー定義関数。
たとえば、新しいアプリケーションキーを取得して 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 つのタイプのデータを収集できます。
  • 情報ポイント
  • カスタムタイマー
  • Custom Metrics
  • ユーザ データ
  • トピックパス(パンくずリスト)

情報ポイント

情報ポイントを使用すると、独自のコードがどのように実行されているかを追跡できます。メソッドが呼び出される頻度と、beginCall を呼び出して実行される時間を確認できます。コールバック success または error が呼び出されると、情報ポイントを追跡するためのコールが終了します。
beginCall(name, functionName, args, success, error)
Parameters
次の表では、2 つの方法のパラメータについて説明します。
Nameタイプ説明
name文字列情報ポイントが記録されているファイルまたはモジュールの名前。
functionName文字列情報ポイントを追跡するために beginCall を呼び出す関数。
successfunctionユーザ定義のコールバックの成功例。
errorfunctionユーザ定義のコールバックの失敗例。
たとえば、次のようなコードを使用して情報ポイントを作成すると、メソッドの起動方法、および実行にかかる時間を決定できます。
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 メソッド startTimerstopTimer を使用します。
  • startTimerWithName(name, success, error)
  • stopTimerWithName(name, success, error)
Parameters
2 つのメソッドは、次のパラメータを使用します。
Nameタイプ説明
name文字列カスタムタイマーの名前。使用できる文字は [A-Za-z\s0-9] です。不正な文字は、ASCII 16 進値に置き換えられます。
successfunctionユーザ定義のコールバックの成功例。
errorfunctionユーザ定義のコールバックの失敗例。
たとえば、ユーザーが画面を表示するのにかかった時間を追跡する場合、インストルメンテーションは次のようになります。
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) 
Parameters

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

Nameタイプ説明
name文字列カスタムメトリックの名前。メトリック名には英数字を使用する必要があります。不正な文字は、ASCII 16 進値に置き換えられます。
value値が整数ではない場合は、エラーが返されます。
successfunctionユーザ定義の成功コールバック。
errorfunctionユーザ定義のエラーコールバック。
たとえば、次のメソッドを使用してカスタムメトリックをレポートすることができます。
reportMetric(event, data) {
    window.plugins.ADEUMMobilePlugin.reportMetricWithName(data.name, parseInt(data.value),
        (success) => {
            this.showAlert("reportMetricWithName : success");
        },
        (error) => {
            this.showAlert("reportMetricWithName error:" + error);
        }
    );
};

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

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

次の SDK API メソッドを使用して、トピックパスを作成して残します。
leaveBreadcrumb(breadcrumb, mode, success, error)
Parameters
leaveBreadcrumb メソッドは、次のパラメータを使用します。
Nameタイプ説明
breadcrumb文字列クラッシュレポートおよびセッションに含める文字列。2048 文字で切り捨てられます。空の値は無視されます。
mode

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

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

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

successfunctionユーザ定義のコールバックの成功例。
errorfunctionユーザ定義のコールバックの失敗例。
次のコード例は、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)
Parameters
次の表で、パラメータについて説明します。
Nameタイプ説明
key文字列キーと値のペアを識別するキー。
value文字列キーに関連付けられている値。
successfunctionユーザ定義のコールバックの成功例。
errorfunctionユーザ定義のコールバックの失敗例。
次のコード例は、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);
        }
    );
}

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

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

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

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

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

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) => {
                // 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

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

デフォルトでは、モバイルスクリーンショットはエージェント側で有効になりますが、コントローラ側では無効になります。これらのスクリーンショットは、コントローラの [セッションの詳細(Sessions Details)] ダイアログに表示されます。Session Detailsプログラムで手動でスクリーンショットを取得するには、コントローラ UI でスクリーンショットを有効にし、次のスクリーンショット API を追加する必要があります。
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);
      });
}
注: これにより、個人情報を含むすべてがキャプチャされるため、スクリーンショットを作成するタイミングに注意する必要があります。

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

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

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

ロギングレベルを有効にして設定するには、メソッド loggingLevel を使用します。ロギングは、次のいずれかのレベルに設定できます。
ログ レベル説明
0なしログは表示されません。このレベルはロギングを無効にします。
1エラーエラーメッセージのみが表示されます。これはデフォルトのロギングレベルです。
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);
     }
);