Skip to content
Release: Australia · Updated: 2026-03-12 · Official documentation · View source

NowAnalyticsService protocol- iOS

The NowAnalyticsService protocol provides functions that enable you to configure analytics properties, user settings, and events for managing the collection of user analytics data.

An object conforming to this protocol is returned by sharedAnalyticsService. Use it in your application to perform API calls.

NameTypeDescription
trackingConsentBooleanFlag that indicates whether the user has consented to analytics tracking for the associated device. By default, devices are opted-out. Explicitly setting this value to `false` will immediately finish any ongoing session and delete the locally recorded data.Valid values: - true: User consented to anlaytics data being tracked on this device. - false: User denied data tracking.

Parent Topic:Mobile SDK - iOS

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

Adds an application event, such as a user reaching a specific level or screen, and enables the setting of custom properties on the event. These events appear on the dashboard in the order that they occurred.

These events appear in your analytics dashboard.

NameTypeDescription
named eventNameStringName of the event to add.
with propertiesArray

Optional. Custom property key-value pairs for the event. Property keys may not contain the dot ('.') or dollar ('$') signs. They will be trimmed.Supported value types:

  • Date
  • NSNull
  • NSNumber
  • Strings
  • URL

Note: The total size of the eventName, properties key and value should not exceed 300 bytes (per event). Strings are UTF-8 encoded. Events that exceed this limit are ignored.

TypeDescription
None 

The following example shows how to add a "Successful Login" event and an "Open Case" event with properties.

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

NowAnalyticsService - addScreenAction(named actionName: String)

Adds a custom action to the current screen. These actions appear in the user dashboard as part of the session data and describes a screen change in an application.

NameTypeDescription
named actionNameStringName of the action to add to the screen, such as `MyButtonClick`.Maximum length: 256 UTF-8 bytes
TypeDescription
None 
// Add event
NowAnalytics.sharedAnalyticsService.addEvent(named: "Successful Login")

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

Appends the specified item to the specified user property list.

NameTypeDescription
named propertyNameStringName of the user property list to append the listItem to.
listItemStringList item to append to the property.
TypeDescription
None 
// Append handled case to list
NowAnalytics.sharedAnalyticsService.appendToUserProperty(named: "Case Identifiers", listItem: "TASK-1")

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

Deletes all analytics data associated with the current user. This method also unsets the current active user and opts this device out of future tracking.

To set the current user, use the setUserId() method.

NameTypeDescription
completion@escaping \(\(\_ success: Bool\) -> Void\)Completion handler to execute after the analytics data is deleted. Return values for the completion handler: - Success: Returns a Boolean value of true. - Failure: Void - Failure may occur if the Usage Insights servers cannot be reached, as when there is no connectivity. If failure occurs, retry the method.
TypeDescription
None 
// Delete user data
NowAnalytics.sharedAnalyticsService.deleteCurrentUserData(completion: { (success) -> Void in
  if success {
    // deletion succeeded
  } else {
    // deletion failed
  }
})

NowAnalyticsService - incUserProperty(named propertyName: String, by value: Int)

Increments or decrements the value of the specified numeric property by the specified value.

NameTypeDescription
named propertyNameStringName of the user property to increment.
by valueIntegerValue to increment the property by. Enter a negative value to decrement the value.
TypeDescription
None 
// Increment the "Cases Handled" count
NowAnalytics.sharedAnalyticsService.incUserProperty(named: "Cases Handled", by: 2)

NowAnalyticsService - installJavascriptInterface(into webView: WKWebView)

Enables the calling of the methods in the SNAnalytics() API from within a WebView using JavaScript.

This method returns an SNMobileAnalytics object that is available in JavaScript, which exposes the native methods.

NameTypeDescription
webViewWKWebViewWeb view object in which to inject the JavaScript interface.
TypeDescription
ObjectSNMobileAnalytics
// 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(named propertyName: String)

Deletes the specified property for the current user.

To set the current user, use the setUserId() method.

NameTypeDescription
named propertyNameStringName of the user property to delete.
TypeDescription
None 
// Remove unnecessary property
NowAnalytics.sharedAnalyticsService.removeUserProperty(named: "Temp Cases")

NowAnalyticsService - setDelegate(_ delegate: NowAnalyticsServiceDelegate?)

Sets a weak reference for a delegate to receive notifications.

NameTypeDescription
delegateNowAnalyticsServiceDelegateOptional. Object that contains the reference to the delegate class.
// Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)
TypeDescription
None 

This example shows how to define a delegate class for 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?)

Sets the application's user ID for the current user. Pass nil to log out the current user.

NameTypeDescription
userIdStringOptional. Application-specific user identifier.To log the current user out, pass `nil`. The user ID must not contain HTML tags or any personal data such as name, email, or phone number. Maximum length: 256 UTF-8 bytes
TypeDescription
None 
// 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: [String: Any])

Sets multiple properties with the specified values for the current user. Properties can be anything that you want to track on the dashboard for a user.

You must call the setUserId() function before calling this function.

NameTypeDescription
userPropertiesArrayKey-value pairs of the user properties to set.Supported value types: - NSNumber - Strings - Date - URL - NSNull Key may not contain dots \('.'\) or dollar \('$'\) signs. Maximum length: - key: 256 characters - value: 1,000 characters
TypeDescription
None 
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(named propertyName: String, with value: Any?)

Sets the specified property with the specified value for the current user. You can define any property that makes sense for your application.

You must call the setUserId() function before calling this function.

NameTypeDescription
named propertyNameStringName of the user property to set. May not contain dots \('.'\) or dollar \('$'\) signs.Maximum length: 256 characters
with valueAnyValue to set the user property to.Supported value types: - Date - NSNull - NSNumber - Strings - URL Maximum length: 1,000 characters
TypeDescription
None 
// Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

NowAnalyticsService - startScreen(named screenName: String)

Logs the time when the associated screen first appears in the UI.

Call this method after the viewDidAppear(_:) method.

NameTypeDescription
named screenNameStringName of the screen to log the start time for, such as `WelcomeScreen`. This can be anything that you want to define as a screen and display/aggregate on an analytics dashboard.Maximum length: 256 UTF-8 bytes
TypeDescription
None 
// Mark the appearance starting time of a screen
// This method should be usually called from the viewDidAppear
NowAnalytics.sharedAnalyticsService.startScreen(named: "WelcomeScreen")