NowAnalyticsService プロトコル:iOS

Zurich API リファレンス

Release

zurich

ft:locale

ja-JP

ft:publication_title

Zurich API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

NowAnalyticsService プロトコル:iOS

リリースバージョン: Zurich

更新日 2025年07月31日

所要時間：14分

NowAnalyticsService プロトコルは、ユーザーアナリティクスデータの収集を管理するためのアナリティクスプロパティ、ユーザー設定、およびイベントを構成できる機能を提供します。

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

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

NowAnalyticsService - addEvent(名前付きイベント名:文字列、プロパティ:[文字列:任意]?)

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

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

表 : 2. パラメーター
名前	タイプ	説明
名前付きイベント名	文字列	追加するイベントの名前。
プロパティあり	アレイ	オプション。イベントのカスタムプロパティのキーと値のペア。プロパティキーにドット記号 ('.') またはドル記号 ('$') を含めることはできません。それらはトリミングされます。サポートされている値タイプ: 日付 NSNull 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: String)

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

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

表 : 5. 戻り値
タイプ	説明
なし

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

NowAnalyticsService - appendToUserProperty(名前付きプロパティ名:文字列、listItem:文字列)

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

表 : 6. パラメーター
名前	タイプ	説明
名前付きプロパティ名	文字列	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. パラメーター
名前	タイプ	説明
完了	@escaping ((_ success: Bool) -> Void)	アナリティクスデータが削除された後に実行する補完ハンドラー。補完ハンドラーの戻り値: 成功:ブール値 true を返します。失敗:無効 - 接続がない場合など、ユーザーエクスペリエンスアナリティクスサーバーに到達できない場合、エラーが発生する可能性があります。エラーが発生した場合は、メソッドを再試行してください。

表 : 9. 戻り値
タイプ	説明
なし

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

NowAnalyticsService - incUserProperty(名前付きプロパティ名:文字列、値別:Int)

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

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

表 : 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. パラメーター
名前	タイプ	説明
webビュー	WKWebView	JavaScript インターフェイスを挿入する Web ビューオブジェクト。

表 : 13. 戻り値
タイプ	説明
オブジェクト	SNMobileアナリティクス

// 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(名前付きプロパティ名:文字列)

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

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

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

表 : 15. 戻り値
タイプ	説明
なし

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

NowAnalyticsService - setDelegate(_ 委任: NowAnalyticsServiceDelegate?)

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

表 : 16. パラメーター
名前	タイプ	説明
代理人	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: String?)

現在のユーザーのアプリケーションのユーザー 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. パラメーター
名前	タイプ	説明
userProperties	アレイ	設定するユーザープロパティのキーと値のペア。サポートされている値タイプ: NSNumber 文字列日付 URL NSNull キーにドット (「.」) またはドル記号 (「$」) を含めることはできません。最大長: キー: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(名前付きプロパティ名:文字列、値:任意?)

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

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

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

表 : 23. 戻り値
タイプ	説明
なし

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

NowAnalyticsService - startScreen(名前付き screenName: String)

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

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

表 : 24. パラメーター
名前	タイプ	説明
名前付き 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")