Event Collection API: Common Payload 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.

Attribution Window

The Attribution Window is the time frame during which a user's action can be traced back to the source that led them to take that action. For example, if a user searches for a product on Eureka, clicks on it, adds it to their cart, and then makes a purchase, the attribution window is the time frame during which the search engine can trace the user's actions back to the initial search query.

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

Each value must be either a numeric string (e.g. "1", "7", "14", "30", "90") or "session". The array must contain at least 1 value for add-to-cart and purchase events. Each value must not contain spaces.

When sending data for events like adding items to carts or purchases, consider the time window your event falls within. Only include values from the predefined windows that encompass the event timeframe. For instance, if an item was added to the cart on the eighth day, you would only send the values for "14", "30", and "90" because those windows include the eighth day.

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

Session definition: A session is a group of user interactions with your website that take place within a given time frame. A session ends after:

• 30 minutes of inactivity

Find Locale

The locale (e.g. tr_TR, en_US, en_GB) identifies the language and region for your integration. It is used as part of the X-PARTNER-CONFIG-KEY header: {PARTNER_ID}-{LOCALE}.

To retrieve the locale:

Open your website in a browser, then run the following in the browser console (F12 > Console):

Insider.systemRules.call('getLocale')

Output example: 'tr_TR' or 'en_US'

The Insider JavaScript object must be loaded on the page for this to work. If it is not available, check with your Insider One team for the correct locale value.

For you available locales you can also check Catalog Locales.

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.

You can retrieve the Insider ID in mobile apps via the Insider SDK using the following methods:

• JavaScript (Hybrid / WebView):

insider.getUserId();
// Returns short-formatted ID, e.g. 'df0307392228d7eb'

• Android (Kotlin):

val insiderID = Insider.Instance.getInsiderID()

• iOS (Swift):

let insiderID = Insider.getInsiderID()

Mobile IDs are short-formatted (e.g. df0307392228d7eb), which is different from the web's longer dot-separated format.

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.

TraceId

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

Search Analytics TraceId

What traceId does:

• The traceId is used to uniquely identify a single search or listing interaction in the Eureka Analytics dashboard. When events are written to the database, each product in the event becomes a separate row. All rows sharing the same traceId are grouped and counted as one interaction.

• For example, if a search event contains 10 products, all 10 rows have the same traceId, and they count as 1 search in analytics. If the user changes sorting and 3 new products are sent (still with the same traceId), the total is now 13 rows but still 1 search in analytics.

• This uniquification applies to search, product-list-view, and product-click events.

• This does NOT apply to add-to-cart and purchase events, these are counted directly by quantity, not uniquified by traceId.

Rules:

• A new traceId is generated only when the user performs a new search or navigates to a different listing page.

• Sorting changes, filter changes, and pagination do not generate a new traceId.

• Store the traceId with the products and reuse it for all events within the same search or listing session. For example, you can store it in your local storage for your web application.

• It's important to distinguish between web sessions and traceId. Unlike a web session which encompasses your entire browsing activity, a traceId focuses on a single search or listing page view.

Recommended format: Base64-encoded form of {userid}+{~}+{search query}+{~}+{ISO 8601 Date and time in UTC}

For example:

• 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 query text and timestamp match, search sessions are generated uniquely per user, ensuring that analytics, personalization, or tracking don't mix results between different users.

Uniqueness Example:

Deduplication example:

Suppose userA searches for "queryA" (traceId: dXNlckErcXVlcnlBKzIwMjUtMDgtMjBUMTE6MzA6MDBa).

The search returns 10 products → 10 rows in the database, all with the same traceId → counted as 1 search in analytics.

userA changes sorting → 3 new products sent with the same traceId → now 13 rows total → still 1 search in analytics.

userA searches for "queryB" → a new traceId is generated → this becomes a separate search in analytics.

Category and Brand Analytics TraceId

A unique traceId must be generated for every new Category or Brand page visit. This traceId should remain the same across sorting changes, filter changes, pagination, and facet applications within the same page.

Deduplication example:

• User visits "categoryA > categoryB" (traceId: trace-cat-456).

• Page shows 24 products → 24 rows in the database, all with the same traceId → counted as 1 page view in analytics.

• User changes sorting → 5 new products sent with the same traceId → now 29 rows → still 1 page view in analytics.

• User navigates to a different category → a new traceId is generated → this becomes a separate page view in analytics.

The traceId for category/brand pages does not need to follow the base64 encoding convention used for search traceIds. It can be any unique string identifier.

Fallback Mechanism:

SessionId

The gassid value is used as the web session identifier. It tracks user sessions at 30-minute intervals and renews them 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 One’s InOne platform. If the gassid is not present, it must generate and provide a new one.

SessionId for Mobile Apps

A publicly accessible, pre-built session ID is not available from the Insider SDK for Mobile Apps. For Mobile integrations, you need to generate and manage the session ID on your client side.

