Guides

An entity that engages with an application is referred to as a user. A user can be linked to a device by their device ID. If a singular user has multiple devices, the user can be tracked across all devices by utilizing API calls.

User Endpoints

UXCam Data Access API provides two endpoint URLs for retrieving both qualitative (List User) and quantitative (Analyze User) data for users. The endpoint URLs are:

List User: https://api.uxcam.com/v2/user

Analyze User: https://api.uxcam.com/v2/user/analytics

User Data Attributes

For UXCam Data Access user APIs, all valid attributes that can be used for performing operations such as aggregations, filterings, and groupings based on their data type are listed in the table below.

Users Attribute Table

Attribute CategoryAttribute Data TypeAttribute NameDescription
DateTimeDateTimedate_rangeDateTime when the user used the app
DateTimeDateTimeuser_first_seen_onDateTime when the user used the app first
Devicestringapp_versionApp version on the device
Devicestringdevice_classClass of the device given by the device size
Devicestringdevice_idDevice Ids are randomly generated unique ids for user devices. For more detail [Link]
Devicestringdevice_manufacturerDevice manufacturers recorded within a given user. E.g. Samsung and motorola
Devicestringdevice_modelDevice name
Devicestringdevice_os_versionDevice OS version recorded within a given user
Devicestringdevice_platformPlatform (iOS or Android) of the user. The value is set to 1 for android users having a device OS as an ANDROID platform, and the value is set to 2 for iOS users having a device OS as an iOS platform.
Devicestringsdk_versionUXCam SDK version on app
EngagementIntegeruser_gesture_countTotal number of gestures by the user
EngagementIntegeruser_rage_gesture_countTotal number of rage gestures on the user
EngagementIntegeruser_responsive_gesture_countTotal number of responsive gestures by the user
EngagementIntegeruser_session_screen_countTotal number of screens visited by the user
EngagementIntegeruser_session_durationTotal time spent in seconds by the user
EngagementIntegeruser_unresponsive_gesture_countTotal number of unresponsive gestures by the user
Session Propertystringevent_nameEvent triggered by users on sessions
Session Propertylistsession_screen_listList of screens visited during the session
Session PropertyDateTime Stringsession_uploaded_monthDistribution of users by month (relevant to grouping parameter only)
Session PropertyDateTime Stringsession_uploaded_weekDistribution of users by week(Mon-Sun) (relevant to grouping parameter only)
Session PropertyDateTime Stringsession_uploadedon_dayDistribution of users by days (relevant to grouping parameter only)
Userstringdevice_cityCountry city name based on device IP address. For more details on IP Address [Link]
Userstringdevice_countryCountry name based on device IP address
UserJSONuser_custom_propertyAdditional properties attached for users on sessions
Userstringuser_nameRandomly assigned alias for users. Note: This is not the real user name, alias, or ID. For more detail [Link]
UserstringuxcamuseridUXCam User ID of user

List Users

A user list provides qualitative data, including details about the device, user interactions, personalized user properties, and location data.

Request Parameters

Now that you have explored the data attributes and query parameters, The list user endpoint supports the following query parameters as given in the URL structure below.

For more information on request parameters see the Query parameters section

Structure of API URL:

https://api.uxcam.com/v2/user?appid=<appid>&apikey=<apikey>&filters=<filters>&page=<page number>&page_size=<number of data in single request>

To authenticate the List event API, App ID and API key are required. See authentication for more details.

Example

Response Structure

The response is in JSON format and includes a data array with multiple objects enclosed in curly brackets. Each object can be thought of as a new row and is separated by a comma. Each object includes several properties, which are represented as key-value pairs.

The List user API provides information about a user in several key-value pairs grouped under different keys: user custom properties are under the "property" key, user device information is under the "device" key, user engagement metrics are under the "usage" key, and user location information is under the "location" key.

