NowAnalyticsSDK インターフェイス: Android

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：16分

    • NowAnalyticsSDK インターフェイスには、ユーザーアナリティクスデータの収集を管理するためのアナリティクスプロパティ、ユーザー設定、およびイベントを構成できる関数が用意されています。

    表 : 1. プロパティ
    名前 タイプ 説明
    構成 NowServiceConfiguration サービスに関連付ける構成。

    NowAnalyticsSDK:addEvent(eventName:String)

    ユーザーが特定のレベルまたは画面に到達するなどのアプリケーションイベントを追加します。これらのイベントは、発生した順にダッシュボードに表示されます。

    表 : 2. パラメーター
    名前 タイプ 説明
    名前付きイベント名 文字列 追加するイベントの名前。
    表 : 3. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出してアプリケーションイベントを追加する方法を示しています。

    // Add event
NowAnalyticsSDK.getAnalyticsService().addEvent("Successful Login")

    NowAnalyticsSDK:addEvent(eventName: String, props: MutableMap<String, Any>)

    ユーザーが特定のレベルまたは画面に到達するなどのアプリケーションイベントを追加し、イベントのカスタムプロパティの設定を有効にします。これらのイベントは、発生した順にダッシュボードに表示されます。

    表 : 4. パラメーター
    名前 タイプ 説明
    eventName 文字列 追加するイベントの名前。
    プロパティ ミュータブルマップ イベントのカスタムプロパティのキーと値のペア。

    イベント名、プロパティキー、および値の合計サイズは、プロパティあたり 300 バイトを超えることはできません。この制限を超えるプロパティは無視されます。プロパティ キーにドット記号 ('.') またはドル記号 ('$') を含めることはできません。含まれる場合はトリミングされます。文字列は UTF-8 でエンコードされます。

    サポートされている値タイプ:
    • 整数
    • 倍精度
    • 浮動小数点数
    • 文字列
    • URL
    • ブール
    • 日付
    表 : 5. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して、イベントのカスタムプロパティを含むアプリケーションイベントを追加する方法を示しています。

    // Add event with properties
NowAnalyticsSDK.getAnalyticsService().addEvent("Open Case",
  mutableMapOf(
    "Screen Name" to "Case",
    "Case Number" to 123,
    "Case Priority" to 5
  )
)

    NowAnalyticsSDK:addScreenAction(actionName:String)

    カスタムアクションを追加します。これらのアクションは、セッションデータの一部としてユーザーダッシュボードに表示され、アプリケーションの画面変更について説明します。

    表 : 6. パラメーター
    名前 タイプ 説明
    actionName 文字列 画面に追加するアクションの名前 ( MyButtonClick など)。
    表 : 7. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して現在の画面にカスタムアクションを追加する方法を示しています。

    // Add a custom action to the current screen
NowAnalyticsSDK.getAnalyticsService().addScreenAction("MyButtonClick")

    NowAnalyticsSDK:appendToUserProperty(propertyName: String, item: String)

    指定されたアイテムを指定されたユーザープロパティリストに追加します。

    表 : 8. パラメーター
    名前 タイプ 説明
    propertyName 文字列 リストアイテムを追加するユーザープロパティの名前。
    item 文字列 プロパティに追加するリストアイテム。
    表 : 9. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して、指定されたリストにケースを追加する方法を示しています。

    // Append handled case to list
NowAnalyticsSDK.getAnalyticsService().appendToUserProperty("Case Identifiers", "TASK-1")

    NowAnalyticsSDK - configure(instanceURL: URL, configureCallbacks: ConfigureCallbacks?)

    指定された ServiceNow インスタンス URL と NowAnalytics へのコールバックを構成します。

    このメソッドが呼び出されると、関連付けられた ServiceNow インスタンスから実際の構成がフェッチされ、自動的に同期されます。

    表 : 10. パラメーター
    名前 タイプ 説明
    インスタンス URL URL NowAnalyticfs サービスに関連付ける ServiceNow インスタンスの URL。
    configureCallback ConfigureCallback オプション。ServiceNowインスタンスとの通信中にエラーが発生するたびに実行するコールバック。このコールバックは、任意の時点で呼び出すことができ、複数の理由で複数回呼び出すことができます。
    表 : 11. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して指定されたインスタンスを構成する方法を示しています。

    // Init NowAnalytics after NowSDK is initialized
