Manual Recommendation Integration

Use this guide when your application requests and renders recommendations without the frontend SDK owning the request and rendering flow. This is the primary method for backend, mobile, and custom API integrations.

This step requires a synchronized item catalog. Page and business event tracking should already be live before recommendation placements are enabled.

Before you start

Request lifecycle

  1. Obtain and cache a valid bearer token on a trusted backend.

  2. Build the request from the agreed lists, page context, identity, histories, filters, and exclusions.

  3. Send the request to the environment-specific Recommendations API endpoint.

  4. Read the returned lists and preserve their attribution metadata.

  5. Render the selected items or apply the agreed fallback behavior.

  6. Send an impression for every recommendation shown and a click_on_recommendation for every recommendation clicked.

For endpoint paths, exact fields, and response schemas, see the Recommendations API Reference.

Authentication and request domain

Keep OAuth client credentials on a backend and send the resulting bearer token with authenticated recommendation requests. If you use a custom hostname, follow Custom Domain (CNAME) and replace the default request host consistently.

Recommendation requests require the OAuth bearer token described above. Tracked events remain unauthenticated and must not reuse the recommendation Authorization header.

Build the request

The request shape is shared across integration methods. Use Recommendation Request Model for the behavior of lists, aliases, context, histories, exclusions, filters, and response enrichment.

Ensure that:

  • context_item and history item IDs exist in the synchronized catalog.

  • context_item_type accompanies context_item.

  • device_id and user_id follow the shared identity and consent rules.

  • Each placement uses the agreed list_name, page type, and channel.

Preserve response attribution

Do not discard request_id, list_name, or an applicable user_group before rendering. Manual recommendation events need that metadata to attribute impressions and clicks to the correct request, placement, and benchmark branch.

Your application owns rendering in this method. It must therefore retain enough state to associate every rendered item with the recommendation response that supplied it.

Benchmarking

Follow the shared A/B testing and benchmarking contract. When Froomle assigns the branch, use the returned user_group as the rendering authority. For customer-managed control traffic, pass the agreed control group on the request and on its manually tracked recommendation events. Do not invent or hard-code a request_id.

Froomle-managed request example

Send a standard request to POST /{environment}/recommendations/requests without user_group:

{
  "device_id": "device-123",
  "user_id": "user-123",
  "page_type": "home",
  "lists": [
    {
      "list_name": "home_page_trending",
      "list_size": 10
    }
  ]
}

For a customer-vs-Froomle benchmark, a customer/control response can contain an empty recommendation list:

{
  "request_id": "req-abc-123",
  "user_group": "customer",
  "lists": [
    {
      "list_name": "home_page_trending",
      "items": []
    }
  ]
}

Render the customer/control content because user_group resolves that branch, not merely because items is empty.

Customer-managed request example

For the customer/control branch, pass the group name agreed with Froomle:

{
  "device_id": "device-123",
  "user_id": "user-123",
  "page_type": "home",
  "user_group": "customer",
  "lists": [
    {
      "list_name": "home_page_trending",
      "list_size": 10
    }
  ]
}

For the treatment/Froomle branch, send the same request without user_group so normal Froomle version resolution applies.

Hybrid browser tracking

A backend may fetch recommendations while the frontend SDK tracks browser events. For this supported advanced pattern, preserve the returned attribution metadata in the rendered DOM as described in Backend-Fetched Recommendations and SDK Event Tracking.

Failure handling

Set an application-level timeout and ensure recommendation failures do not block the main page or application flow. Handle empty responses and request failures using the agreed fallback strategy. See Resilience and fallbacks for production patterns.

Related topics