# Manual Event Integration

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html)

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.

> **IMPORTANT:**
> 
> Events API calls are unauthenticated. Do not send an OAuth `Authorization` header with event requests.

<a id="_before_you_start"></a>

## Before you start

-   Complete [Item synchronization](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/item-sync-options.html) so event item IDs resolve to catalog items.
    
-   Agree on the [Event model and tracking contract](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/tracking-events.html).
    
-   Apply the [identity and consent rules](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/user-identity-consent.html) consistently across events and recommendation requests.
    
-   Confirm the environment, channel, page types, and optional site context with Froomle.
    

<a id="_choose_a_delivery_channel"></a>

## 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](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html). |
| 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. |

<a id="ManualEventsApi"></a>

## Events API integration

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

<a id="_browser_and_mobile_delivery"></a>

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

<a id="ManualTrackingPixel"></a>

### Track message opens with an image request

First check whether the email service provider (ESP) or customer engagement platform can capture open events and forward them server-to-server to the Froomle Events API. Prefer provider-native events when available because the provider can apply its own handling for mail privacy proxies, image caching or prefetching, and other platform-specific behavior. Use image-based tracking as a fallback when the platform can load an image but cannot forward a suitable event. 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:

```html
<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.

> **IMPORTANT:**
> 
> 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.

> **NOTE:**
> 
> 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](https://docs.froomle.com/froomle-doc-main/v2/js_lib/email-campaign-attribution.html). If the landing page does not use the SDK, send the agreed `batch_click_on_recommendation` event through a manual integration.

<a id="_backend_delivery"></a>

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

<a id="_construct_the_payload"></a>

### Construct the payload

Every payload must satisfy the [Event Model and Tracking Contract](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/tracking-events.html). 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.
    

<a id="_handle_failures"></a>

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

<a id="ManualPubSub"></a>

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

<a id="ManualSftp"></a>

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

<a id="_rollout_order"></a>

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

<a id="_validate_the_integration"></a>

## Validate the integration

Use [QA & Monitoring](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/qa-monitoring.html) to compare traffic volumes, inspect API failures, and detect missing or inconsistent events. For exact fields and endpoint details, use the [Events API Reference](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html).

<a id="_related_topics"></a>

## Related topics

-   [Manual recommendation integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/recommendations.html)
    
-   [Performance and metrics](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/performance-metrics.html)
    
-   [Resilience and fallbacks](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/resilience-and-fallbacks.html)