Event Collection API: Common Properties

The Event Collection API has established a set of common data types for event properties. This approach ensures consistency and clarity across various event payloads. These shared data types serve as standardized structures that can be reused in different contexts, promoting a consistent approach to data representation.

Event Payload Properties

userId

Every user must be assigned a unique identifier, tailored to your specific criteria and definitions. If you can obtain the value using the Insider JavaScript object, please provide that value. If it's not retrievable, send a userId using characters from the base64 scheme without any symbols.

It is available in local storage with the name spUID, or you can use Insider.getUserId() method on the console.

campId

The campId serves as a unique identifier. 

By default, it is set to 999999. If you want to use a different value, contact the Insider One team.

variantId

The variationId represents the unique identifier for a specific campaign variation.

By default, it is set to 999999. If you want to use a different value, contact the Insider One team.

Trace Id

Trace Id definition changes by leveraging Search Analytics, Category Analytics, and Brand Analytics data.

Search Analytics Trace Id

Rules for traceId

• traceId is a unique identifier for a search query.

• A new ID is generated only when the user performs a new search.

• For all subsequent events related to that search (click, add-to-cart, purchase), you must use the same traceId.

• This ensures search performance metrics like Click-Through Rate (CTR) and Conversion Rate can be calculated correctly.

• To keep this consistency, you should store the traceId products and reuse it for all related events. For example, you can store it in your local storage for your web application.

For uniqueness, assign a distinctive identifier to each trace. It's important to distinguish between web sessions and traceId. Unlike a web session, which encompasses your entire browsing activity on a website, a traceId focuses on a single search.

It should be the base64-encoded form of {userid}+{~}+{search query}+{~}+{ISO 8601 Date and time in UTC}.

• Recommended value:  YXBwbGV+MjAyMy0xMi0xNFQxMToyMDoyOFo= (base64 encoded form of query and time combination)

• Not recommended value: pear~2023-12-14T11:20:28Z (not base64 encoded)

To retrieve the unique identifier associated with a particular user, use Insider.getUserId() method.

Even if the query text and timestamp match, search sessions are generated uniquely for each user — ensuring that analytics, personalization, or tracking don’t mix results across users.

This table illustrates the uniqueness of the search session id.

For another example, suppose user Jordan interacts with the search results. After searching for "Mike shoes", Jordan clicks on a product, adds an AeroJordan item to the cart, and eventually completes the purchase.

All subsequent event payloads (click, add-to-cart, purchase) must reference the previously generated traceId (Sm9yZGFuK05pa2Ugc2hvZXMrMjAyNS0wOC0yMFQxMTozMDowMFo=). This ensures that the entire sequence of actions is consistently tied back to the original search session.

Category and Brand Analytics Trace Id

For uniqueness, assign a distinctive identifier to each trace. A unique trace ID must be generated for every request made to Category or Brand pages. This trace ID should remain consistent and be resent across all operations, including pagination, filtering, and facet applications.

Session Id

The gassid value is used as the web session identifier. It tracks user sessions in 30-minute intervals and is renewed based on continued user activity. The gassid remains consistent across all requests within the same session and is primarily used for session-based campaign tracking on the Insider platform. If the gassid is not present, it must generate and provide a new one.

Preferred Currency

Specifies the base (reference) currency used for analytics and reporting. Although product prices may exist in multiple currencies, the preferredCurrency ensures consistency by defining the currency in which analytics are presented.

You can find the default currency on the Account Settings page.

Converted Price

Represents the product price converted from its original source currency into the preferredCurrency. This provides a single unified value, regardless of the original currency.

Source Field

Indicates the component in which the search engine is used. This field helps identify the context of the search interaction. The possible values for this field are search-popup, search-listing, category-listing, and brand-listing.

Platform

This field specifies the platform on which the application is running. The possible values for this field are desktop-web, mobile-web, ios, android, and tablet-web. If your use case does not fit into these predefined values, you may provide a custom standardized value.

Use as few distinct values as possible, when predefined values not used. Consistency is essential—arbitrary or inconsistent custom values can fragment analytics and inflate reporting dimensions.

Integration Type

This field specifies the type of user who is accessing the application. The possible values for this field are api, and web.

Display Position

Specifies the product's position on the current page when it is first displayed.

Do not update the position after facets or filters are applied. Always send the product’s position from when it was first displayed within the same traceId. This ensures consistent and accurate tracking across the session.

List Value

The listValue field uses a tilde (~) as a separator to indicate hierarchical categories. Flat categories and brand values can be sent as plain text, without separators.

Input format (in request): "electronics~computers~laptops"

