Access data points using REST-based Web services

    Overview

    Data points transferred from Composer and Player to the IntuiFace Data Tracking Hub can be accessed via a custom REST-based Web services query. The result is an XML or JSON-based response containing one or more data points.

    One use for this query is to create an Excel spreadsheet whose data is derived from it. Every refresh of the query will update charts based on that data. See this section for more information.

    Description of the Web Service

    Data points accessed via a Web services query can be downloaded in two formats:

    Required parameter:

    • credentialKey. To find it:

    All of the following parameters are optional:

    This optional parameter is unique to XML:

    • xlsx=true: causes the XML response to be formatted in a way that makes it readable by Excel.

    Example Web Service Requests

    • Simple working request providing JSON:
      This request will get all data points collected from all devices and for all experiences run on those devices for all time. The result will be in the JSON format.
      https://analytics.intuilab.com/analytics/export/json?credentialKey={YourCredentialKeyHere}
    • More complex request providing XML
      This request will get you the data points for a specific device, for all experiences run on this device after October 28 2015 at 2pm UTC.
      https://analytics.intuilab.com/analytics/export/xml?credentialKey={YourCredentialKeyHere}&deviceName={YourDeviceName}&startDate=2015-10-28T14:00:00.000Z

    We recommend you use a tool like Postman to build and test your request.

    Use the REST request in an Excel file

    You can connect an Excel spreadsheet to the IntuiFace Data Tracking Hub using the XML-oriented REST-based Web services query as an Excel data source. By doing so you will be able to refresh data points dynamically.

    Here are the steps:

    • in Excel's Data tab, click on - depending on your version of Excel - Get External Data From Web or From Web
    • Enter the Web services query, making sure you set the xlsx=true parameter. You should build and test it using a tool like Postman before using it in Excel.
      • Query copied from above: https://analytics.intuilab.com/analytics/export/xml?credentialKey={YourCredentialKeyHere}&xlsx=true
    • Click on the Import button

    That's it!

    You can then create Pivot tables and your own dashboards.


    excel-1.png


    excel-2.png


    excel-3.png

    Update an existing connection in Excel

    You can download this sample Excel file and just insert your credential key in the request.

    • in Excel's Data tab, expand the Refesh All button and select Connection Properties
    • Select the Definition tab
    • Click on Edit query
    • Enter your credential key in the placeholder

    You can build Pivot tables and diagrams from this raw table which will contains all available data points, on all devices attached to your account.
    If you don't see anything, that's probably because you don't have data points to visualize. See this article to learn how to log events - and thus create data points - in your IntuiFace experiences.


    excel-update.png

    Structure of a Data Point

    The following fields appear in all queries:

    • TimestampUTC: Contains the timestamp at the moment the Log Event action occurred.
      The date is formatted as [day]/[month]/[year]. The time recorded is for the UTC standard, equivalent to Greenwich Mean Time (GMT).
      NOTE: Be sure to verify that the time and time zone are properly set on each device running Player.
    • TimestampLocalTime: Contains the timestamp at the moment the Log Event action occurred.
      The date is formatted as [day]/[month]/[year]. The time recorded is for the local time zone of the device running Composer/Player.
      NOTE: Be sure to verify that the time and time zone are properly set on each device running Player.
    • DeviceName: The name of the device running Composer/Player.
    • Application: The name of the IntuiFace software running on the device. Values can be any one of
      • Composer
      • PlayerForWindows
      • PlayerForTablets
      • PlayerForKiosks
    • ApplicationVersion: The version of the IntuiFace application identified in the previous field.
    • PlayerTags: A list of all tags assigned to this instance of Player. If multiple tags exist, they will be separated by the pipe symbol: '|'.
    • OS: The name of the operating system on the device running Composer/Player. Values can be any one of:
      • Windows
      • iPad
      • Android
      • ChromeOS
      • SSSP [for Samsung SMART Signage Platform]
    • OSVersion: The version of the operating system identified in the previous field.
    • ExperienceName: The name of the IntuiFace experience that generated this data point.
    • SessionID: Contains the Session ID if specified by the running experience. Could be blank.
    • SceneName: The name of the scene in which the data point was generated.
    • EventName: The name of the event specified in the Log Event action.
    • ElapsedTime: Contains a value only for the automatically recorded events "Scene Left", "Session Stopped" and "Experience Stopped". In all other cases this field will be blank.

    The following fields only conditionally appear:

    • Value: Only appears if using IntuiFace Version 5.1 or earlier.
    • Comment: Only appears if using IntuiFace Version 5.1 or earlier.
    • [Parameter Name]: Only appears if a parameter is associated with the event represented by this data point.
      • There will be as many columns as there are unique parameters across all data points downloaded by the Web services query.

    Additional Notes

    • Unlike in previous releases of IntuiFace, this method of accessing data points is available even to those using Composer Free or Composer Pro.
    • Web services queries in Excel generate a schema that is only changed if data is reimported. A refresh of the feed is insufficient to update the schema. As a result, if parameters are added to logged events, a refresh in Excel won’t display data for the corresponding fields.
    • If a Parameter value - the value of a parameter associated with the Log Event action - contains only numbers and one more more commas, the commas are deleted by Composer/Player before data point transfer . If the comma is meant to indicate decimal notation, use a binding converter to change the comma into a period.
    • If the name of a Parameter, as defined in Composer or Player for a logged event, contains a space, the space will be replaced with an underscore when downloaded in an XML format.