Knowledge Center

Knowledge Center > Insights > Developer Reference > API Reference > Insights Streaming API

Insights Streaming API

Use the Streaming API to report new user or account events to Insights.

An event in Insights is an individual activity performed by a user. See Insights Glossary for more information.

The Streaming API is required in cases where you cannot use the Batch API because the data source you want to capture event data from does not offer a historical event export capability. 

Prerequisites

Before you can use the Streaming API, Zuora must configure your Insights tenant with a Stream API Data Source and provide you with the API token that you will need for authentication. Submit a request at Zuora Global Support for assistance. Zuora Global Support will send the API token to a confirmed Insights administrator. See Global Support Scope for Insights for more information.

Zuora Global Services can also provide a JavaScript template that enables your web application to report events to Insights using the Streaming API.

Data Latency

Events posted via the Streaming API take up to two hours to become viewable in Insights and reflected in Metric or Attribute value calculations, or Segment memberships

Request

POST https://nw1.events.insights.zuora.com/api/track/event

Request Header Fields

None.

Request Body Fields

Specify the following fields in the body of the request.

token required

Insights API token. For example, "WliXmCWAMGYMvFBU".

stream required

Insights stream to create the event in. The value for the stream can be found in the dropdown menu to the right of search in the menu navigation. For example, "cloudstream" for the stream shown below.

timestamp required

Date and time of the event in milliseconds since 1 January 1970 at 00:00 UTC. For example, "1368976387454" for May 19, 2013 15:13:07 (pm) UTC.

timezoneOffset required

Time zone of the event, in minutes relative to UTC. For example, "-420" for UTC -07:00.

accountId required

ID of the account to create the event for. Account IDs in Insights match the account IDs in your Zuora tenant.

event required

Label of the event.

Event labels are used for filtering and aggregating event data. You do not need to define event labels before using them, but to avoid duplication you should be careful to maintain consistency with respect to case, spacing, and punctuation.

eventData optional

Custom attributes of the event.

Type: serialized JSON object

session optional

ID of a session in your application.

If you specify a session ID, Insights groups the new event with any previous events that have the same session ID. The session ID should be universally unique. Most platforms provide an API for generating UUIDs or GUIDs.

See Tracking Accounts and Users: Controlling the Session for more information about sessions in Insights.

If you do not specify a session ID, the following happens:

  • If the new event is not within 30 minutes of a previous event for the same user, Insights generates a session ID for the new event and returns the generated session ID.
  • If the new event is within 30 minutes of a previous event for the same user, Insights groups the new event with the previous event and returns the session ID of the previous event.

If you do not specify a session ID, Insights returns a session ID that you can specify in subsequent calls.

Insights only supports sessions for user events, not for account events.

sessionData optional

Custom attributes of the session.

Type: serialized JSON object

userId optional

ID of the user to create the event for. If you do not specify a user ID, Insights creates an account event.

userName optional

Full name of the user to create the event for. For example, "Jane Doe".

userData optional

Custom attributes of the user to create the event for.

Type: serialized JSON object

accountName optional

Name of the account to create the event for. For example, "Acme, Inc.".

accountData optional

Custom attributes of the account to create the event for.

Type: serialized JSON object

Description

Custom Attributes

You can use the eventData, sessionData, accountData, and userData request body fields to provide custom attributes of the event, session, account, and user.

The value of each custom attributes field must be a serialized JSON object containing one or more key-value pairs. Values must be booleans, strings or numbers. Use ISO8601-formatted strings to store dates or timestamps. Nested lists and objects are not permitted.

If the value of a custom attribute does not match a previously stored value, then the value is updated. Missing keys are not deleted. To delete a previously saved key, explicitly supply a null value.

Custom attributes should be short keywords, numbers or dates that you want to use for ordering, filtering and segmenting users. You should not use custom attributes for long text strings.

Examples

Example Request (JSON)

{
     "timestamp": 1368976387454,
     "timezoneOffset": -420,
     "token": "mBLUNEqRlQJfhbmRnNcwQqlslAwRILNK",
     "stream": "production",
     "userId": "45b979fbc892496bbd759c0bdb38b711",
     "userName": "Mabel Jones",
     "userData": {
         "role": "administrator"
     },
     "accountId": "2c92c0fa57ffa60f01580a4b8552651d",
     "accountName": "Acme, Inc.",
     "accountData": {
         "status": "paying",
         "plan": "enterprise"
     },
     "event": "login",
     "session": "caa8c9c0-bc14-477f-ae23-f4841522b76e"
}

Example Success Response (JSON)

{
    "session":"caa8c9c0-bc14-477f-ae23-f4841522b76e",
    "message":"OK"
}

Example Error Response (JSON)

{
    "code":"NOT_NULL",
    "fields":["token"],
    "message":"Field token cannot be null"
}
Last modified
18:05, 12 Feb 2017

Tags

This page has no custom tags.

Classifications

(not set)