Froomle Web SDK

The Froomle Web SDK is a client-side engine that manages user identity, provides environmental context, and delivers personalized recommendations directly to your frontend. It is designed to work with any architecture: from legacy server-side rendering (PHP) to modern reactive frameworks (React, Vue).

Core Mechanics

Unlike a simple API wrapper, the SDK handles the heavy lifting of a personalization integration:

  • Identity Management: Automatically maintains a first-party cookie (_fr_id) to track user sessions and cross-visit history.

  • Context Provisioning: Collects and transmits the current channel, page_type, and context_item to the recommendation engine.

  • Dual Delivery Modes:

    • Automatic Mode (No-Code): Decorate your HTML with data-froomle-* attributes and let the SDK fill your DOM.

    • Programmatic Mode (Raw JSON): Subscribe to data updates using callbacks and handle rendering in your own framework (React/Vue).

Integration Lifecycle

An SDK integration typically follows these sequential steps:

  1. Initialize: Set your environment and credentials.

  2. Identity: Configure user_id (if authenticated) and consent levels.

  3. Context: Define the current page_type and channel.

  4. Implementation: Choose between Automatic (DOM) or Programmatic (JSON) mode.

Quickstart

Choose the implementation style that best fits your technical stack.

  • Automatic Mode

  • Programmatic Mode

Best for static sites or CMS-based workflows. You define the "slots" in your HTML, and the SDK populates them automatically.

<!-- 1. Initialize & Provide Context -->
<script
  src="https://cdn.jsdelivr.net/npm/@froomle/frontend-sdk@latest/dist/froomle.global.js"
  data-froomle-env="my_env"
  data-froomle-channel="www"
  data-froomle-page-type="home">
</script>

<!-- 2. Define a Recommendation Slot -->
<div data-froomle-reco="recommended_for_you">
  <img data-froomle-param-src="images[0]">
  <h1 data-froomle-param-inner="title"></h1>
</div>

Best for React, Vue, or apps requiring custom UI logic. You receive raw JSON data and manage the rendering yourself.

import { setFroomleConfig, registerFroomleCallback } from "froomle-sdk";

// 1. Configure the engine
setFroomleConfig({
  env: "my_env",
  channel: "www",
  page_type: "home"
});

// 2. Subscribe to raw recommendation data
registerFroomleCallback("recommended_for_you", (recos) => {
  // recos is a raw JSON array: [{ item_id: '123', title: '...', ... }]
  renderMyCards(recos);
});

1. Installation

  • CDN Manual

  • NPM

  • Composer PHP

Ideal for standard websites. Add this to the <head> of your page.

<script src="https://cdn.jsdelivr.net/npm/@froomle/frontend-sdk@latest/dist/froomle.global.js"></script>

Ideal for modern bundling workflows (Webpack, Vite, etc.).

npm install froomle-sdk

For server-side attribute injection in PHP apps.

# For Modern PHP (7.4+)
composer require froomle/froomle-sdk

# For Legacy PHP (<= 5.6)
composer require froomle/froomle-sdk-legacy

2. Identity & Storage

The SDK automatically manages a first-party cookie to ensure consistent personalization across sessions.

Cookie Storage (_fr_id)

When the SDK loads, it checks for a cookie named _fr_id. * If it exists: The value is used as the device_id. * If it doesn’t: A new UUID is generated and stored for 365 days.

This identifier allows Froomle to "stitch" together user behavior even before they log in.

User Identification

You can provide more specific identifiers to link the session to an authenticated account. See the User Identity Guide for full details.

Parameter Description

device_id

Automatically set via _fr_id cookie. Can be overridden if you have your own device-level ID.

user_id

Permanent ID. Set this when a user logs in (e.g., account ID, email hash) to enable cross-device personalization.

Personalization must respect user privacy. The SDK supports three levels of consent, which should be updated based on your Consent Management Platform (CMP) settings.

Level Name Behavior

0

No Tracking

(Default) Returns popular items only. No impressions are tracked.

1

Analytics Only

Tracks impressions, but does not use history for personalization.

2

Full

Active personalization based on user history.
Applying consent
import { setFroomleConsent } from "froomle-sdk";

// Call this once the user accepts your cookie policy
setFroomleConsent(2);

Consent level is stored in localStorage. You only need to set it once per device change.

3. Environmental Context

Froomle requires context to anchor its recommendations. This ensures that a mobile user on the "Home" page doesn’t receive recommendations optimized for a desktop user on an "Article" page.

Refer to the Modules & Placements Guide for the recommended taxonomy of these values.

