Events API environments

There are three different API endpoints you can send events to, one for each of the typical environments that a company has:

Environment	Endpoint
Production	https://simonsignal.com/http/v1/collect
Staging	https://staging.simonsignal.com/http/v1/collect

Use these different endpoint to integrate with Simon for the different environments you deploy to.

Every request sent to the endpoint must be a POST request with the payload being JSON.

All request payloads sent to Simon's Events 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, please contact us.

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.
`page.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.
`device.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' }).

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

Event types

The event field accepts the event types delineated below. A properties object literal must also be passed to the track command if the event has any required properties.

Page View

This is an example of 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "title": "SimonJS Test Page",
        "language": "en-US",
        "referrer": "http://www.google.com"
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "page_view"
}

Page impressions are measured using the track command with the page_view event type. Details about the product are added in properties.

Value	Type	Required	Description
title	String	No	The title of the page.
language	String	No	The user language preference. This can change on an event by event basis, hence why it is not in the `context` parameter.
referrer	String	No	The URL of the referring page.

Product View

This is an example of a Product 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "productId": "632910392",
        "variant": "808950810",
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        }
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "product_view"
}

Product impressions are measured using the track command with the product_view event type. Details about the product are added in properties.

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	No	The variant of the product (e.g. 808950810).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).

Add To Cart

This is an example of an Add To Cart 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "productId": "632910392",
        "variant": "808950810",
        "quantity": 1,
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        },
        "cartItems": [
            {
                "productId": "632910392",
                "variant": "808950810",
                "quantity": 1,
                "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
                "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
                "brand": "Acme",
                "category": "Apparel/Men/T-Shirts",
                "color": "Black",
                "productName": "Nyan Cat T-Shirt",
                "size": "Medium",
                "style": "Slim Cut",
                "price": 24.95,
                "properties": {
                    "desc": "Slim cut t-shirt with a cat on it"
                }
            }
        ]
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "add_to_cart"
}

Products added to cart are captured using the track command with the add_to_cart event type. Details about the product are added in properties.

The call to add_to_cartsupports an optional cartItems array with all the items in the cart and their corresponding parameters (productId, variant etc.). cartItems should include the product that was just added.

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	Yes	The variant of the product (e.g. 808950810).
quantity	Number	Yes	The number of units added to the cart (e.g. 1).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).
cartItems	Array	No	An array with the full contents of the cart (e.g. [{item 1 parameters},{item 2 parameters},...][{item 1 parameters},{item 2 parameters},...]).

Cart

This is an example of a Cart 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "cartItems": [
            {
                "productId": "632910392",
                "variant": "808950810",
                "quantity": 1,
                "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
                "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
                "brand": "Acme",
                "category": "Apparel/Men/T-Shirts",
                "color": "Black",
                "productName": "Nyan Cat T-Shirt",
                "size": "Medium",
                "style": "Slim Cut",
                "price": 24.95,
                "properties": {
                    "desc": "Slim cut t-shirt with a cat on it"
                }
            }
        ]
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "cart"
}

The complete contents of a cart can be sent using the track command with the cart event type. Details about the product are added in a cartItems array.

The following table describes the composition of an element in the cartItems array, which contains the full cart contents:

Value	Type	Required	Description
cartItems	Array	Yes	An array with the full contents of the cart (e.g. [{item 1 parameters},{item 2 parameters},...][{item 1 parameters},{item 2 parameters},...]).
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	Yes	The variant of the product (e.g. 808950810).
quantity	Number	Yes	The quantity of the product added to the cart (e.g. 1).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).

Update Cart

This is an example of an Update Cart 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "productId": "632910392",
        "variant": "808950810",
        "quantity": 2,
        "previousQuantity": 1,
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        },
        "cartItems": [
            {
                "productId": "632910392",
                "variant": "808950810",
                "quantity": 2,
                "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
                "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
                "brand": "Acme",
                "category": "Apparel/Men/T-Shirts",
                "color": "Black",
                "productName": "Nyan Cat T-Shirt",
                "size": "Medium",
                "style": "Slim Cut",
                "price": 24.95,
                "properties": {
                    "desc": "Slim cut t-shirt with a cat on it"
                }
            }
        ]
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "update_cart"
}

Update cart actions are measured using the track command with the update_cart event type. Details about the product are added in properties. Like the add_to_cart event, update_cart supports an optional cartItems array with the full cart contents including the most recent update.

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	Yes	The variant of the product (e.g. 808950810).
quantity	Number	Yes	The new quantity of the product in the cart (e.g. 2).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
previousQuantity	Number	No	The previous quantity of the product in the cart (e.g. 1).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).
cartItems	Array	No	An array with the full contents of the cart (e.g. [{item 1 properties},{item 2 properties},...][{item 1 properties},{item 2 properties},...]).

