Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Last updated