Documentation / Product / Features / StartSmart

StartSmart Data Management

The following document outlines the required formatting for all supported event types as well as reserved identifiers in relation to the StartSmart program. Should you need to deviate from this collection schema please consult your implementation team before implementation.

Table of Contents

What is an event?

Events represent all inbound data collected from any of the supported methods such as direct to API, via the Lytics JavaScript tag or from a supported integration. Each event sent must include the following:

  • Identifier
    At minimum one identifier must be included with each event in order to associate the fragment of data with a profile. In the case of the Lytics JavaScript tag, an anonymous identifer called _uid will be sent with every event.
  • Event Type
    In order to determine how the event should be processed an event type must be included. Only event types from the definitions below can be included. Should you require a custom event type consult with your implementation team to determine options and if it is in scope for the project.
  • Attributes
    Though attributes are not technically required they are what will contain the contextual data required to get the most out of Lytics. Any combination of the defined attributes can be included with each event.
{
    "event": "identify",
    "email": "[email protected]",
    "channel": "web",
    "profile": {
        "firstName": "Mok",
        "lastName": "Wahlboog",
        "title": "celebrity"
    },
    "campaign": {
        "name": "who-you-is-campaign"
    }
}

Event Types

A single event type should be included in all inbound events to Lytics when using the standard schema. These events dictate the rules around how an event is processed and are extremely important to ensure profiles are accurately generated.

IdentifiersCommonProfileSiteItemCampaignCartSubscriptionTransaction
identification
identifyxxxxx
general
clickxxxx
viewxxxx
email
openxxxx
bouncexxx
blockedxxx
sentxxx
deliveredxxx
commerce
cart-addxxxxxx
cart-removexxxxxx
checkoutxxxxxx
purchasexxxxxx
refundxxxxxx
b2b/saas
registerxxxxxx
loginxxxxxx
logoutxxxxxx
account-createxxxxxx
account-deletxxxxxx
trial-startxxxxxx
trial-endxxxxxx
customxxxxxxxxx

Identifiers

Identifiers represent unique, identifiable value for a user. By default, the Lytics JavaScript tag will append an anonymous _uid to all collection events but additional identifiers as defined below can and should be leveraged to improve identity resolution.

KeyDescription
_uidLytics managed id most commonly set based on anonymous cookie
userIdcustomer managed unique identifier for entity
usernameunique user name for entity
emailemail address of entity
emailHashsecure hash of email address for entity
customIdoptional custom id placeholder number 1
customId2optional custom id placeholder number 2
customId3optional custom id placeholder number 3

Attributes

Attributes represent a standard set of meta data associated with an event. For instance, when an event is sent from the web it should include the relevant site attribute data in order to facilitate the best behavioral understanding. The standard schema supports attributes for a variety of common collection events ranging from ecommerce to generic activity.

Common

Common attributes are optional key/value pairs that can be included with any standard Lytics event. They generally give more context of source, time, etc.

KeyDescription
channelName of channel such as email, web, mobile, etc.
sessionIdUnique identifier for session
timestampTime the event took place, if no value passed will default to current time
timezoneTimezone that the event originated from

Profile

A person (alive, dead, undead, or fictional).

KeySchema.orgDescription
nameThe name of the entity.
firstNameThe first name of a Person. This can be used along with lastName instead of the name property.
lastNameThe last name of an Person. This can be used along with firstName instead of the name property.
jobTitleThe job title of the person (for example, Financial Manager).
phoneNThe phone number.
cellNThe cellphone number.
genderGender of the person. While http://schema.org/Male and http://schema.org/Female may be used, text strings are also acceptable for people who do not identify as a binary gender.
birthDateDate of birth.
urlURL of the entity.
imageAn image of the entity.
createdNDate entity was created.
updatedNDate entity was last updated.
PostalAddresshttps://schema.org/PostalAddress
address.streetAddressThe street address. For example, 1600 Amphitheatre Pkwy.
address.addressRegionThe region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division
address.addressLocalityThe locality in which the street address is, and which is in the region. For example, Mountain View.
address.postalCodeThe postal code. For example, 94043.
address.addressCountryThe country. For example, USA. You can also provide the two-letter ISO 3166-1 alpha-2 country code.
organization.identifierNThe Identifier of the company.
organization.nameNThe name of the company.
organization.urlNThe url of the company.

Site

Attributes related to a website or online property.

KeySchema.orgDescription
referralDomainNdomain that referred the user
languageNusers browser language
deviceNtype of device the user is on (mobile, desktop, etc.)
urlNurl where the event originated
tagVersionNversion of tag that emitted the event

Item

Any offered product or service. For example: a pair of shoes; a concert ticket; the rental of a car; a haircut; or an episode of a TV show streamed online.

KeySchema.orgDescription
itemIdThe item identifier, such as ISBN. For example: meta itemprop="productID" content="isbn:123-456-789".
skuThe Stock Keeping Unit (SKU), i.e. a merchant-specific identifier for a product or service, or the product to which the offer refers.
nameThe name of the item.
categoryA category for the item. Greater signs or slashes can be used to informally indicate a category hierarchy.
urlURL of the item.
imageAn image of the item.
valueNValue, generally cost, of item.
purchaseDateThe date the item e.g. vehicle was purchased by the current owner.
deliveryDateNThe date the item e.g. vehicle was delviered to the current owner.
attr1NFlexible attribute of type string, bool, int or number.
attr2NFlexible attribute of type string, bool, int or number.
attr3NFlexible attribute of type string, bool, int or number.
attr4NFlexible attribute of type string, bool, int or number.
attr5NFlexible attribute of type string, bool, int or number.

Campaign

Any marketing initiative to be associated for attribution.

KeySchema.orgDescription
campaignIdNThe id of the campaign.
sourceNThe source of the campaign, generally utm_source (google, newsletter).
mediumNThe medium of the campaign, generally utm_medium (cpc, banner, email).
nameNThe label of the campaign, generally utm_name (spring_sale).
listIdNId of the list the campaign is associated with.
segmentIdNId of the segment the campaign is associated with.
templateIdNId of the template the campaign is assocaited with.

Cart

An e-commerce shopping cart. Carts are responsible for holding pending transaction details and are commonly marketed against.

KeySchema.orgDescription
cartIdNThe id of the shopping unique shopping cart.
createdDateNDate the shopping cart was first created.
updatedDateNDate the shopping cart was last changed.
totalValueNTotal value represented by the shopping cart.
itemCountNTotal number of items in the shopping cart.
returnUrlNReturn url for accessing the shopping cart again.

Subscription

A subscription, generally referenced in a transaction, represents an ongoing relationship with a product.

KeySchema.orgDescription
subscriptionIdNThe id of the subscription.
cycleNThe cycle time for the subscription (day, week, annual).
startDateNThe date when the subscription was started or will start.
endDateNThe date when the subscription ends or ended.
totalValueNThe total value represented by the subscription.
cycleValueNThe total value represented by each subscription cycle.
listIdNThe list id associated with the subscription.
segmentIdNThe segment id associated with the subscription.

Transaction

A single transaction such as a purchase or reservation. Each transaction will likely have its own unique invoice or id and contain a subset of products or campaign information.

KeySchema.orgDescription
orderIdThe identifier property represents any kind of identifier for any kind of Thing, such as ISBNs, GTIN codes, UUIDs etc. Schema.org provides dedicated properties for representing many of these, either as textual strings or as URL (URI) links.
orderDateDate order was placed.
itemCountNNumber of items purchased
totalTaxNTotal tax if transaction is purchase
subTotalNSubtotal if transaction is purchase
totalNTotal value if transaction is purchase