Setting Context via JS/TS
import { setFroomleConfig } from "froomle-sdk";

setFroomleConfig({
  channel: "www-desktop",
  page_type: "article_detail",
  context_item: "article_456", // Optional: the ID of the current item in view
  context_item_type: "article"  // Mandatory if context_item is provided
});
Setting Context via HTML Attributes
<script
  src="..."
  data-froomle-channel="www-desktop"
  data-froomle-page-type="article_detail"
  data-froomle-context-item="article_456"
  data-froomle-context-item-type="article">
</script>

4. Delivery Modes

The SDK offers two ways to handle recommendation results. You can mix and match these on a single page (e.g., use Automatic mode for a sidebar and Programmatic mode for a custom Hero section).

Mode A: Automatic (DOM-Based)

Automatic mode uses HTML data attributes to mark slots and map item properties to your UI. This is the fastest way to integrate.

1. Define the Slot

Add data-froomle-reco="list_name" to a container. The SDK will fetch the list and clone the child elements for each recommendation.

<div data-froomle-reco="recommended_for_you">
  <!-- This inner content acts as a template -->
  <div class="card">
    <img data-froomle-param-src="images[0]" />
    <h3 data-froomle-param-inner="title"></h3>
  </div>
</div>

2. Mapping Parameters

Use data-froomle-param-* to bind SDK-provided item data to your template.

Attribute Pattern Result

data-froomle-param-inner="<field>"

Sets the inner text (or HTML) of the element.

data-froomle-param-<attr>="<field>"

Sets the specific HTML attribute <attr> (e.g., src, href, data-id).

You can access nested fields or array elements using dot or bracket notation (e.g., images[0], metadata.price).

Mode B: Programmatic (JSON-Based)

Programmatic mode gives you the raw data, letting you use your own rendering engine (React, Vue, etc.) or custom JS logic.

1. Subscribe to Updates

Register a callback for a specific list. The callback is fired as soon as the data is available.

import { registerFroomleCallback } from "froomle-sdk";

registerFroomleCallback("recommended_for_you", (recos) => {
  // recos is an array of RecommendationItem objects
  recos.forEach(item => {
    console.log(`Found item: ${item.title}`);
  });
});

2. The Recommendation Object

A typical recommendation item contains the following core fields. Additional fields can be configured in the Froomle Dashboard.

{
  "item_id": "item_123",
  "title": "personalized news title",
  "images": ["https://cdn.com/thumb.jpg"],
  "uri": "https://yoursite.com/article_123",
  "item_type": "article"
}

3. Item IDs

It is strongly recommended to add item IDs to your own content elements (e.g., articles). These IDs improve recommendation quality and analytics. Use the data-froomle-id="<item_id>" attribute on your source elements.

5. Advanced: Ordered Sections

The SDK can reorder existing elements in your DOM based on the user’s preference for specific categories or attributes. This is useful for reordering "Topics" or "Store Sections."

  1. Mark the Container: Use data-froomle-order="<attribute>" (e.g., category).

  2. Mark the Children: Use data-froomle-order-value="<value>" on the items to be sorted.

<div data-froomle-order="category">
    <div data-froomle-order-value="Politics">Politics Section</div>
    <div data-froomle-order-value="Sports">Sports Section</div>
    <div data-froomle-order-value="Lifestyle">Lifestyle Section</div>
</div>

The SDK will fetch the top 50 recommendations and sort your sections by the frequency and score of the matching attribute.

6. Advanced JS Events

registerOrderCallback(fn: (element: Element, orderedChildren: Element[]) ⇒ void)

Fires after sections are reordered. Use this to apply visual transitions or tracking.

registerOrderCallback((element, orderedChildren) => {
  console.log("Sections reordered:", orderedChildren);
});

registerFroomleOrderMethod(name, fn)

Define custom logic for the data-froomle-order attribute.

7. Custom Domains

To prevent ad-blockers from interfering with your personalization, we recommend using a custom subdomain (e.g., froomle.yourdomain.com) mapped to the Froomle API via CNAME.

setFroomleRequestDomain("froomle.yourdomain.com");

8. Performance Optimization

Pre-rendering (PHP)

To avoid the "flash of un-personalized content," you can inject the necessary configuration script server-side using the PHP SDK. This ensures the browser starts and identifies the user as soon as the first byte is received.

<?php
use Froomle\FroomleSdk\Froomle;

// This generates the necessary <script> tags and identifies the user
Froomle::init("my_env", [
    "channel" => "www",
    "page_type" => "home"
]);

Related Topics