NowAnalyticsService プロトコル - iOS

Xanadu API リファレンス

Release

xanadu

ft:locale

ja-JP

ft:publication_title

Xanadu API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

NowAnalyticsService プロトコル - iOS

リリースバージョン: Xanadu

更新日 2024年08月01日

所要時間：15分

NowAnalyticsService プロトコルは、ユーザー分析データの収集を管理するための分析プロパティ、ユーザー設定、およびイベントを構成できる関数を提供します。

このプロトコルに準拠するオブジェクトは、 sharedAnalyticsService によって返されます。アプリケーションで使用して API 呼び出しを実行します。

表 : 1. 要件
名前	タイプ	Description (説明)
trackingConsent	ブーリアン	関連付けられたデバイスのアナリティクストラッキングにユーザーが同意したかどうかを示すフラグ。デフォルトでは、デバイスはオプトアウトされています。この値を `明示的に false` に設定すると、進行中のセッションがすぐに終了し、ローカルに記録されたデータが削除されます。有効な値： true:ユーザーは、このデバイスで分析データが追跡されることに同意しました。 false:ユーザーがデータ追跡を拒否しました。

NowAnalyticsService - addEvent(named eventName: String, with properties: [String: Any]?)

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

これらのイベントはアナリティクスダッシュボードに表示されます。

表 : 2. パラメーター
名前	タイプ	Description (説明)
名前付き eventName	文字列	追加するイベントの名前。
プロパティあり	アレイ	オプション。イベントのカスタムプロパティのキーと値のペア。プロパティキーにドット記号 ('.') またはドル記号 ('$') を含めることはできません。それらはトリミングされます。サポートされている値の型: 日付 NSヌル NSNumber 文字列 URL 注: eventName、プロパティキー、および値の合計サイズは、(イベントあたり) 300 バイトを超えてはなりません。文字列は UTF-8 でエンコードされます。この制限を超えるイベントは無視されます。

表 : 3. 返される内容
タイプ	説明
なし

次の例は、「ログイン成功」イベントと「ケースを開く」イベントをプロパティとともに追加する方法を示しています。

// Add event with properties
NowAnalytics.sharedAnalyticsService.addEvent(
  named: "Open Case", with: ["Screen Name": "Case",
                             "Case Number": "123",
                             "Case Priority": 5
])

NowAnalyticsService - addScreenAction(名前付き actionName: 文字列)

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

表 : 4. パラメーター
名前	タイプ	Description (説明)
名前付き actionName	文字列	画面に追加するアクションの名前 ( `MyButtonClick` など)。最大長:256 UTF-8 バイト

表 : 5. 返される内容
タイプ	説明
なし

// Add event
NowAnalytics.sharedAnalyticsService.addEvent(named: "Successful Login")

NowAnalyticsService - appendToUserProperty(named propertyName: String, listItem: String)

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

表 : 6. パラメーター
名前	タイプ	Description (説明)
名前付き propertyName	文字列	listItemを追加するユーザープロパティリストの名前。
リストアイテム	文字列	プロパティに追加するリストアイテム。

表 : 7. 返される内容
タイプ	説明
なし

// Append handled case to list
NowAnalytics.sharedAnalyticsService.appendToUserProperty(named: "Case Identifiers", listItem: "TASK-1")

NowAnalyticsService - deleteCurrentUserData(completion: @escaping ((_ success: Bool) -> Void))

現在のユーザーに関連付けられているすべてのアナリティクスデータを削除します。この方法では、現在アクティブなユーザーの設定も解除され、このデバイスは将来の追跡からオプトアウトされます。

現在のユーザーを設定するには、 setUserId() メソッドを使用します。

表 : 8. パラメーター
名前	タイプ	Description (説明)
完了	@escaping ((_ success: Bool) -> Void)	分析データが削除された後に実行する完了ハンドラー。完了ハンドラーの戻り値: 成功:ブール値 true を返します。障害:無効 - 接続がない場合など、Appsee サーバーに到達できない場合に障害が発生する可能性があります。エラーが発生した場合は、メソッドを再試行してください。

表 : 9. 返される内容
タイプ	説明
なし

// Delete user data
NowAnalytics.sharedAnalyticsService.deleteCurrentUserData(completion: { (success) -> Void in
  if success {
    // deletion succeeded
  } else {
    // deletion failed
  }
})

NowAnalyticsService - incUserProperty(名前付き propertyName:文字列、値:Int)

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

表 : 10. パラメーター
名前	タイプ	Description (説明)
名前付き propertyName	文字列	インクリメントするユーザープロパティの名前。
値別	整数	プロパティをインクリメントする値。値をデクリメントするには、負の値を入力します。

表 : 11. 返される内容
タイプ	説明
なし

// Increment the "Cases Handled" count
NowAnalytics.sharedAnalyticsService.incUserProperty(named: "Cases Handled", by: 2)

NowAnalyticsService - installJavascriptInterface(webView へ:WKWebView)

JavaScript を使用して WebView 内から SNAnalytics() API のメソッドを呼び出せるようにします。

このメソッドは、JavaScript で使用できる SNMobileAnalytics オブジェクトを返します。これにより、ネイティブメソッドが公開されます。

表 : 12. パラメーター
名前	タイプ	Description (説明)
Web ビュー	WKWebView	JavaScriptインタフェースを挿入するWebビュー・オブジェクト。

表 : 13. 返される内容
タイプ	説明
オブジェクト	SNMobileAnalytics

// Register JS object inside the web page
// This will create an object named 'SNMobileAnalytics' on JS that will have 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}))
NowAnalytics.sharedAnalyticsService.installJavascriptInterface(into: webView)

