Overview

Data points transferred from Composer and Player to the Intuiface Analytics Data 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:

• XML: Use the URL https://analytics.intuiface.com/analytics/export/xml
• JSON: Use the URL https://analytics.intuiface.com/analytics/export/json

Request parameters

Required parameter:

• credentialKey. To find it, head to the Credential Keys page. For details, see our article about credential key creation and management.
• startDate=YYYY-MM-DDThh:mm:ss.000Z: a start date, using ISO 8601 date & time representation
• endDate=YYYY-MM-DDThh:mm:ss.000Z: an end date using ISO 8601 date & time representation

All of the following parameters are optional:

• includeSa: (case-sensitive) set it to 'true' to include data points for all Secondary Accounts; it is 'false' by default
• if includeSa is false, other optional parameters are available:
  • deviceName: only retrieve data points for the specified device. Can be combined with the experienceName and/or eventName parameters. Only available if not using the 'includeSa' parameter. You'll get an error if specifying an experience when using the 'includeSa' parameter.
  • experienceName: only retrieve data points for the specified experience. Can be combined with the deviceName and/or eventName parameters. Only available if not using the 'includeSa' parameter. You'll get an error if specifying an experience when using the 'includeSa' parameter.
  • eventName: only retrieve data points for the specified event. Can be combined with the deviceName and/or experienceName parameters. Only available if not using the 'includeSa' parameter. You'll get an error if specifying an event when using the 'includeSa' parameter.

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 request responding with JSON:
  This request will get all data points collected from all devices and for all Primary Account experiences (no Secondary Accounts) run on those devices between 28-June-2022 and 28-July-2022. The result will be in JSON format.
  https://analytics.intuiface.com/analytics/export/json?credentialKey={YourCredentialKeyHere}&startDate=2022-06-28T14:00:00.000Z&endDate=2022-07-28T14:00:00.000Z
• More complex request responding with XML:
  This request will get you the data points for a specific device, for all experiences run on this device for the Primary and all Secondary Accounts after October 28 2022 at 2pm UTC.
  https://analytics.intuiface.com/analytics/export/xml?credentialKey={YourCredentialKeyHere}&deviceName={YourDeviceName}&startDate=2022-10-28T14:00:00.000Z&includeSA=true

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 Analytics Data 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.intuiface.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.

 

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 Refresh 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 contain 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.

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 (used for Player on Windows devices)
  • PlayerForTablets (used for Player on iPad or Android devices)
  • PlayerForKiosks (used for Player on BrightSign, Chrome, Tizen, or webOS devices)
• 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
  • BrightSign
  • ChromeOS
  • SSSP [for Samsung SMART Signage Platform]
  • webOS
• 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

• Web services queries in Excel generate a schema that is only changed if data is re-imported. 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 or 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.

Limitations

• Data points will not be correctly imported using Office 365