Manual Event Integration

Use this guide when your application sends Froomle events without the frontend SDK owning event delivery. The integration may run in a backend, mobile application, custom browser implementation, Pub/Sub pipeline, or offline export.

Events API calls are unauthenticated. Do not send an OAuth Authorization header with event requests.

Before you start

Complete Item synchronization so event item IDs resolve to catalog items.
Agree on the Event model and tracking contract.
Apply the identity and consent rules consistently across events and recommendation requests.
Confirm the environment, channel, page types, and optional site context with Froomle.

Choose a delivery channel

Channel	Use when	Delivery behavior
Events API	Events must be available in near real time from a browser, mobile application, or backend.	Send events to the tenant Events API endpoint. See the Events API Reference.
Pub/Sub (beta)	You already operate a streaming pipeline and have coordinated the connection with Froomle.	Map your stream to the Froomle event contract and publish to the provisioned Pub/Sub integration.
SFTP	Events are not time-sensitive, such as historical events, offline purchases, or campaign opens.	Upload agreed CSV, TSV, or JSON files in batches. Do not use SFTP for real-time page or recommendation events.

Channel

Use when

Delivery behavior

Events API

Events must be available in near real time from a browser, mobile application, or backend.

Send events to the tenant Events API endpoint. See the Events API Reference.

Pub/Sub (beta)

You already operate a streaming pipeline and have coordinated the connection with Froomle.

Map your stream to the Froomle event contract and publish to the provisioned Pub/Sub integration.

SFTP

Events are not time-sensitive, such as historical events, offline purchases, or campaign opens.

Upload agreed CSV, TSV, or JSON files in batches. Do not use SFTP for real-time page or recommendation events.

Events API integration

Use the environment-specific endpoint provided during account setup. The API accepts event payloads that follow the shared event contract.

Browser and mobile delivery

Send events as they occur. Events produced at the same moment, such as multiple recommendation impressions, may be sent in one request. Do not block page rendering or navigation while waiting for the event response.

Backend delivery

Batch events during traffic peaks instead of creating one HTTP request per event. A batch interval of approximately 500 milliseconds is recommended; delays up to one second are acceptable. Longer delays reduce how quickly new behavior can influence recommendations.

Construct the payload

Every payload must satisfy the Event Model and Tracking Contract. In particular:

Use the same item_id and item_type values as the synchronized catalog.
Send device_id and, for a consented logged-in user, user_id according to the shared identity rules.
Include the agreed page, channel, site, subscription, campaign, and source context when applicable.
For recommendation impressions and clicks, preserve the returned request_id and list_name; include the resolved user_group when the benchmark contract requires it.

Handle failures

Validate 4xx responses and correct the payload instead of retrying it unchanged. Use bounded retries with backoff for transient failures such as rate limits, timeouts, and 5xx responses. Keep retry queues bounded so an event-delivery failure cannot exhaust application resources or break the user-facing experience.

Pub/Sub integration (beta)

Agree with Froomle which event types will be shared.
Receive the Pub/Sub project and access configuration.
Map source records to the Froomle event contract.
Publish the agreed CSV, TSV, or JSON representation.
Complete validation with the Froomle team before production traffic starts.

Pub/Sub support requires coordination with Froomle.

SFTP integration

Use file delivery only for non-time-sensitive or historical data. Agree on the file schema, naming convention, upload location, and processing cadence with Froomle before sending production files.

Rollout order

Send page_visit, detail_pageview, and applicable business events first.
Validate identifiers, event volumes, and API responses.
Add recommendation placements.
Send impression when a recommendation is shown and click_on_recommendation when it is clicked.
Confirm that recommendation events retain the request and benchmark attribution returned with the recommendation.

Validate the integration

Use QA & Monitoring to compare traffic volumes, inspect API failures, and detect missing or inconsistent events. For exact fields and endpoint details, use the Events API Reference.