The API internally splits this into an array for analytics processing: ["electronics", "computers", "laptops"]

An empty listValue results in the field being omitted from internal analytics output.

Click Position 

Specifies the position of the product on the current page when it is clicked.

Created At

Timestamp indicating when the event was created.

• Must follow RFC 3339 date-time format.

• Includes date, time, and timezone offset or Z for UTC.

Sample Value:

2025-08-20T14:30:00+03:00 or 2025-08-20T11:30:00Z

• Represents 14:30 local time in Istanbul, Turkey, operating on UTC+3 time zone

• Both values represent the same moment. Z is always UTC+0, while +03:00 explicitly indicates the offset.

Event Type

This field specifies the type of event that is being tracked. The possible values for this field are search, product-click, add-to-cart, and purchase.

Attribution Window

The attribution window is the time frame during which a user’s actions can be traced back to the original source that initiated those actions. For example, if a user searches for a product on Eureka, then clicks the product, adds it to their cart, and completes a purchase, the attribution window defines how long these actions can be attributed to the initial search query.

The sample attribution window values you see are predefined for metric calculations. When sending events, such as add-to-cart or purchase, consider the time window during which the event occurs. Only include values from the predefined windows that cover the event’s timestamp.

For example, if an item was added to the cart on the eighth day, you should send only the values for 14, 30, and 90 days, as these windows include the eighth day.

Sample Values: ["session", "1", "7", "14", "30", "90"]

Your title goes here

If you wish to incorporate session-based attribution into metric calculations, include the session in the attribution window field.

According to Google Analytics, a session is a group of user interactions with a website that occur within a defined time frame. A session starts when the user first lands on the site and ends based on user activity patterns.

A single user can initiate multiple sessions, occurring within the same day or across days, weeks, or months. Once a session ends, a new session can begin. Time-based session expiration typically follows three rules:

• 30 minutes of inactivity

• At midnight — Not applicable to Insider sessions

• Campaign change — Not applicable to Insider sessions

These definitions help ensure consistent and accurate attribution for analytics and performance measurement.

Facet

The facet field has the following properties:

If the price is filtered, please send a list with a maximum of two sizes.

Sorting

The sorting parameter in the search event can only have one value from the predefined sorting types. It needs to be added to the event payload based on the currently selected search result.

• Relevancy

• PriceAsc

• PriceDesc

• MostPopularFirst

• BestRatedFirst

• MostRatedFirst

• NewestFirst

• MostFavoriteFirst

• MostDiscountedFirst

Product

The product field has the following properties:

If catalog supports a groupCode, you must provide it. Without groupCode, group-level analytics will not be available in your analytics page.

Event Support Matrix

The Event Support Matrix table provides a structured reference for all parameters available within the product field across different event payloads. Each row represents a specific parameter, along with the supported event types: Product List View Event, Search Event, Product Click Event, Add to Cart Event, and Purchase Event. The check marks indicate whether a parameter is included in a given event type:

Advanced Analytics – Updates Introduced in the September 01, 2025, Release

Review and adopt these changes to improve the completeness and accuracy of analytics. Event-level values remain supported for backward compatibility.

groupCode Field

The groupCode field is a newly introduced field in this release. It needs to be sent under the product object.

If the catalog supports a groupCode, you must provide it. Without groupCode, group-level analytics will not be available in your analytics page.

Product Field

The product object has been expanded with additional optional fields by event type to provide richer context and analytics:

For Search Event

• groupCode

• convertedPrice

• preferredCurrency

• displayPosition

For Product Click Event

• groupCode

• convertedPrice

• preferredCurrency

• displayPosition

• clickPosition

• query

• facets

• sorting

• resultCount

• itemsPerPage

• totalPages

• currentPage

For Add to Cart Event

• groupCode

• convertedPrice

• preferredCurrency

• displayPosition

• clickPosition

• query

• facets

• sorting

• resultCount

• itemsPerPage

• totalPages

• currentPage

• attributionWindow

For Purchase Event

• groupCode

• convertedPrice

• preferredCurrency

• displayPosition

• clickPosition

• query

• facets

• sorting

• resultCount

• itemsPerPage

• totalPages

• currentPage

• attributionWindow

• source

Position Field

The position value is split into two separate fields: searchPosition and clickPosition.

You can find the detailed definitions in the related section:

• displayPosition

• clickPosition

currentPage Field

The currentPage field has been relocated to the products object and is available for product click, add-to-cart, and purchase event types.

preferredCurrency Field

The preferredCurrency is a newly introduced field in this release.

convertedPrice Field

The convertedPrice is a newly introduced field in this release.