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

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.

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.

Track message opens with an image request

Use image-based tracking when an email or messaging platform can load an image but cannot send a JSON POST request. Froomle can expose an agreed event type, typically batch_open, as a GET request on your environment-specific Events API endpoint.

The tracking flow is:

  1. Your campaign template includes an image whose src is the Events API URL with the event fields encoded as query parameters.

  2. The email or message client requests that URL when it loads the image.

  3. The Events API validates and records the event.

  4. For a valid event, the API redirects the client to a small Froomle-hosted PNG so image loading can complete. An invalid event returns an HTTP 400 response instead.

For example:

<img
  src="https://{subdomain}.froomle.com/api/{environment}/events?event_type=batch_open&amp;campaign_id=spring-newsletter-2026-05-13&amp;page_type=email&amp;channel=email&amp;user_id=opaque-user-456"
  width="1"
  height="1"
  alt="">

Replace the subdomain and environment placeholders with the values supplied by Froomle. URL-encode every query-parameter value, and use the exact event fields agreed for your environment. GET event types and their required fields are enabled by Froomle configuration, so confirm the contract before sending production traffic.

Query parameters can appear in mail-provider, proxy, and server logs. Use only opaque identifiers; never include email addresses, names, authentication tokens, or other directly identifying or secret values in the tracking URL. Only add the pixel when your consent and privacy rules allow the event to be sent.

Image loading is not a precise measure of a human opening a message. Mail clients may block, cache, prefetch, or proxy images, which can cause missing, delayed, or repeated requests. Treat batch_open as a delivery-channel signal rather than an exact count of people who read the message.

This image request records the open only. For recommendation clicks that land on a page using the Frontend SDK, use Email Campaign Recommendation Attribution with the SDK. If the landing page does not use the SDK, send the agreed batch_click_on_recommendation event through a manual integration.

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 user_group only for an externally assigned customer/control branch.

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)

  1. Agree with Froomle which event types will be shared.

  2. Receive the Pub/Sub project and access configuration.

  3. Map source records to the Froomle event contract.

  4. Publish the agreed CSV, TSV, or JSON representation.

  5. 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

  1. Send page_visit, detail_pageview, and applicable business events first.

  2. Validate identifiers, event volumes, and API responses.

  3. Add recommendation placements.

  4. Send impression when a recommendation is shown and click_on_recommendation when it is clicked.

  5. 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.

Related topics