3. Events

Events are required to track important user actions such as adding an item to the cart or to the wishlist, logging into a personal account, and many more. Tracking these events is necessary to understand user behavior for specific targeting, as well as for the proper functioning of recommendation strategies. To send data to Gravity Field, you need to embed a small code for each required event.

In the event, you can pass a set of parameters that you plan to use for future work. Some events, such as Purchase or Login, require implementation according to a certain scheme. However, for other target actions, you can create and personalize your own events.

Important: for e-commerce implementation, Purchase and Add to Cart events are mandatory, but we also recommend implementing the maximum number of events from the pre-configured list that are relevant to your site. This will aid in implementing more use cases and expand the user's profile. The final list of required events is agreed with the team working on your project and depends on the planned use cases.

Pre-configured events

Add to Cart (mandatory for e-commerce)

Example:

Javascript

GF.API("event", {
  name: "Add to Cart",
  properties: {
    eventType: "add-to-cart-v1",
    value: 118.26,
    currency: "USD", //any supported currency code
    productId: "item-34454",
    quantity: 2,
    cart: [{
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      },
      {
        productId: "item-34454",
        quantity: 2,
        itemPrice: 59.13
      }
    ]
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "add-to-cart-v1"	string
value*	The value added to the cart. If more than one item is added, contains the unit price multiplied by the quantity. For example, for 99 dollars 99 cents it's 99.99	float
currency	The currency used for the value (Supported standard - ISO 4217, letter code, for example, "USD"). Optional but required for multi-currency sites	string
productId*	SKU as in the feed	string
quantity*	The number of items added to the cart	integer, positive
cart	The current state of the cart, including the last item added. Items must be listed in the order they were added, from oldest to newest	array
Product in cart object:
productId*	SKU as in the feed	string
quantity*	The number of units of this item in the cart	integer, positive
itemPrice*	The price of one item after discounts (if any)	float

Common mistakes:

In the Add to Cart event, the quantity parameter is often passed incorrectly. This parameter should reflect the actual number of items added to the cart, not the sum of all units after the action. Example: there were 2 items of a specific SKU in the cart, and we added 1 more item of the same SKU. In the event, we expect to see quantity=1.

Purchase (mandatory for e-commerce)

Example:

Javascript

GF.API("event", {
  name: "Purchase",
  properties: {
    uniqueTransactionId: "123456",
    eventType: "purchase-v1",
    value: 90.55,
    currency: "USD", //any supported currency code
    cart: [
      {
        productId: "item-34454",
        quantity: 1,
        itemPrice: 65.87,
      }, {
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      }
    ]
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "purchase-v1"	string
uniqueTransactionId	Unique transaction ID. Helps to deduplicate transaction events. Maximum 64 characters	string
value*	Monetary value of the event. For example, 99 dollars 99 cents is 99.99	float
currency	The currency used for the value (Supported standard - ISO 4217, letter code, for example, "USD"). Optional but required for multi-currency sites	string
cart*	Products must be listed in the order they were added - from the oldest to the newest
Product in cart object:
productId*	SKU, same as in the feed	string
quantity*	Amount of units of this product in the cart	integer, positive
itemPrice*	Cost of one unit of the product after discounts (if any) have been applied	float

Remove From Cart

Example:

Javascript

GF.API("event", {
  name: "Remove from Cart",
  properties: {
    eventType: "remove-from-cart-v1",
    value: 34.45,
    currency: "USD", //any supported currency code
    productId: "gswefd-34-454",
    quantity: 1,
    cart: [{
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      },
      {
        productId: "item-34454",
        quantity: 1,
        itemPrice: 34.45
      }
    ]
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "remove-from-cart-v1"	string
value*	Cost of the removed item(s). If more than one unit of an item is removed, this should contain the total cost. If multiple SKUs are removed at once, it is recommended to use Sync cart event	float
currency	The currency used for the value (Supported standard - ISO 4217, letter code, for example, "USD"). Optional but required for multi-currency sites	string
productId*	SKU, same as in the feed	string
quantity*	Number of units of this product removed from the cart	integer, positive
cart	Current state of the cart, excluding the removed item. Products must be listed in the order they were added - from oldest to newest	array
Product in cart object:
productId*	SKU, same as in the feed	string
quantity*	Number of units of this product in the cart	integer, positive
itemPrice*	Cost of one unit of the product after discounts (if any) have been applied	float

Sync cart

This event updates the current state of the cart. This event is recommended in the case of bulk changes in the cart or changes to the cart contents without user involvement, for example:

1. Server-side cart update (e.g., items that ran out of stock during the user's session automatically removed from the cart)

2. Cart update upon user authorization (combining carts before/after login)

3. Cart update upon entering the site, including auto-login (e.g., automatic loading of a mobile cart when entering the web platform)

4. Mass removal of items from the cart - complete cart clearing or removal of a number of positions with one click

Example:

Javascript

GF.API("event", {
  name: "Sync cart",
  properties: {
    eventType: "sync-cart-v1",
    currency: "USD", //any supported currency code
    cart: [ 
      {
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      },
      {
        productId: "item-34454",
        quantity: 1,
        itemPrice: 34.45
      }
    ]
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "sync-cart-v1"	string
currency	The currency used for the value (Supported standard - ISO 4217, letter code, for example, "USD"). Optional but required for multi-currency sites	string
cart*	Current state of the cart, excluding the removed item/including the added item. Products must be listed in the order they were added - from oldest to newest	array
Product in cart object:
productId*	SKU, same as in the feed	string
quantity*	Number of units of this product in the cart	integer, positive
itemPrice*	Cost of one unit of the product after discounts (if any) have been applied	float

Adding to Wishlist/Favourites

Example:

Javascript

GF.API("event", {
  name: "Add to Wishlist",
  properties: {
    eventType: "add-to-wishlist-v1",
    productId: "item-34454"
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "add-to-wishlist-v1"	string
productId*	SKU, same as in the feed	string

Attribute Change

Used when the user changes the attribute of the displayed product, such as size or color.

Example:

Javascript

GF.API("event", {
  name: "Change Attribute",
  properties: {
    eventType: "change-attr-v1",
    attributeType: "Color",
    attributeValue: "Navy Blue"
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "change-attr-v1"	string
attributeType*	Color, size, brand, etc., must match the column header in the feed	string
attributeValue*	New value, must match the values in the feed	string

The attribute type and value must match the values in the feed.

Product Filtering

Used when the user filters products by a field value (usually in a PLP).

Example:

Javascript

GF.API("event", {
  name: "Filter Items",
  properties: {
    eventType: "filter-items-v1",
    filterType: "Color", // Name of filter (Color, Size, Brand, Fit, Author, Keyword, Category...)
    filterNumericValue: 4
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "filter-items-v1"	string
filterType*	Filter name (color, size, brand, etc.). Must match the item property specified in the feed	string
filterNumericValue*	Only one value is accepted: filterNumericValue OR filterStringValue, but not both. This affects the available segmentation conditions.	number
filterStringValue**	Only one value is accepted: filterNumericValue OR filterStringValue, but not both. This affects the available segmentation conditions.	string

Keyword Search

Example:

Javascript

GF.API("event", {
  name: "Keyword Search",
  properties: {
    eventType: "keyword-search-v1",
    keywords: "my search string"
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "keyword-search-v1"	string
keywords*	Search query as entered by the user	string

Aggregating Requests for Live Search

In cases when live search is available on the site (also called search-as-you-type), it is necessary to perform query aggregation when sending events. When using this method, we don’t pass every entered character in a separate event, and only the last input state is sent to the system. For example, when a user enters the query "game", four entries are created: "g", "ga", "gam", and finally, "game". However, only the last input "game" is sent to the system, ignoring the previous ones.

When sending the event, it is necessary to indicate a delay after which the request will be sent to the system. For example, if a user starts entering "gam", stops, and 2 seconds have passed (recommended as maximum delay), the request "gam" should be sent to the system. Next, if the user decides to continue inputting, adds "game", and stops, after 2 seconds, the second input result "game" should be sent. It is recommended to sync the sending of the event with the search query rendering for the user, or when the user hits "Enter" or clicks on "Search".

Promo Code Entry

Example:

Javascript

GF.API("event", {
  name: "Promo Code Entered",
  properties: {
    eventType: "enter-promo-code-v1",
    code: "..."
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "enter-promo-code-v1"	string
code*	Promo code	string

Sort Items

Example:

Javascript

GF.API("event", {
  name: "Sort Items",
  properties: {
    eventType: "sort-items-v1",
    sortBy: "price",
    sortOrder: "ASC"
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "sort-items-v1"	string
sortBy*	Any of the parameters: price, term, popularity, rating, and more. The parameter must match the name of a column in the feed (if there are matching columns) or be a human-readable value	string
sortOrder*	Ascending or descending (ASC or DESC)	string

Newsletter Subscription

Example:

Javascript

GF.API("event", {
  name: "Subscription",
  properties: {
    eventType: "newsletter-subscription-v1",
    hashedEmail: "SHA-256 hash of the email",   }
});
// and/or
GF.API("event", {
  name: "Subscription",
  properties: {
    eventType: "newsletter-subscription-v1",
    cuid: "...", 
    cuidType: "..." 
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "newsletter-subscription-v1"	string
hashedEmail*	Email, converted to lowercase and hashed on the client side in SHA-256 format	string
cuid**	If identification is not by email, any other customer ID is passed (optional)	string
cuidType*	When passing cuid, its type is passed (required when passing the "cuid" field)	string

cuid can represent any internal identifier, such as CRM ID, mobile phone hash, and others.

We strongly recommend to hash any identifiers containing personal data.

Signup

Example:

Javascript

GF.API("event", {
  name: "Signup",
  properties: {
    eventType: "signup-v1",
    hashedEmail: "SHA-256 hash of the email",   }
});
// or/and
GF.API("event", {
  name: "Signup",
  properties: {
    eventType: "signup-v1",
    cuid: "...", 
    cuidType: "..." 
  }
});

properties container definition:

Property	Description	Type
eventType*	Must be "signup-v1"	string
hashedEmail*	Email, converted to lowercase and hashed on the client side in SHA-256 format	string
cuid**	If identification is not by email, any other customer ID is passed (optional)	string
cuidType*	When passing cuid, its type is passed (required when passing the "cuid" field)	string

cuid can represent any internal identifier, such as CRM ID, mobile phone hash, and others.

We strongly recommend to hash any identifiers containing personal data.

Login

Example:

Javascript

GF.API("event", {
  name: "Login",
  properties: {
    eventType: "login-v1",
    hashedEmail: "SHA-256 hash of the email"
	}
});
// or/and
GF.API("event", {
  name: "Login",
  properties: {
    eventType: "login-v1",
    cuid: "...", 
    cuidType: "..." 
  }
});

properties container definition:

Property	Description	Тип
eventType*	Must be "login-v1"	string
hashedEmail*	Email, converted to lowercase and hashed on the client side in SHA-256 format	string
cuid**	If identification is not by email, any other customer ID is passed (optional)	string
cuidType*	When passing cuid, its type is passed (required when passing the "cuid" field)	string

cuid can represent any internal identifier, such as CRM ID, mobile phone hash, and others.

We strongly recommend to hash any identifiers containing personal data.

User Identification

There are two globally accepted types of user identifiers:

1. Hashed email of the user, i.e., the encrypted email address or phone number of the user. hashedEmail.

   1. If passing an email, turn it to lowercase, then hash. Example:

      [email protected] → [email protected] - convert to lowercase

      [email protected] → f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a - SHA256 hash

   2. If passing phone number, then format

      971XXXXXXXXXX (start with country code, e.g. 971, without "+", dashes, and brackets), then hash.

2. Cuid - Customer Unique Identifier. Cuid can be any unique value used to identify a user - it can be a phone number, CRM ID, or any other ID.

We strongly recommend to hash any identifiers containing personal data.

Custom Event

If you want to track an event not listed above, the following structure can be used to design it:

GF.API("event", {
  name: "EVENT_NAME",
  properties: {  
    FIRST PROPERTY NAME: "PROPERTY VALUE",  // Optional, string
    SECOND PROPERTY NAME: "PROPERTY VALUE",  // Optional, string
    value: 199.99 // Optional, float
  }
})