Skip to main content

Sending Data to Intel

Sending clickstream and transactional events into Intel can be achieved in both real-time and offline manner.

Using the Track API to send Events in Real-time​

Intel includes a Tracking API that is used to send event messages to Intel for processing. There are several ways to access the Tracking API.

  • GetAnalytics.io Tracker Client
  • Track REST API
  • Track Pixel API

GetAnalytics.io Tracker Client​

This is the recommended approach for sending real-time event messages to Intel. To use the tracker client, please refer to GetAnalytics.io's Getting Started guide.

For browser usage, please see CDN Browser Usage. For Node.js usage, please see Node.js Usage.

Track REST API​

This endpoint allows direct access to the underlying Track API to allow the recording of analytics data from any website or application.

Endpoint:

POST https://track.conscia.io/v1/{{trackingMethod}}

trackingMethod is one of identify, track, or page

Tracking Pixel API​

This endpoint returns a 1×1 gif to allow for tracking email opens, advertising impressions and checkout pages where JavaScript and POST requests may be disallowed, but where you can embed an image.

GET https://track.conscia.io/v1/pixel/{{trackingMethod}}?data={{base64EncodedJson}}

trackingMethod is one of identify, track, or page

<base64EncodedJson> is the event message.

Example of using this endpoint with an image tag:

<img src="https://track.conscia.ai/v1/pixel/track?data=eyJhcGlUb2tlbiI6ICJiNWNjODI1NS1kMWYxLTRkNjAtODA4Mi0wNjVmN2VjODIxNDUiLCAidXNlcklkIjogInVzZXIzMzQxIiwgImV2ZW50IjogIkVtYWlsIE9wZW5lZCIsICJwcm9wZXJ0aWVzIjogeyAgICJzdWJqZWN0IjogIlRoZSBDb25zY2lhIFByaW1lciIsICAgImVtYWlsIjogImh1Z29AZWxhaW5lLm1lIiB9fQ==">

Sending Offline Events​

Sending offline events means that when an event occurs, it is not immediately sent to Intel, but sent at a later time. The event messages must have the timestamp set to the time that the event originally occurred.

There are two approaches:

  1. Upload a file containing multiple events.
  2. Use one of the real-time methods above to send events that have already occurred.

Uploading files with event messages​

curl --request POST \
  --url https://io.conscia.ai/tracker/upload \
  --header 'authorization: Bearer {{apiKey}}' \
  --header 'X-Customer-Code: {{customerCode}}' \
  --form 'file[]=@my-file.txt'

Accepted formats of the uploaded files are:

  • Newline-delimited JSON
  • Comma-delimited file

Examples of newline-delimited JSON.

{"timestamp": "2007-12-14T13:30", "type":"identify","traits":{"name":"Peter Gibbons","email":"peter@example.com","plan":"premium","logins":5},"userId":"97980cfea0067"}
{"timestamp": "2007-12-14T13:41", "type":"identify","traits":{"name":"Jane Sekata","email":"jsek@example.com","plan":"premium","logins":2},"userId":"97780abea0123"}

Example of a delimited file

timestamp,type, traits.name, traits.email, traits.plan, traits.logins, userId
"2007-12-14T13:30","identify","Peter Gibbons,"peter@example.com","premium",5,97980cfea0067
"2007-12-14T13:41","identify","Jane Sekata,"jsek@example.com","premium",2,97780abea0123

Event Message Payload​

Types of Messages​

Conscia’s libraries generate and send messages to our tracking API in JSON format, and provide a standard structure for the basic API calls. A recommended JSON structure is also provided that helps keep the most important parts of your data consistent, while allowing great flexibility in what other information you collect and where.

Types of calls (aka Tracking Methods):

  • Identify: Who is the user?
  • Track: What are they doing?
  • Page: What web page are they on?

An Identify call helps with the understanding of the user who is triggering messages. Track and Page calls can be considered as increasingly specific types of events.

Common Fields​

The common fields for every API call are:

TraitTypeDescription
anonymousId (required; optional if userID is set instead)StringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely
messageId (implicit)StringAutomatically collected, a unique identifier for each message that lets you find an individual message across the API.
receivedAt (implicit)DateAutomatically set by Segment, the timestamp of when a message is received by Segment It is an ISO-8601 date string.
sentAt (optional)DateTimestamp of when a message is sent to Segment, used for clock skew correction It is set automatically by the Segment tracking
timestamp (optional)DateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API, as a ISO-8601 format
type (implicit)StringType of message, corresponding to the API method: 'identify', 'track' or 'page'
userId (required; optional if anonymousID is set instead)StringUnique identifier for the user in your database. A userId or an anonymousId is required. See the Identities docs for more details.
version (implicit)NumberVersion of the Tracking API that received the message, automatically set.

Identify​

Identify call lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about the user, like their email, name, and more.

Make an Identify call:

  • After a user first registers
  • After a user logs in
  • When a user updates their info (for example, they change or add a new address)
  • Upon loading any pages that are accessible by a logged in user (optional)

The payload of a typical identify call with most common fields removed:

{
  "type": "identify",
  "traits": {
    "name": "Peter Gibbons",
    "email": "peter@example.com",
    "plan": "premium",
    "logins": 5
  },
  "userId": "97980cfea0067"
}