Remove from Cart

This is an example of an Remove From Cart 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "productId": "632910392",
        "variant": "808950810",
        "quantity": 2,
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        }
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "remove_from_cart"
}

Remove from cart actions are measured using the track command with the remove_from_cart event type. Details about the product are added in properties. Like the add_to_cart event, remove_from_cart supports an optional cartItems array to send the full cart contents after the removed item.

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	Yes	The variant of the product (e.g. 808950810).
quantity	Number	Yes	The quantity of items that are removed for that product in the cart (e.g. 2).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).
cartItems	Array	No	An array with the full contents of the cart (e.g. [{item 1 properties},{item 2 properties},...][{item 1 properties},{item 2 properties},...]).

Complete Transaction

This is an example of a Complete Transaction 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "transactionId": "122710332",
        "revenue": 49.90,
        "shipping": 5.00,
        "tax": 2.29,
        "promotion": "PROMO_1234",
        "properties": {
            "campaignId": "12345"
        },
        "cartItems": [
            {
                "productId": "632910392",
                "variant": "808950810",
                "quantity": 1,
                "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
                "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
                "brand": "Acme",
                "category": "Apparel/Men/T-Shirts",
                "color": "Black",
                "productName": "Nyan Cat T-Shirt",
                "size": "Medium",
                "style": "Slim Cut",
                "price": 24.95,
                "properties": {
                    "desc": "Slim cut t-shirt with a cat on it"
                }
            },
            {
                "productId": "331910392",
                "variant": "408950811",
                "quantity": 1,
                "productImageUrl": "https://cdn.simondata.com/files/408950811.jpg",
                "productUrl": "https://www.simondata.com/apparel/t-shirts/408950811",
                "brand": "Acme",
                "category": "Apparel/Men/T-Shirts",
                "color": "White",
                "productName": "Inner Space T-Shirt",
                "size": "Medium",
                "style": "Slim Cut",
                "price": 24.95,
                "properties": {
                    "desc": "Slim cut t-shirt with planets on it"
                }
            }
        ]
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "complete_transaction"
}

Successful transactions are measured using the track command with the complete_transaction event type. Details about the product are added in properties.

Value	Type	Required	Description
transactionId	String	Yes	The transaction ID (e.g. 122710332).
revenue	Number	Yes	Specifies the revenue associated with the transaction (e.g. 49.90). It does not include shipping or tax costs.
cartItems	Array	Yes	An array containing data about the products in the transaction (See table below).
shipping	Number	No	Specifies the total shipping cost of the transaction. (e.g. 5.00).
tax	Number	No	Specifies the total tax of the transaction. (e.g. 2.29).
promotion	String	No	The promotion ID (e.g. PROMO_1234).
properties	Object	No	An object of extra arguments (e.g. { campaignId: '12345' }).

The following table describes the composition of an element in the cartItems array:

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	Yes	The variant of the product (e.g. 808950810).
quantity	Number	Yes	The quantity of the product added to the cart (e.g. 1).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).

Registration

This is an example of a Registration 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "email": "[email protected]",
        "username": "joesmith",
        "userId": "97980cfea0067",
        "optIn": true,
        "firstName": "Joe",
        "lastName": "Smith",
        "name": "Joe Smith",
        "properties": {
            "campaignId": "12345"
        }
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "registration"
}

Track when users first register or sign up using the track command with the registration event type. Details about the registration are added in properties.

When a user registers with you for the firs time, you should call identify and separately also call registration.

Value	Type	Required	Description
email	String	Yes	The email address of the user (e.g. [email protected]).
username	String	No	The username (e.g. joesmith).
userId	String	No	The user id. (e.g. 97980cfea0067).
optIn	Boolean	No	A boolean flag indicating whether this contact has opted in to receive marketing email.
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).
properties	Object	No	An object of extra arguments (e.g. { campaignId: '12345' }).

Favorite

This is an example of a Favorite 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "productId": "632910392",
        "variant": "808950810",
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        }
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "favorite"
}

Favorites are measured using the track command with the favorite event type. Details about the product are added in properties.

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	No	The variant of the product (e.g. 808950810).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).

Waitlist

This is an example of an Waitlist 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "productId": "632910392",
        "variant": "808950810",
        "quantity": 1,
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        }
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "waitlist"
}

A waitlist event should be called when a contact chooses to be added to a waitlist for a product that is out of stock. This is a track event with the waitlist event type. Details about the product are added in properties.