NowAnalyticsService - removeUserProperty (名前付き propertyName: 文字列)

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

現在のユーザーを設定するには、 setUserId() メソッドを使用します。

表 : 14. パラメーター
名前	タイプ	Description (説明)
名前付き propertyName	文字列	削除するユーザープロパティの名前。

表 : 15. 返される内容
タイプ	説明
なし

// Remove unnecessary property
NowAnalytics.sharedAnalyticsService.removeUserProperty(named: "Temp Cases")

NowAnalyticsService - setDelegate(_ delegate: NowAnalyticsServiceDelegate?)

代理人が通知を受信する弱参照を設定します。

表 : 16. パラメーター
名前	タイプ	Description (説明)
代理人	NowAnalyticsServiceDelegate	オプション。デリゲートクラスへの参照を含むオブジェクト。 `// Register delegate private var analyticsDelegate = NowAnalyticsDelegate() // Keep ref of delegate NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)`

表 : 17. 返される内容
タイプ	説明
なし

この例では、 NowAnalyticsServiceDelegate のデリゲートクラスを定義する方法を示します。

// Define a delegate class for NowAnalyticsServiceDelegate
class NowAnalyticsDelegate: NowAnalytics.NowAnalyticsServiceDelegate {
  func nowAnalyticsSessionShouldStart() -> Bool {
    // Session is about to start, return true to allow session to start
    return true
  }

  func nowAnalyticsSessionDidStart(_ sessionId: String) {
    // Session was started
  }

  func nowAnalyticsSessionShouldEnd(_ sessionId: String) -> Bool {
    // Session is about to end, return true to allow session to end
    return true
  }

  func nowAnalyticsSessionDidEnd(_ sessionId: String) {
    // Session was ended
  }

  func nowAnalyticsDidDetectScreen(_ screenName: String) -> String? {
    // Example of skipping specific screen detection
    if (screenName == "LoginViewController") {
      return nil
    }

    // Example of appending a prefix for every screen detected
    return "MyApp_" + screenName
  }
}

// Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)

NowAnalyticsService - setUserId(_ userId: 文字列?)

現在のユーザーのアプリケーションのユーザー ID を設定します。nil を渡すと、現在のユーザーがログアウトされます。

表 : 18. パラメーター
名前	タイプ	説明
userId	文字列	オプション。アプリケーション固有のユーザー識別子。現在のユーザーをログアウトさせるには、 `nil` を渡します。ユーザー ID には、HTML タグや、名前、メール、電話番号などの個人データを含めることはできません。最大長:256 UTF-8 バイト

表 : 19. 返される内容
タイプ	説明
なし

// Add several properties at once
NowAnalytics.sharedAnalyticsService.setUserProperties([
  "Cases Handled": 100,
  "Last Login": Date(),
  "Is Remote": true,
  "Profile URL": URL(string: "https://www.servicenow.com")!
])

NowAnalyticsService - setUserProperties(_ userProperties: [文字列:任意])

現在のユーザーに対して、指定された値で複数のプロパティを設定します。プロパティは、ユーザーのダッシュボードで追跡するものであれば何でもかまいません。

この関数を呼び出す前に、 setUserId() 関数を呼び出す必要があります。

表 : 20. パラメーター
名前	タイプ	Description (説明)
ユーザープロパティ	アレイ	設定するユーザープロパティのキーと値のペア。サポートされている値の型: NSNumber 文字列日付 URL NSヌルキーにドット ('.') またはドル記号 ('$') を含めることはできません。最大長: キー:256 文字値:1,000 文字

表 : 21. 返される内容
タイプ	説明
なし

import NowAnalytics

// Initialize the Analytics SDK
NowAnalytics.configure(for: URL(string: "https://my.instance.service-now.com")!)

// Enable tracking consent
NowAnalytics.sharedAnalyticsService.trackingConsent = true

// Set User Id for proper identification
NowAnalytics.sharedAnalyticsService.setUserId("John Doe")

// Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

// Add several properties at once
NowAnalytics.sharedAnalyticsService.setUserProperties([
    "Cases Handled": 100,
    "Last Login": Date(),
    "Is Remote": true,
    "Profile URL": URL(string: "https://www.servicenow.com")!
])

NowAnalyticsService - setUserProperty(名前付き propertyName:文字列、値:任意?)

現在のユーザーの指定されたプロパティに指定された値を設定します。アプリケーションに適した任意のプロパティを定義できます。

この関数を呼び出す前に、 setUserId() 関数を呼び出す必要があります。

表 : 22. パラメーター
名前	タイプ	Description (説明)
名前付き propertyName	文字列	設定するユーザープロパティの名前。ドット ('.') またはドル記号 ('$') を含めることはできません。最大長:256 文字
値あり	任意	ユーザープロパティを設定する値。サポートされている値の型: 日付 NSヌル NSNumber 文字列 URL 最大長：1,000 文字

表 : 23. 返される内容
タイプ	説明
なし

// Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

NowAnalyticsService - startScreen(named screenName: String)

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

このメソッドは、 viewDidAppear(_:) メソッドの後に呼び出します。

表 : 24. パラメーター
名前	タイプ	Description (説明)
名前付き screenName	文字列	開始時間をログに記録する画面の名前 ( `WelcomeScreen` など)。これは、画面として定義し、アナリティクスダッシュボードに表示/アグリゲートするものであれば何でもかまいません。最大長:256 UTF-8 バイト

表 : 25. 返される内容
タイプ	説明
なし

// Mark the appearance starting time of a screen
// This method should be usually called from the viewDidAppear
NowAnalytics.sharedAnalyticsService.startScreen(named: "WelcomeScreen")