The corresponding JavaScript event that would generate the above payload:

analytics.identify("97980cfea0067", {
  name: "Peter Gibbons",
  email: "peter@example.com",
  plan: "premium",
  logins: 5
});

Beyond the common fields, an identify call has the following fields:

FieldTypeDescription
traits (optional)ObjectFree-form dictionary of traits of the user, like email or name. See the Traits field docs for a list of reserved trait names.
userId (required; optional if anonymousID is set instead)StringUnique identifier for the user in your database. A userId or an anonymousId is required. See the Identities docs for more details.

Identities​

The identify call specifies a customer identity that can be referenced across the customer’s whole lifetime. Every identify call must have a User ID or an Anonymous ID, depending on how much is known about the user in question.

Anonymous ID​

There are certain cases where the user is unknown but you still want to be able to tie them to traits, events, or page views. In these cases, an Anonymous ID should be used.

The browser-based Tracking Client will automatically keep track of users as they navigate around and assign an Anonymous ID.

User ID​

User IDs are a more permanent and robust identifier, like a database ID. Since these IDs are consistent across a customer’s lifetime, identify calls should include a User ID as often as possible. Use database IDs instead of simple email addresses or usernames, because database IDs never change. That guarantees that even if the user changes their email address, they can still be recognized. Instead of using an email address or a username as a User ID, send them along as [traits].

Traits​

Traits are extra pieces of information that are sent along with a identify tracking method. These could be demographics like age or gender and account-specific like plan.

Some traits that have semantic meanings for users are reserved and should only be used for their intended meaning.

Reserved traits are:

TraitTypeDescription
addressObjectStreet address of a user optionally containing: city, country, postalCode, state, or street
ageNumberAge of a user
avatarStringURL to an avatar image for the user
birthdayDateUser’s birthday
companyObjectCompany the user represents, optionally containing: name (String), id (String or Number), industry (String), employee_count (Number) or plan (String)
createdAtDateDate the user’s account was first created. Using ISO-8601 date strings.
descriptionStringDescription of the user
emailStringEmail address of a user
firstNameStringFirst name of a user
genderStringGender of a user
idStringUnique ID in your database for a user
lastNameStringLast name of a user
nameStringFull name of a user.
phoneStringPhone number of a user
titleStringTitle of a user, usually related to their position at a specific company. Example: “VP of Engineering”
usernameStringUser’s username. This should be unique to each user, like the usernames of Twitter or GitHub.
websiteStringWebsite of a user

Track​

The track API call is how any actions your users perform is recorded, along with any properties that describe the action.

Each action is known as an event. Each event has a name, like User Registered, and properties. For example, a User Registered event might have properties like plan or accountType.

The payload of a typical track call with most common fields removed:

{
  "type": "track",
  "event": "User Registered",
  "properties": {
    "plan": "Pro Annual",
    "accountType" : "Facebook"
  }
}

The corresponding JavaScript event that would generate the above payload:

analytics.track("User Registered", {
  plan: "Pro Annual",
  accountType: "Facebook"
});

Beyond the common fields, the track call has the following fields:

FieldTypeDescription
event (required)StringName of the action that a user has performed. See the Event field docs for more details.
properties (optional)ObjectFree-form dictionary of properties of the event, like revenue See the Properties docs for a list of reserved property names.

Event​

Every track call records a single user action. These are called events, and it is recommend that you make your event names human-readable. Conscia's Intel uses a standard set of event names with special semantic meanings. See the Semantic Events section for more detail.

Properties​

Properties are extra pieces of information you can tie to events you track. They can be anything that will be useful while analyzing the events later. Properties should be set whenever possible because they provide a more complete picture of what is happening.

Some properties are reserved and have semantic meanings. For example, revenue is expected to be a dollar amount. Reserved properties should only be used for their intended meaning. See the Semantic Events section for properties specific to individual reserved events.

Page​

The page call records when a user sees a page of a website, along with any optional properties about the page.

The browser-based Tracking Client calls page just after analytics.load.

The payload of a typical page call with most common fields removed:

{
  "type": "page",
  "properties": {
    "title": "Welcome | Initech",
    "url": "http://www.example.com",
    "extraInfo": "my-info"
  }
}

The corresponding JavaScript event that would generate the above payload. When using the browser-based Tracking Client, the title, url, path, search, width and height are automatically gathered and passed as properties into the event payload:

analytics.page({ extraInfo: "my-info" });

Beyond the common fields, the page call takes the following fields:

FieldTypeDescription
properties (optional)ObjectFree-form dictionary of properties of the page, like url and referrer See the Properties field docs for a list of reserved property names.

Properties​

PropertyTypeDescription
pathStringPath portion of the page’s URL. Equivalent to canonical path which defaults to location.pathname from the DOM API.
referrerStringPrevious page’s full URL. Equivalent to document.referrer from the DOM API.
searchStringQuery string portion of the page’s URL. Equivalent to location.search from the DOM API.
titleStringPage’s title. Equivalent to document.title from the DOM API.
urlStringPage’s full URL. Conscia first looks for the canonical URL. If the canonical URL is not provided, Conscia uses location.href from the DOM API.
keywordsArray [String]A list/array of keywords describing the page’s content. The keywords would most likely be the same as, or similar to, the keywords you would find in an HTML meta tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn’t automatically collected.