NowAnalyticsSDK.getAnalyticsService().configure(URL("https://my.instance.service-now.com"),
  // Optional - pass callback
  object: ConfigureCallbacks {
    override fun onFail(e: Exception) {
      // configuration failed
    }

    override fun onSuccess() {
      // configuration succeeded
    }
  }
)

    NowAnalyticsSDK:deleteCurrentUserData()

    現在のユーザーのすべてのローカルデータとリモートデータを削除します。

    また、この方法では、現在のアクティブユーザーの設定が解除され、このデバイスが今後のアナリティクスの追跡から除外されます。
    注:
    このメソッドは、SNAnalytics サーバーへの同期呼び出しを実行します。したがって、これはサイドスレッドで実行することをお勧めします。
    表 : 12. パラメーター
    名前 タイプ 説明
    なし
    表 : 13. 返される内容
    タイプ 説明
    ブール 削除が成功したかどうかを示すフラグ。
    可能な値：
    • true:削除に成功しました。
    • false:削除に失敗しました。接続がない場合など、SNAnalytics サーバーに到達できない場合、エラーが発生することがあります。メソッドを再試行する必要があります。

    次のコード例は、この関数を呼び出して現在のユーザーのデータを削除する方法を示しています。

    // Delete user data
NowAnalyticsSDK.getAnalyticsService().deleteCurrentUserData()

    NowAnalyticsSDK:getTrackingConsent()

    現在のユーザーの同意応答をアナリティクストラッキングに返します。

    表 : 14. パラメーター
    名前 タイプ 説明
    なし
    表 : 15. 返される内容
    タイプ 説明
    ブール 現在のユーザーがデータの収集に同意したかどうかを示すフラグ。
    可能な値：
    • true:ユーザーはデータの収集に同意しました。
    • false:ユーザーはデータの収集をオプトアウトしました。

    次のコード例は、この関数を呼び出して、分析追跡に対する現在のユーザーの同意応答を要求する方法を示しています。

    // Get the current user tracking consent value
val curUserConsent = NowAnalytics.sharedAnalyticsService.getTrackingConsent()

    NowAnalyticsSDK:incUserProperty(propertyName: String, value: Double)

    指定された数値プロパティの値を指定された値だけインクリメントまたはデクリメントします。

    表 : 16. パラメーター
    名前 タイプ 説明
    propertyName 文字列 インクリメントするユーザープロパティの名前。
    値 倍精度 プロパティをインクリメントする値。値をデクリメントするには、負の値を入力します。
    表 : 17. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出す方法を示しています。

    // Increment numeric_property_name by one
NowAnalyticsSDK.getAnalyticsService().incUserProperty("numeric_property_name", 1.0)

// Decrement numeric_property_name by one
NowAnalyticsSDK.getAnalyticsService().incUserProperty("numeric_property_name", -1.0)

    NowAnalyticsSDK:installJavascriptInterface(webView: WebView)

    JavaScript を使用して、{@link android.webkit.WebView} 内から javaScript.SNMobileAnalytics メソッドを呼び出すことができるようにします。

    表 : 18. パラメーター
    名前 タイプ 説明
    webビュー WKWebView 添付先の {@link android.webkit.WebView}。
    表 : 19. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して javaScript.SNMobileAnalytics メソッドの呼び出しを有効にする方法を示しています。

    // Register JS object inside the web page
// This creates an object called 'SNMobileAnalytics' on JS that has the following methods:
// SNMobileAnalytics.setUserId(userId)                 
//   example: SNMobileAnalytics.setUserId("John Doe")
// SNMobileAnalytics.startScreen(screenName)
//   example: SNMobileAnalytics.startScreen("WelcomeScreen")
// SNMobileAnalytics.addScreenAction(actionName)
//   example: SNMobileAnalytics.addScreenAction("MyButtonClick")
// SNMobileAnalytics.addEvent(eventName, properties)
//   example: SNMobileAnalytics.addEvent("Successful Login")
//                                                               
SNMobileAnalytics.addEvent("Successful Login", JSON.stringify({"Screen Name": "Case", "Case Number": "123", "Case Priority": 5}))
NowAnalyticsSDK.getAnalyticsService().installJavascriptInterface(webView)

    NowAnalyticsSDK:removeUserProperty(propertyName:String)

    現在のユーザーの指定されたプロパティを削除します。

    表 : 20. パラメーター
    名前 タイプ 説明
    propertyName 文字列 削除するユーザープロパティの名前。
    表 : 21. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して "Temp Cases" プロパティを削除する方法を示しています。

    // Remove unnecessary property
NowAnalyticsSDK.getAnalyticsService().removeUserProperty("Temp Cases")

    NowAnalyticsSDK:setListener(nowAnalyticsListener:NowAnalyticsListener?)

    セッションの変更や自動画面検出などの NowAnalytics のイベントにリスナーを設定します。

    注:
    このメソッドを呼び出すたびに、リスナーがオーバーライドされます。
    表 : 22. パラメーター
    名前 タイプ 説明
    nowAnalyticsリスナー NowAnalyticsリスナー NowAnalytics がセッションイベントについて通知するインターフェイス。
    • onNowAnalyticsScreenDetected:NowAnalytics が画面を自動的に検出したときに呼び出されます。
    • onNowAnalyticsSessionEnded:セッションの終了後に呼び出されます。
    • onNowAnalyticsSessionEnding:セッションが終了する直前に呼び出され、セッションが終了しないようにすることができます。
    • onNowAnalyticsSessionStarted:セッションが開始されたときに呼び出されます。
    • onNowAnalyticsSessionStarting:セッションが開始される直前に呼び出され、セッションが開始されないようにすることができます。
    表 : 23. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して NowAnalyticsListener() を設定する方法を示しています。

    // From anywhere in the code you can register the delegate
