Overview

Event Ingestion API environments

There are three different API endpoints you can send events to. The event references below use the dev environment.

Use these different endpoints to integrate with Simon based on the environments you deploy to.

All request payloads sent to Simon's Event Ingestion API will have the following:

Parameter

Required

Description

partnerId

Yes

The internal partnerId Simon uses to identify the customer's site.

context

Yes

A dictionary containing optional fields about the context of the event.

clientId

Yes

A unique identifier for the device. If no unique identifier for the device can be maintained this may be a unique identifier for the current session (max length: 45 characters).

partnerSecret

Yes

The shared secret used for authentication.

ipAddress

No

The public IP address of the users device if available.

sentAt

Yes

Epoch time in milliseconds of when the request was sent. Epoch time is the number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT).

timezone

No

The time difference between UTC time and local time, in minutes. See https://www.w3schools.com/jsref/jsref_gettimezoneoffset.asp for an example.

type

Yes

The high level type of request being sent in can be either track or identify.

If you do not know your partner ID, contact your account manager.

The optional context attributes:

Parameter

Description

debug

A setting for development, when if True, will tell the HTTP API to send validation errors as HTTP 412 errors. Boolean field, defaults to False.

name

Unique name for your client library. For example, our Simon JavaScript SDK sets this to simon.js.

version

Version identifier for your client library.

userAgent

The user agent of the device sending the event, if available.

page

A dictionary representing parameters relevant to the page's context.

url

The page url of the event which the event was triggered from, if available.

device

A dictionary representing parameters relevant to the device's context.

type

String identifying the type of client device (e.g. android).

Sending clickstream data to Simon Data

🚧

Exceptions and debug mode

If you're unsure about whether your event is correctly formatted, you can use the debug mode. Exceptions will be silent unless the debug mode is active. Check out the details below.

The identify command

This is an example of an identify call:

{
    "partnerId": "804f98b48491143c2e4f2ffea854eb372a41bbfd",
    "clientId": "92adbc3c-c22b-49bf-a9ae-11d9e8b3e6b4",
    "context": {
        "version": "1.0.0",
        "name": "simon.js",
        "debug": true,
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
        "page": {
            "url": "http://localhost:9000/index.html"
        }
    },
    "partnerSecret": "1294b7e58f37568396b31ce481cf8edc1e6cfcb5",
    "sentAt": 1524776691259,
    "ipAddress": "127.0.0.1",
    "timezone": 240,
    "type": "identify",
    "userId": "97980cfea0067",
    "traits": {
        "name": "test",
        "email": "[email protected]",
        "firstName": "Joe",
        "lastName": "Smith",
        "userId": "97980cfea0067",
        "username": "joesmith",
        "properties": {
            "campaignId": "12345"
        }
    }
}

A call to identify establishes the identity associated with a userId. The variable userId is a user identifier that you specify. identify can be called to pass information when a source of identity is recognized, such as an authenticated login, an click from an email with an identity URL parameter, and signup for newsletter subscription. Different types of identifiers can be passed on.

Calling identify does not automatically establish identity for all subsequent track events. Include traits within the track calls to accomplish this.

When a user registers with you for the first time, you should call identify and also make a separate call to registration.

Valid values for the traits dictionary are as follows.

Value

Type

Required

Description

email

String

Yes

The email address of the user (e.g. [email protected]).

firstName

String

No

The first name of the user (e.g. Joe).

lastName

String

No

The last name of the user (e.g. Smith).

name

String

No

The full name of the user. (e.g. Joe Smith).

userId

String

No

The user id. (e.g. 97980cfea0067).

userName

String

No

The username (e.g. joesmith).

ARN

String

No

The ARN of the user. Used to sync Simon with Amazon SNS.

properties

Object

No

An object of extra arguments (e.g. { campaignId: '12345' }).

πŸ“˜

Next-Gen Identity

If your organization is on Next-Gen Identity, you can use any native identifier present in your organization's account. Email address is no longer required.

Next-Gen Identity is currently in a Limited Beta. Most accounts are currently on Legacy Identity unless told otherwise. Contact your account manager for more detail.

A note about identify and AWS SNS. The following fields should be set in your identify call for Simon to properly keep track of SNS identities:

  • userId: Set this to the internal user id for the user
  • context.device.type: Set this to the device type of the device to be synced with SNS. The value can be ios,android,kindle, or windows
  • traits.ARN: Set this to the AWS SNS ARN of the user's device

The track command

A track command may be invoked to pass user-interaction data to Simon Data. These user-interactions are captured by specific events that are documented in this API and are explained in more detail below. Each event has an Event Type specifying the name of the event and an associated Event Object which contains additional metadata about the event.

An example track command for a page_view event:

{
    "partnerId": "804f98b48491143c2e4f2ffea854eb372a41bbfd",
    "clientId": "92adbc3c-c22b-49bf-a9ae-11d9e8b3e6b4",
    "context": {
        "version": "1.0.0",
        "name": "simon.js",
        "debug": true,
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
        "page": {
            "url": "http://localhost:9000/index.html"
        }
    },
    "partnerSecret": "1294b7e58f37568396b31ce481cf8edc1e6cfcb5",
    "sentAt": 1524776691259,
    "ipAddress": "timezone": 240,
    "type": "track",
    "properties": {
        "title": "SimonJS Test Page",
        "language": "en-US"
    },
    "event": "page_view"
}

Note that this looks much like the identify call above with the exceptions that the type is track, instead of traits we have properties, and we have an extra parameter called event.

πŸ“˜

Establishing identity within a 'track' call

Use traits containing userId and email parameters in the payload as a method to establish the identity associated with the track event, as in the below example.

{
    "partnerId": "804f98b48491143c2e4f2ffea854eb372a41bbfd",
    "clientId": "92adbc3c-c22b-49bf-a9ae-11d9e8b3e6b4",
    "context": {
        "version": "1.0.0",
        "name": "simon.js",
        "debug": true,
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
        "page": {
            "url": "http://localhost:9000/index.html"
        }
    },
    "partnerSecret": "1294b7e58f37568396b31ce481cf8edc1e6cfcb5",
    "sentAt": 1524776691259,
    "ipAddress": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "title": "SimonJS Test Page",
        "language": "en-US"
    },
    "event": "page_view",
    "userId": "97980cfea0067",
    "traits": {
        "name": "test",
        "email": "[email protected]",
        "firstName": "Joe",
        "lastName": "Smith",
        "userId": "97980cfea0067",
        "username": "joesmith",
        "properties": {
            "campaignId": "12345"
        }
    }
}

Parameters

The properties that can be specified within the properties object literal vary depending on the event type.

🚧

Using custom properties

The event schema is enforced and events that are missing required properties or include unrecognized properties will be rejected during processing. Using the debug mode during your integration set-up will let you know that this is happening. However, all event types support custom properties within the properties.properties part of the payload (see an example for product view events). The API also supports custom events if there is not a pre-existing matching event type, but make sure to adhere to the schema for those events, too.

Event type

Event object

page_view

none

product_view

productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties
cartItems

add_to_cart

productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties
cartItems

cart

cartItems
productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties

update_cart

productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
previousQuantity
price
properties
cartItems

remove_from_cart

productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties
cartItems

complete_transaction

transactionId
revenue
cartItems
productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties
shipping
tax
promotion
properties

registration

email
username
userId
optIn
firstName
lastName
properties

favorite

productId
variant
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties

waitlist

productId
variant
quantity
productImageUrl
productUrl
brand
category
color
productName
size
style
price
properties

authentication

userId
isLoggedIn
ARN
email
properties

custom

eventName
requiresIdentity
properties