Value	Type	Required	Description
productId	String	Yes	The product ID or SKU (e.g. 632910392).
variant	String	Yes	The variant of the product (e.g. 808950810).
quantity	Number	No	The quantity of the product added to the waitlist (e.g. 1).
productImageUrl	String	No	The encoded URL for an image of the product (starts with http or https).
productUrl	String	No	The encoded URL for the product page (starts with http or https).
brand	String	No	The brand to which the product belongs (e.g. Acme).
category	String	No	The category to which the product belongs (e.g. Apparel). Use `/` as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
color	String	No	The color of the product (e.g. Black).
productName	String	No	The name of the product (e.g. Nyan Cat T-Shirt).
size	String	No	The size of the product (e.g. Medium).
style	String	No	The style of the product (e.g. Slim Cut).
price	Number	No	The price of a product (e.g. 24.95).
properties	Object	No	An object of extra arguments (e.g. { desc: 'Slim cut t-shirt with a cat on it' }).

Authentication

This is an example of an Authentication 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": "127.0.0.1",
    "timezone": 240,
    "type": "track",
    "properties": {
        "userId": "xyz123456",
        "isLoggedIn": true,
        "ARN": "arn:aws:sns:us-east-1:123456789:example-arn-2",
        "email": "[email protected]",
        "properties": {
            "appVersion": "3.4.1"
        }
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "authentication"
}

📘
When to use 'identify' vs 'authentication'
The general method to establish the identity for users is to use the identify call. The authentication event is mainly useful when using Amazon SNS as a channel for push messaging. It is used tie an ARN identifier with the userId. Always use identify except to specifically provide an ARN.

An authentication event should be called when a user logs in or out of the service. This is a track event with the authentication event type. Details about the product are added in properties.

Value	Type	Required	Description
userId	String	Yes	The unique userId of the user authenticating.
isLoggedIn	Boolean	Yes	A flag indicating if the user is logging into the system. This should be `false` when the user is logging out.
ARN	String	Yes	The Amazon AWS ARN the of the user.
email	String	No	The email address of the user authenticating.
properties	Object	no	An object of extra arguments.

Custom

This is an example of a Custom 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": "127.0.0.1",
	"timezone": 240,
	"type": "track",
	"properties": {
		"eventName": "event_abc",
		"requiresIdentity": true,
		"properties": {
			"desc": "Slim cut t-shirt with a cat on it"
		}
	},
	"traits": {
		"userId": "97980cfea0067",
		"email": "[email protected]"
	},
	"event": "custom"
}

custom type is used to track events that do not map to one of the pre-defined event types. This is a track event with the custom event type. Details are added in added in an eventObject.

Value	Type	Required	Description
eventName	String	Yes	The custom event type name (max length: 38 characters).
properties	Object	No	An object of extra arguments.
requiresIdentity	Bool	No	If False, the event will not require an email or match an identify event to be used. Defaults to True.

Debugging

Enabling debug mode

Debug mode can be enabled by setting the debug parameter to true when adding the tag.

Add the setting to the tag to enable debug mode:

context.debug: true

🚧
Exceptions are silent by default
By default, exceptions are caught silently and sent to our servers for further analysis. Enabling debug mode will send validation errors as HTTP 412 errors. The debug field defaults to False.

Understanding server responses

Add to cart event missing productId:

{
    "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": {
        "variant": "808950810",
        "quantity": 1,
        "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
        "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
        "brand": "Acme",
        "category": "Apparel/Men/T-Shirts",
        "color": "Black",
        "productName": "Nyan Cat T-Shirt",
        "size": "Medium",
        "style": "Slim Cut",
        "price": 24.95,
        "properties": {
            "desc": "Slim cut t-shirt with a cat on it"
        },
        "cartItems": [
            {
                "variant": "808950810",
                "quantity": 1,
                "productImageUrl": "https://cdn.simondata.com/files/808950810.jpg",
                "productUrl": "https://www.simondata.com/apparel/t-shirts/808950810",
                "brand": "Acme",
                "category": "Apparel/Men/T-Shirts",
                "color": "Black",
                "productName": "Nyan Cat T-Shirt",
                "size": "Medium",
                "style": "Slim Cut",
                "price": 24.95,
                "properties": {
                    "desc": "Slim cut t-shirt with a cat on it"
                }
            }
        ]
    },
    "traits": {
        "userId": "97980cfea0067",
        "email": "[email protected]"
    },
    "event": "add_to_cart"
}

If the implementation of your client code is healthy, all POST requests should complete with a 200 (OK) or 204 (No Content) response code. Our servers will respond with a 412 (Precondition Failed) response code in the case that a given request does not meet our criteria and debug mode is on. The example contains a properties object missing a required field and the corresponding response.

Error Response Code	Action
412	You are sending invalid data. Check the response body for more specifics.
500	Contact Simon Data.

Response from server:

{error: "Error validating event: add_to_cart; property not found: productId"}