NowAnalyticsSDK.getAnalyticsService().setListener(NowAnalyticsListener())

    NowAnalyticsSDK:setTrackingConsent(consentGiven:Boolean)

    アナリティクストラッキングに対する現在のユーザーの同意応答を設定します。

    表 : 24. パラメーター
    名前 タイプ 説明
    consentGiven ブール アナリティクスの追跡に対する現在のユーザーの同意を示すフラグ。
    有効な値：
    • true:ユーザーは自分のデータが追跡されることに同意しました。
    • false:ユーザーはデータの追跡をオプトアウトしました。
    表 : 25. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して、現在のユーザーの同意応答を分析追跡に設定する方法を示しています。

    // Enable tracking consent
NowAnalyticsSDK.getAnalyticsService().setTrackingConsent(true)

    NowAnalyticsSDK:setUserId(userId:文字列)

    アプリケーション固有のユーザー識別子を設定します。現在のユーザーをログアウトするには、nil を渡します。

    表 : 26. パラメーター
    名前 タイプ 説明
    userId 文字列 アプリケーション固有の一意のユーザー識別子。この識別子は、ダッシュボードでそのユーザーのレポートを集計するために使用されます。
    表 : 27. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して、アプリケーション固有のユーザー識別子を "John Doe" に設定する方法を示しています。

    // Set User Id for proper identification
NowAnalyticsSDK.getAnalyticsService().setUserId("John Doe")

    NowAnalyticsSDK:setUserProperties(userProperties: MutableMap<String, Any>)

    現在のユーザーに対して、指定された値を持つ複数のプロパティを設定します。ユーザーのダッシュボードで追跡する任意のプロパティを指定できます。

    現在のユーザーを設定するには、 NowAnalyticsSDK:setUserId(userId:文字列) 関数を呼び出します。

    表 : 28. パラメーター
    名前 タイプ 説明
    userProperties ミュータブルマップ 設定するユーザープロパティのキーと値のペア。
    サポートされている値タイプ:
    • [Number (番号)]
    • 文字列
    • 日付
    • URL
    • Null
    表 : 29. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して現在のユーザーの複数のプロパティを設定する方法を示しています。

    // Add several properties at once
NowAnalyticsSDK.getAnalyticsService().setUserProperties(
  mutableMapOf(
    "Cases Handled" to 100,
    "Last Login" to Date(),
    "Is Remote" to true,
    "Profile URL" to URL("https://www.servicenow.com")
  )
)

    NowAnalyticsSDK:setUserProperty(propertyName:文字列、propertyValue:任意)

    指定されたプロパティを現在のユーザーの指定された値で設定します。ユーザーのダッシュボードで追跡する任意のプロパティを指定できます。

    現在のユーザーを設定するには、 NowAnalyticsSDK:setUserId(userId:文字列) 関数を呼び出します。

    表 : 30. パラメーター
    名前 タイプ 説明
    propertyName 文字列 設定するユーザープロパティの名前。
    値 任意 ユーザープロパティを設定する値。
    サポートされている値タイプ:
    • [Number (番号)]
    • 文字列
    • 日付
    • URL
    • Null
    表 : 31. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して、現在のユーザーのプロパティ "Role" を "Admin" に設定する方法を示しています。

    // Set the "Role" property of the user to "Admin"
NowAnalyticsSDK.getAnalyticsService().setUserProperty("Role", "Admin")

    NowAnalyticsSDK:startScreen(screenName:String)

    関連する画面が UI に最初に表示された時刻をログに記録します。

    通常、このメソッドはアクティビティの onResume() メソッドから呼び出します。

    表 : 32. パラメーター
    名前 タイプ 説明
    名前付き screenName 文字列 開始時間を記録する画面の名前 ( WelcomeScreen など)。これは、画面として定義し、アナリティクスダッシュボードに表示/アグリゲートする任意のものにすることができます。
    表 : 33. 戻り値
    タイプ 説明
    なし

    次のコード例は、この関数を呼び出して「WelcomeScreen」の表示の開始時間を設定する方法を示しています。

    // Mark the appearance starting time of a screen
// This method should be usually called from the onResume() method
NowAnalyticsSDK.getAnalyticsService().startScreen("WelcomeScreen")