Eureka Event Collection API

The Eureka Event Collection API collects user engagement data from Insider One's Eureka search experience. This API enables you to send search analytics data to Insider One if you do not use the Eureka Search Pop-up or SDK.

If you are using the Eureka Search Pop-up, event logs are tracked automatically; no additional integration is needed. If you are using the Eureka SDK, refer to the Eureka SDK Campaign Implementation guide for SDK-based event tracking.

The primary purpose of the API is to enable you to collect the metrics needed to measure the success of the search experience. These metrics allow you to measure how successful the search experience you provide to your users is.

After integrating with the Event Collection API, you can visit the Eureka Analytics dashboard to visualize engagement funnel metrics and keyword-based search insights.

Use cases

You can use the Eureka Event Collection API for your different needs:

• Custom Search UI

If you use your own search interface instead of the Eureka Search Pop-up or SDK, you need to send user engagement data through this API.

• Mobile App Integration

When you use Eureka search results in your mobile app, but want to send engagement data from the server side.

• Server-Side Tracking

When you want to collect search, click, add-to-cart, and purchase events server-side (backend-to-backend).

• Category/Brand Listing Pages

If you manage your listing pages with the Eureka Category Merchandising API, you can use this API to collect engagement data from those pages.

• A/B Testing Analytics

When running A/B tests through Eureka SDK campaigns and measuring the performance of different variations.

To start using the API, you need the following information from the Inone settings:

After you receive an API key, you can use it to authenticate your requests.

Endpoint and Headers

The Event Collection API operates through a single endpoint. You only need to configure the payload based on the event type. The API accepts only POST requests.

POST https://eurekaevent.api.useinsider.com/api/v1/events

Event Types

The Eureka Event Collection API supports the following event types. Click on each event type for detailed payload documentation.

Request Payload

The configuration for event payloads requires specific settings, and you can find detailed information for each payload type on its corresponding child page.

Within the event payload, you will find common fields such as traceId, strategyId, sorting, source, facets, and product fields. To prepare defined object structures or identifications, refer to Common Properties.

Send the product fields as parameters, including their field names and data types as stated. If any of the required fields is missing, the event will not be inserted.

If any parameter not defined in the specification is sent via the Event API, it will not be processed.

Response

• Success Response

{
  "status": "Success"
}

• Error Response (HTTP 5XX)

{
  "status": "Error",
  "code": 500,
  "message": "Internal Server Error"
}

• Validation Error Response (HTTP 4XX)

{
  "code": 400,
  "message": "Validation Exception Occurred",
  "validations": [
    "Key: 'AddToCart.SearchSessionId' Error:Field validation for 'SearchSessionId' failed on the 'required' tag"
  ]
}

Validations

While using the Event Collection API, you may come across two types of exceptions: 

• AuthException

• ValidationException

You are expected to adjust the request according to the information provided in the exception message.

AuthException

AuthException indicates an exception during API usage, indicating that the x-auth-token request header parameter does not match the token provided in the Insider One InOne panel.

Sample Response

{
  "status": "AuthException",
  "code": 403,
  "message": "Partner token authentication is unsuccessful.",
  "validations": null
}

Validation Exception

Validation Exception indicates an exceptional scenario in which the event payload or header is not as expected. The Event Collection API requires the x-partner-config-key parameter in the request header, and it must match your partner ID.

Event-related validation details for each event are provided on the relevant event page. Below, you can see these validations along with explanations:

• required: Field is mandatory and must be provided.

• required unless no result: Required when results exist, optional when there are no results.

• date time: Must be in RFC 3339 / ISO 8601 format.

  • Example: 2023-09-27T14:40:35.967+03:00

• past date: Date must not indicate a future time.

• url: The field value must be a URL string format.

• one of: The field can have only one of the indicated values.

• min: The field value must be greater than or equal to the given threshold.

• max: The field value must be lower than or equal to the given threshold.

• excludes space: Must not contain space characters.

• non_blank_string: Must not be a blank string.

Sample Response

{
  "status": "ValidationException",
  "code": 400,
  "message": "Validation Error Occurred",
  "validations": [
    "Event type is required"
  ]
}

Limitations

• All functions must be executed with a simple HTTPS POST request.

• Only new data can be sent via this API. No data can be retrieved.

• x-partner-config-key must be sent in the request header.

• Parameters not defined in the specification will not be processed (ignored).

• If any required field is missing, the event will not be recorded.