POST/orgs/:org/datasets/:dataset/track

Track: Report & improve on actions

Report meaningful actions that occur during a customer journey which indicate an engaged customer. Many actions can be used to improve the results for that customers’ journey in both real-time and on return, some for improving results overall for all customers and other actions can be used for reporting.

Examples of meaningful actions for an e-commerce store might include:

  • add to collection - Whether a product has been added to cart, wishlist or other collections (and their name)
  • clicks - on both Visii generated recommendations and other product links
  • collection view (eg viewing wishlist) - this should include all items in wishlist, basket or purchase when viewed
  • filters - which filters the customer uses whilst searching
  • ratings (eg like, scoring)
  • scrolling events - important to limit rate of reporting by using milestones such as 25%, 50%, 75% and 100% of page viewed.
  • search inputs - any metadata that can be used to search and which results they subsequently click
  • split test group information - useful for reporting
  • time on page - important to limit rate of reporting by using milestones such as 1s, 5s, 10s, 30s, 1m

Note: Every situation is unique, so we advise considering your use-case and success metrics, sending as much data as you feel comfortable whilst respecting PII data. Please contact us if you have any questions.

Tracking across journeys requires the use of the v querystring parameter across Vision API endpoints. To minimise additional requests, using the v parameter allows tracking without additional requests to this endpoint. See Example below.

Input

URL

Field Type Required Value Description
org string yes

The organisation name.

dataset string yes

The dataset name.

v string yes

The vars querystring containing key-value pairs (`key:value` comma separated) of action information, support both specific and custom parameters. Details of [Vars Querystring](#vars-querystring) below.
For example: `v=a:exit,id:abc-123`

Vars Querystring

Field Type Required Value Description
a string yes

The action to track.


Values
  • init: Used to initiate and make a user known to Visii
  • add-cart: The user has added a product recommended by Visii to their cart
  • purchase: A user has purchased made a purchase with items included in the body. Only purchases including Visii results are included
s string no

The source of the tracking action, a name of widget, type of page and/or split test identifier.
For example: If running a split test, pdp-a and pdp-b could be used. If using a front-end widget, explore-widget.


Values
  • pdp: The action has taken place on a product details page
  • search: Action has taken place from a search widget or step
  • checkout: Action has taken place from the checkout
  • *: Any source useful for reporting can be used.
id string no

The result identifier of the result interacted with.

u string no

The user identifier to track a user across their session(s) if desired.

Body

Field Type Required Value Description
message string yes

An additional message that can be included. If nothing else to convey, set as 'track'.

data object no

Used to pass additional rich information for reporting, such as a list of products when a customer purchases. See [Examples](#examples).

Request

Note: my-dataset-api-token is a dataset token, not organisation token.

curl -X POST \
     -H "Authorization: token my-dataset-api-token" \
     -H "Accept: application/vnd.visii.v2+json" \
     -d '{"message":"track"}' \
     "https://api.visii.com/orgs/my-org/datasets/my-dataset/track?v=a:purchase,u:xxx,id:abc123,resultIndex:4"

Response

Field Type Required Value Description
status string yes

The status of the response.

HTTP/1.1 200 OK
{
  "status": "ok"
}

Examples

Exit

  1. A user lands on a product page (id: aa-b1) - with a unique identifier of xxx123, used by the site to track users over multiple visits. This is generated or read from a cookie.
  2. When requesting results, depending on where the results are rendered, two options are available:
    • Rendering Client-side: A request to Vision Similar is made with v variable is set to include the user id:
      /orgs/:org/datasets/:dataset/similar?id=aa-b1&v=u:xxx123&s:pdp
    • Rendering Server-side: Once the page is loaded with results, client-side request to track with action/a set to init will inform Visii of the user:
      /orgs/:org/datasets/:dataset/track?v=a:init,s:pdp,u:xxx123
  3. The user clicks a Visii result. This is meaningful and part of the conversion funnel.
    A client or server side request to track with action exit with resultIndex set to the item they have chosen:
    /orgs/:org/datasets/:dataset/track?v=a:exit,s:pdp,u:xxx123,id:aa-b2

Purchase

Continuing from above example - the user has been exited from another product page.

  1. A user lands on a product page (id: aa-b2) - with the same user ID xxx123 which is read from a cookie.
  2. The user adds the product to their cart. This is meaningful and part of the conversion funnel.
    A client or server side request to track with action set to add-cart:
    /orgs/:org/datasets/:dataset/track?v=a:add-cart,s:pdp,u:xxx123,id:aa-b2
  3. At some point in the future, the user makes a purchase. This is meaningful as it is the end of the conversion funnel.
    A client or server side request to track with action set to add-cart:
    /orgs/:org/datasets/:dataset/track?v=a:purchase,u:xxx123,id:aa-b2

Body:

{
  "message": "purchase",
  "data": [
    {
      "id": "aa-b1",
      "value": 59.99,
      "currency": "EUR"
    },
    {
      "id": "xx-y1",
      "value": 24.99,
      "currency": "EUR"
    }
  ]
}

UI Testing

Including information about the environment, widgets or behaviour of a user can be used to see in reports and improve results.

  1. The user scrolls through the paginated Visii results. This is meaningful as it suggests the first page of results are not suitable for them.
    A client-side request to track with action change-results and resultIndex set to the index of the first result they have paged in view:
    /orgs/:org/datasets/:dataset/track?v=a:change-results,s:pdp,u:xxx123&id:aa-b1,resultIndex:8
  2. Two versions of a widget are being tested can be compared by providing a different source.
    A client-side request to track with source widget-a:
    /orgs/:org/datasets/:dataset/track?v=a:change-results,s:widget-a,u:xxx123,id:aa-b1

Visii Analytics script

Many users are used with integrating Google Analytics in their applications. That is why, for ease of use we also provide a va.js script that can be inserted into your page and a track function to call whenever you have analytics data you think Visii could use.

!function(){var a=window.visii=window.visii||[];a.invoked?window.console&&console.error&&console.error("Visii analytics snippet was added twice."):(a.invoked=!0,a.track=function(){var e=Array.prototype.slice.call(arguments);return a.push(e),a},a.load=function(e){var o=document.createElement("script");o.type="text/javascript",o.async=!0;var i="https://cdn.visii.com/visii.com/va"+("function"==typeof window.fetch?"":"p")+".js";o.src=i;var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(o,t),a.config=e},a.load({
  organisation:"<organisation>",
  dataset:"<dataset>",
  token:"<token>",
  userCookie:"<user-cookie>"
}),a.track("page-load"))}();

Replace in the above script your dataset details:

Field Type Required Value Description
organisation string yes

The organisation name.

dataset string yes

The dataset name.

token string yes

The dataset API token.

user-cookie string no

The cookie name that contains an user identifier.

Usage

To send analytics to Visii, just call the track function:

Field Type Required Value Description
event-name string yes

The event name.

data object no

Details associated with the event.

window.visii.track("event-name", dataObject);

The track function is using internally the /track endpoint described above, so all examples shown there can also be used when using the va script.