---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# SNAnalytics - Client

# SNAnalytics - Client {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

The SNAnalytics API provides methods to push custom analytics data (events, pages, and user properties) to the User Experience Analytics for Service Portal dashboard.

User Experience Analytics for Service Portal provides dashboard views for monitoring the key performance indicators (KPIs) of web applications built on Service Portal. You can use these insights to optimize your portal. For example, User Experience Analytics tracks when a user orders a catalog item or views a knowledge article. You can use this data to infer which items or articles are the most popular among users.

To access this API, the Service Portal Analytics (com.glide.service-portal.analytics) plugin
must be activated on the instance. In addition, within your application, you must import the
snAnalytics Angular service, such as:  

    <client_script><![CDATA[function($rootScope, $scope, $window, $timeout, spUtil, $sce, spModal, $uibModal, $location, cabrillo, snAnalytics)

For additional information, see [User Experience Analytics for Service
Portal](https://www.servicenow.com/docs/access?context=sp-analytics&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US).

## SNAnalytics - addEvent(Object payload) {#ariaid-title2}

Stores the specified event information in the analytics data store.
Events are actions performed by a user, such as clicking a button or submitting a form.
Call this method within your web-page widget whenever you want to capture a user action.
These events then automatically appear on the associated user session timeline and User
Experience Analytics dashboard.  
The following is an example of a payload passed in an addEvent() call:

    var payload= {};
    payload.name = "Manage Account";
    payload.data = {};
    payload.data["Function Name"] = c.data.function_name;
    payload.data["User Type"] = c.data.user_type;
    payload.data["Company"] = c.data.company_name;
    snAnalytics.addEvent(payload);

The screen capture below shows the information that appears on the analytics dashboard for
the event "Manage Account." The timeline at the top represents the number of times that the
event occurred. The pie charts below the timeline reflect the properties that were captured
in the addEvent() call.

If you want to capture when users access a web page, use the [SNAnalytics - startPage(String name, String description)](https://servicenow-prod.fluidtopics.net/5P4lnhVfWN2q7Hg_~FCEuQ#SNAnaly-startPage_S_S "Saves the name and description of a page in the analytics data store.") method instead of this method.
{#SNAnaly-addEvent_O__table_u1m_5gr_z4b__entry__3}

| Name | Type | Description |
|-|-|-|
| payload | Object | Event to store in the analytics data store. Data type: Object "payload": { "data": [Array], "name": String } |
| payload.data | Array Each element can be a string (case-sensitive), boolean, number, or date. | Optional. Name-value pairs of custom event properties. These properties can be any values that you want to track and see on the analytics dashboard. They appear under the associated event timeline on the analytics dashboard. The Page Id property always appears first on the dashboard for all base system events, and all other properties are sorted alphabetically. If no properties are required for an event, only an event timeline appears on the analytics dashboard. Properties can be added at a later time. The following values are automatically converted by this method: * String value of "yes": Boolean value of "true" * String value of "no": Boolean value of "false {#SNAnaly-addEvent_O__ul_xsm_2kw_ksb} Default value: Null |
| payload.name | String | Descriptive name of the event. Special characters are not allowed. Maximum length: The length of the event name and value cannot exceed 300 bytes. |
[Table 1. Parameters]

{#SNAnaly-addEvent_O__table_u1m_5gr_z4b} {#SNAnaly-addEvent_O__table_v1m_5gr_z4b__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 2. Returns]

{#SNAnaly-addEvent_O__table_v1m_5gr_z4b}  
The following example shows how to call the addEvent() method during
initialization of a widget.

    function initialize() {
      c.options.glyph = c.options.glyph || 'search';
      c.options.title = c.options.title || c.data.searchMsg;
      c.options.color = c.options.color || "default";
      c.searchTerm = c.data.q;
      c.searchQuery = "";
      c.pageID = $scope.page && $scope.page.id;
      c.showSuggestions =  c.data.searchTypeBehavior === "suggestions" && c.data.isSuggestionsEnabled === "true";
      c.suggestionsLimit = c.options.limit || "";
      c.latitude = null;
      c.longitude = null;
      c.isLocationTrackerDisabled = c.data.isLocationTrackerDisabled === "true";
      c.isTypeAheadEnabled = c.data.isTypeAheadEnabled === "true";

      c.sendAnalytics = function(type){
        var payload= {};
        payload.name = "Initiate Search";
        payload.data = {};
        payload.data["Keyword"] = (type == 'User Entered' ? c.searchTerm : c.searchQuery);
        payload.data["Type"] = type;
        snAnalytics.addEvent(payload);
      };
    }

## SNAnalytics - appendToUserProperty(String name, String value) {#ariaid-title3}

Appends the specified string to the specified user string property in the analytics data store.
{#SNAnaly-appendUserProperty_S_S__table_apg_5fv_dpb__entry__3}

| Name | Type | Description |
|-|-|-|
| name | String or String\[\] | Name of the property to append the specified string to. Special characters are not allowed. Note: The associated property must be a string or string\[\]. Maximum length: The length of the property name and property value cannot exceed 300 bytes. |
| value | String | Value to append to the string property. The following values are automatically converted by this method: * String value of "yes": Boolean value of "true" * String value of "no": Boolean value of "false {#SNAnaly-appendUserProperty_S_S__ul_xsm_2kw_ksb} |
[Table 3. Parameters]

{#SNAnaly-appendUserProperty_S_S__table_apg_5fv_dpb} {#SNAnaly-appendUserProperty_S_S__table_bpg_5fv_dpb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 4. Returns]

{#SNAnaly-appendUserProperty_S_S__table_bpg_5fv_dpb}  
This example shows how to add <kbd class="ph userinput">television</kbd> to the `tags` property.

    snAnalytics.setUserProperties({
      level: 7,
      lastPurchase: new Date(),
      lastPurchaseId: '41563cd2-1666-4855-8c0d-b9ca778aed23',
      isPremium: true,
      tags: ['chair', 'table'],
    });

    // Append television to the tags property (now 'tags' will have 'chair', 'table', and 'television')
    snAnalytics.appendToUserProperty('tags', 'television');

## SNAnalytics - incUserProperty(String name, Number value) {#ariaid-title4}

Increments or decrements the specified user property value with the specified number
value in the analytics data store.
{#SNAnaly-incUserProp_S_N__table_pt1_syp_dpb__entry__3}

| Name | Type | Description |
|-|-|-|
| name | String | Name of the property to increment. Value is case-sensitive. Note: The associated property must be a number. |
| value | Number | Amount to increment the property by. If you enter a negative number, the value is decremented. |
[Table 5. Parameters]

{#SNAnaly-incUserProp_S_N__table_pt1_syp_dpb} {#SNAnaly-incUserProp_S_N__table_qt1_syp_dpb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 6. Returns]

{#SNAnaly-incUserProp_S_N__table_qt1_syp_dpb}  
The following example shows how to increment the property `Grace days` by
5.

    snAnalytics.incUserProperty('Grace days', 5)

## SNAnalytics - removeUserProperty(String name) {#ariaid-title5}

Removes the specified property for the current user from the analytics data
store.
In addition, the property no longer appears on the analytics dashboard.
{#SNAnaly-removeUserProperty_S__table_ikz_zbv_dpb__entry__3}

| Name | Type | Description |
|-|-|-|
| name | String | Name of the property to remove. Value is case-sensitive. |
[Table 7. Parameters]

{#SNAnaly-removeUserProperty_S__table_ikz_zbv_dpb} {#SNAnaly-removeUserProperty_S__table_jkz_zbv_dpb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 8. Returns]

{#SNAnaly-removeUserProperty_S__table_jkz_zbv_dpb}  
The following example shows how to remove the IsAdmin property.

    snAnalytics.removeUserProperty('IsAdmin');

## SNAnalytics - setUserProperties(Object properties) {#ariaid-title6}

Sets the specified properties with the specified values for the current user in the
analytics data store.
These properties are saved in the analytics data
store and appear on the user session details page as illustrated below. If a property
already exists in the analytics data store, the current value is overwritten with the new
value.{#SNAnaly-setUserProperties_O__user_properties_desc-p1-SNAnalytics}

{#SNAnaly-setUserProperties_O__user_properties_desc-p2-SNAnalytics}
{#SNAnaly-setUserProperties_O__table_iz1_41q_dpb__entry__3}

| Name | Type | Description |
|-|-|-|
| properties | Object Each element in this object can be a string, boolean, number, date, string\[\], or null. | Object that contains the name-value pairs of the user properties to set, such as: { level: 7, lastPurchase: new Date(), lastPurchaseId: '41563cd2-1666-4855-8c0d-b9ca778aed23', isPremium: true, tags: ['chair', 'table'], } The following values are automatically converted by this method: * String value of "yes": Boolean value of "true" * String value of "no": Boolean value of "false {#SNAnaly-setUserProperties_O__ul_xsm_2kw_ksb} |
[Table 9. Parameters]

{#SNAnaly-setUserProperties_O__table_iz1_41q_dpb} {#SNAnaly-setUserProperties_O__table_jz1_41q_dpb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 10. Returns]

{#SNAnaly-setUserProperties_O__table_jz1_41q_dpb}  
The following example shows how to set multiple properties for the current user.

    snAnalytics.setUserProperties({
      level: 7,
      lastPurchase: new Date(),
      lastPurchaseId: '41563cd2-1666-4855-8c0d-b9ca778aed23',
      isPremium: true,
      tags: ['chair', 'table'],
    });

## SNAnalytics - setUserProperty(String name, UserProperty value) {#ariaid-title7}

Sets the specified property with the specified value for the current user in the analytics data store.
These properties are saved in the analytics data
store and appear on the user session details page as illustrated below. If a property
already exists in the analytics data store, the current value is overwritten with the new
value.{#SNAnaly-setUserProperty_S_O__user_properties_desc-p1-SNAnalytics}

{#SNAnaly-setUserProperty_S_O__user_properties_desc-p2-SNAnalytics}
{#SNAnaly-setUserProperty_S_O__table_uj2_rfp_dpb__entry__3}

| Name | Type | Description |
|-|-|-|
| name | String | Name of the property to update. This name appears as the label for the property. For example, in the prior screenshot, Domain, Instance Name, Company, Role, and User Type are all name parameters. Special characters are not allowed. Maximum length: The length of the property name and property value cannot exceed 300 bytes. |
| value | UserProperty This value can be a string, boolean, number, date, string\[\], or null. | Value to set in the specified property. The following values are automatically converted by this method: * String value of "yes": Boolean value of "true" * String value of "no": Boolean value of "false {#SNAnaly-setUserProperty_S_O__ul_xsm_2kw_ksb} |
[Table 11. Parameters]

{#SNAnaly-setUserProperty_S_O__table_uj2_rfp_dpb} {#SNAnaly-setUserProperty_S_O__table_vj2_rfp_dpb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 12. Returns]

{#SNAnaly-setUserProperty_S_O__table_vj2_rfp_dpb}  
The following example shows how to set the property `Company`.

    snAnalytics.setUserProperty('Company', "ABC Company")

## SNAnalytics - startPage(String name, String description) {#ariaid-title8}

Saves the name and description of a page in the analytics data store.
This information appears in the user session timeline and on the analytics dashboard. Call this method within your custom widgets to track the pages visited by a user. You can also use this method to track user navigation within an individual page. For more information, see [Use User Experience
Analytics](https://www.servicenow.com/docs/access?context=use-user-exp-analytics&version=xanadu&pubname=xanadu-now-intelligence&ft:locale=en-US).  
Note:  
In general, portal pages are automatically tagged with this tracking capability. Use this method for custom scenarios, such as a single page custom widget in a wizard scenario.

{#SNAnaly-startPage_S_S__table_lmt_pl3_dpb__entry__3}

| Name | Type | Description |
|-|-|-|
| name | String | Descriptive name of the page or page section. Special characters are not allowed. |
| description | String | Optional. Description of the page to appear in the timeline and analytics dashboard. Default: name parameter value |
[Table 13. Parameters]

{#SNAnaly-startPage_S_S__table_lmt_pl3_dpb} {#SNAnaly-startPage_S_S__table_mmt_pl3_dpb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 14. Returns]

{#SNAnaly-startPage_S_S__table_mmt_pl3_dpb}  
The following example shows how to call the startPage() method.

    snAnalytics.startPage('login_view', 'Login');