{

  "success": true,

  "data": [

    {

      "uxcamUserId": "60f7e1a43d4dcd370b7e0b02",

      "userId": "U#744",

      "url": "https://app.uxcam.com/app/60f6c0b8b97ba419120b82eb/users/list/1/60f7e1a43d4dcd370b7e0b02",

      "property": {

        "alias": "Garfield Gerlach",

        "gender": "Male",

        "language": "English",

        "age_group": "71-80",

        "acqn_source": "none",

        "exp_var_key": "test_3",

        "loyalty_card": "no",

        "kUXCam_UserIdentity": "U#744"

      },

      "usage": {

        "registeredOn": "2022-11-12T06:48:43Z",

        "lastseenOn": "2023-01-11T06:27:48Z",

        "totaluser": 12,

        "totaluserTime": 475.85600000000005,

        "totalGesture": 152,

        "screenCount": 92,

        "eventCount": 49,

        "rageGestureCount": 0,

        "responsiveGestureCount": 108,

        "unresponsiveGestureCount": 44

      },

      "location": {

        "countryCode": "NP",

        "city": "Kathmandu",

        "country": "Nepal"

      },

      "device": {

        "model": "SM-A525F",

        "deviceId": "ee294c9b1d063333",

        "platform": "android",

        "appVersion": "1.2",

        "osVersion": "13"

      }

    }

  ]

}

Example Requests

List users from the country USA:

https://api.uxcam.com/v2/user?appid=60f6c0b8b97ba419120b82eb&apikey=9c633412-927a-4f4e-87bc-386dc1e3a618&filters=[{"attribute":"device_country","operator":"equal","value":"USA"}]

Analyze Users

This endpoint for analyzing user data offers aggregated numerical data that can be utilized to create statistical graphs and gain valuable insights.

Request Parameters

This user analytics endpoint supports the following query parameters as given in the URL structure below.

  • pagination
  • filters
  • group_by
  • aggregation
  • comparison

For more information on request parameters see the Query parameters section.

Structure of API URL:

https://api.uxcam.com/v2/user/analytics?appid=<appid>&apikey=<apikey>&filters=<filters>&aggregation=<aggregation>&group_by=<groupings>&page=<page number>&page_size=<number of data in single request>

To authenticate the event analytics API, app id and API key are required. See authentication for more details.

Example

Response Structure

The user analytics API provides aggregated data of users based on the user’s query which is grouped by grouping attributes. It gives us all of the user aggregate data in the output so it can be used to plot statistical charts.

{
  "success": true,
  "data": [
    {
      "user_count": 2993,
      "session_new_users_count": 173,
      "avg_user_session_count": 16.686505020818025,
      "avg_user_session_duration": 1402.0168,
      "avg_user_rage_gesture_count": 3.4235447791656464,
      "avg_user_event_count": 201.1265409421177,
      "avg_user_session_screen_count": 257.78888072495715,
      "dashboard_link": "https://app.uxcam.com/app/60f6c0b8b97ba419120b82eb/users/list/1?date_range={\"o\": \"between_dates\", \"v\": {\"lower\": \"2022-12-24T08:51:21Z\", \"upper\": \"2023-01-23T08:51:21Z\"}, \"tb\": \"session\"}"
    }
  ]
}

Example

Example Requests

  • Usage for a given location compared to the past:

How many users are in a given country (for instance USA) for the app in the last month, and how did this change compared to the month before?

https://api.uxcam.com/v2/user/analytics?appid=60f6c0b8b97ba419120b82eb&apikey=9c633412-927a-4f4e-87bc-386dc1e3a618&filters=[{"attribute":"device_country","operator":"equal","value":"USA"}]&comparison=1
  • Users distribution by device manufacturer

What is the most commonly used device manufacturer observed in the generated users? Or what is the distribution of users by the device manufacturer for Jan 2023?

https://api.uxcam.com/v2/user/analytics?appid=60f6c0b8b97ba419120b82eb&apikey=9c633412-927a-4f4e-87bc-386dc1e3a618&filters=[{"attribute":"date_range","operator":"between_dates","value":{"lower":"2023-01-01","upper":"2023-01-20"}}]&group_by=[{"attribute":"device_manufacturer"}]&aggregation=[{"attribute":"user_count","operator":""}]