The sessionId is used to analyze consecutive user sessions and understand user behavior across search and category result pages. Define a session concept in your app, for example, based on a 30-minute inactivity timeout (similar to the web gassid behavior), and generate a unique sessionId accordingly.

Guidelines:

• Generate a new sessionId when a new session starts (e.g., app launch, or after 30 minutes of inactivity).

• Reuse the same sessionId for all events within the same session.

• The format is a free-form string without spaces.

StrategyId

strategyId is an optional field used to track which merchandising strategy was shown to the user.

When to use strategyId:

strategyId Format:

Free-form string without spaces. Examples: "strategy-relevance-v2", "ab-test-price-sort".

Where to send strategyId:

If strategyId is not sent, the event is recorded without strategy association. Sending it enables strategy-based analysis in the Analytics dashboard.

Integration Type

Every event request requires the integrationType field. This field indicates through which integration method the event is being sent.

If you are performing an API integration, you should send "api" as the integrationType value. This ensures events are correctly categorized in the Analytics dashboard.

Platform

This field specifies the platform on which the application is running.

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. Consistency is essential; arbitrary or inconsistent custom values can fragment analytics and inflate reporting dimensions.

Source Field

Indicates the component in which the search engine is used. This field helps identify the context of the search interaction.

Source-dependent required fields (for click, add-to-cart, purchase):

Legacy source mapping:

Source-Dependent Product Field Validation:

The API enforces strict rules on which product fields are allowed based on the source value:

• When the source is search-popup or search-listing: query is expected in the product, listValue should not be provided.

• When the source is category-listing or brand-listing: listValue is expected in the product; the query should not be provided.

Sending the wrong combination will result in a validation error.

Created At

Timestamp indicating when the event was created.

• Must follow RFC 3339 date-time format.

• Includes date, time, and time zone offset (Z) for UTC.

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

• 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 are:

Pagination & Result Fields

The following fields describe the search or listing result set and pagination state. They are sent at the event level (not inside the product object).

For product-click, add-to-cart, and purchase events, resultCount, itemsPerPage, totalPages, and currentPage are sent inside the product object rather than at the event level.

Product Properties

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.

Click Position

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

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.

Examples:

The API internally splits this into an array for analytics processing:

• Input: "categoryA~categoryB~categoryC"

• Output: ["categoryA", "categoryB", "categoryC"]

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

The listValue must be consistent across all events in the same flow. The value used in the product-list-view event should match the value sent in subsequent product-click and add-to-cart events.

Preferred Currency

The main currency of your website/app. This is the base (reference) currency used for analytics and reporting. Although product prices may exist in multiple currencies, the preferredCurrency ensures consistency by defining the single currency in which all analytics are presented.

You can find the default currency on the Account Settings page. In addition, you can also find it with this method on console:

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.

Sorting

The sorting parameter can only be one of the predefined sorting types. It needs to be added to the event payload based on the current search result selection.

Sorting values are case-sensitive and must not contain spaces. If the user changes the sorting type to a value other than "Relevancy", merchandising rules are disabled.

Empty string is also accepted and defaults to Relevancy. Any value not in this list will result in a validation error.

Facet

The facet field has the following properties:

"facets": [
  { "label": "Color", "field": "color_en", "values": ["Red", "Blue"] },
  { "label": "Size", "field": "size_en", "values": ["M", "L"] },
  { "label": "Price", "field": "price_en", "values": ["100", "500"] }
]

If the price is filtered, please send a list with a maximum of two values (min and max).

Default Values

The API applies the following defaults when fields are missing or empty:

The integrationType value "app" is automatically normalized to "api" by the server.

Field Fallback Behavior

TraceId and SearchSessionId (Bidirectional Fallback):

For all event types, the API applies a bidirectional fallback between traceId and searchSessionId:

• If traceId is provided but searchSessionId is empty → searchSessionId is set to traceId.

• If searchSessionId is provided but traceId is empty → traceId is set to searchSessionId.

For click, add-to-cart, and purchase events, this fallback works in three layers:

1. Product-level traceId → Product-level searchSessionId

2. Product-level searchSessionId → Product-level traceId

3. Event-level searchSessionId → Product-level traceId and searchSessionId

Position Fallback Chain:

• searchPosition: If 0 → falls back to displayPosition → falls back to position

• displayPosition: If 0 → falls back to searchPosition chain

• clickPosition: If 0 → falls back to searchPosition → falls back to position

Product Object

The full product object with all possible fields across event types:

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

This table provides a structured reference for all product parameters across different event types. Check marks indicate whether a parameter is included in a given event type.

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

The updates listed below are now available. Review and adopt these changes to improve the completeness and accuracy of analytics. Event-level values remain supported for backward compatibility.

New product fields by event type: