> For the complete documentation index, see [llms.txt](https://docs.neonblue.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neonblue.ai/data/on-site-personalization-and-js-integration.md).

# On-Site Personalization & JS Integration

#### 1. Purpose of this page

This page describes how to integrate Neon Blue with on-site surfaces using JavaScript, including:

* How Neon Blue participates in on-site experiences
* How gates and holdouts work for web traffic
* How to handle content blocking and custom domains

The examples assume a typical setup where a JavaScript bundle controls a banner or hero surface.

***

#### 2. On-site architecture overview

At a high level, an on-site integration has three layers:

1. **Local rendering logic**
   * The site’s own JavaScript or front-end framework (React, Vue, etc.) that renders a banner or module.
2. **Gate call**
   * A Neon Blue API call that determines whether:
     * The user should see the baseline experience, or
     * The user is eligible for Neon Blue optimization on this surface.
3. **Variant call**
   * For eligible users, a Neon Blue API call that:
     * Assigns the user to a variant in a contextual bandit
     * Returns the data necessary to render that variant (for example, image URLs, text content)

The same holdout and gating structure described in the previous page applies to on-site surfaces.

***

#### 3. Control vs Neon Blue on-site

On-site experiences typically have two layers of control:

1. **Baseline site control**
   * The site can always choose to render its own baseline banner or content when:
     * The global or flow gate indicates “do not pass,” or
     * Neon Blue is temporarily unreachable.
2. **Bandit control variant**
   * For users who do pass the gate, Neon Blue treats the original site banner as one of the variants in the contextual bandit.
   * This allows direct comparison between new variants and the existing design before shifting more traffic to new variants.

This dual structure ensures that:

* The site retains full control over the baseline experience.
* Neon Blue can safely experiment and optimize within its own environment.

***

#### 4. Integration pattern

A typical client-side integration for a banner follows this sequence:

1. **Identify the user**
   * Resolve the canonical `user_id` in the browser, or a device identifier that can be mapped to `user_id` on the backend.
2. **Call the gate API**
   * Request: pass relevant context (user identifier, page type, etc.).
   * Response: a boolean-like “pass / don’t pass” for the specific gate controlling this surface (for example, `homepage_banner_gate`).
3. **Decide which experience to render**
   * If the gate response is “do not pass”:
     * Render the baseline banner or fallback content.
   * If the gate response is “pass”:
     * Call the experiment/variant API.
4. **Call the experiment/variant API**
   * Request: includes `user_id`, experiment name or ID, and context (device, page type, etc.).
   * Response: includes:
     * Variant identifier
     * Content payload (for example, URLs for images generated from Figma templates, copy variations)
5. **Render variant and log events**
   * Render the returned variant in the banner slot.
   * Log impressions and relevant events (clicks, etc.) back into the existing event pipeline, so they appear in the `events` table for measurement.

***

#### 5. Handling client-side vs server-side rendering

On-site integrations can be:

* **Client-side rendered**
  * The JavaScript bundle runs in the browser and calls the Neon Blue APIs directly.
  * This is the most common pattern for banners and hero modules. 
* **Server-side rendered (SSR)**
  * The backend calls Neon Blue before rendering the HTML.
  * Useful for performance-sensitive surfaces or where blocking calls in the browser are undesirable.

Both patterns follow the same conceptual steps: gate → variant → render.

***

#### 6. Content blockers and custom domains

Modern browsers and ad-blockers can aggressively block third-party scripts and calls. To improve reliability:

* Use a **custom subdomain** on the brand’s domain (for example, `assets.brand.com` or a randomized subdomain) that CNAMEs to Neon Blue. 
* Configure SSL termination so that traffic to this subdomain is encrypted end-to-end. 

This pattern:

* Makes Neon Blue’s endpoints appear as first-party resources to the browser.
* Reduces the chance that privacy tools incorrectly flag requests as third-party tracking.

Neon Blue provides domain and SSL configuration guidance during implementation.

***

#### 7. Banner specs and assets

For visual surfaces such as banners:

* Define required **dimensions** (width and height) and any responsive behavior (for example, separate mobile vs desktop layouts). 
* Provide base designs as Figma templates or equivalent, with clearly annotated dynamic regions.
* Ensure the front-end can handle:
  * Swapping image URLs
  * Replacing text blocks
  * Adjusting layout safely when content length changes within expected bounds

Neon Blue uses these specs to generate compatible variants and to guarantee that returned payloads fit the available space.

***

#### 8. Failure modes and fallbacks

A robust integration should define behaviors for:

* **API timeouts or errors**
  * Render the baseline banner if the gate or variant calls fail.
* **Missing or mismatched assets**
  * Use a generic fallback banner or hide the module.
* **Tracking failures**
  * Ensure that the baseline experience remains functional even if event logging is temporarily unavailable.

The goal is that the site remains fully operational regardless of Neon Blue’s availability.