Web SDK: Render from the Auxia Console

Add the SDK to your site once. Where treatments appear, and what they look like, is then managed in the Auxia Console, with no further code changes on your site. If a surface needs fine-grained control from your page code, you can instead fetch and render its treatments yourself. See Render from Your Own Code. Both approaches use the same script and can run side by side, one per surface, in the same project.

	Render from the Auxia Console	Render from Your Own Code
Placement	Picked in the Auxia Console	Container elements in your page
Rendering	Auxia renders into the page	`fetchAndRenderTreatments()`, or your own UI from `getTreatments()`
Your code	`Auxia.initialize()` only	`initialize()` + a call per surface
Changing a surface	Console change, no deploy	Front-end deploy

The rest of this page covers Console-managed rendering.

Prerequisites

API key and Project ID from the Auxia Console.
Project Website URL set in your project settings in the Auxia Console. The Console uses it to open your site for picking placements and previewing treatments.

1. Install

Add the SDK script to every page where treatments may appear:

<script src="https://auxia.net/interactions/v1/interactions.js"></script>

2. Initialize

<script>
  Auxia.initialize({
    apiKey: "YOUR_API_KEY",
    projectId: "YOUR_PROJECT_ID",
    userId: "user-123"
  });
</script>

This is the only code your site needs. The SDK renders treatments on the surfaces you configure in the Auxia Console.

Parameter	Type	Required	Notes
`apiKey`	string	Yes
`projectId`	string	Yes
`userId`	string	Yes	Console-managed surfaces do not render without it. See below.
`contextualAttributes`	object	No	Contextual attributes known at page load. See Contextual attributes from your page.

userId must be present at initialize()Console-managed rendering starts during initialize() and does nothing when userId is empty. Calling updateUserId() afterwards does not start it. On a page where the user is known only after login, call Auxia.initialize() after you have the ID.

3. Enable Console-managed rendering for your project

Ask your Auxia contact to enable Console-managed rendering for your project. Once enabled, the Surfaces list under Configuration > UI Layout in the Auxia Console shows an SDK status column, which shows the surfaces it serves.

4. Set up surfaces and treatments

In the Auxia Console:

Create a surface and pick where it appears by selecting an element on your live site.
Choose the pages it applies to and how it is inserted relative to that element.
Choose a Layout for the surface.
Set up treatments, and preview them on your site before publishing.

Page paths

Page paths are matched against the whole path. /jobs/ matches only that exact page; use /jobs/** to also cover /jobs/index.html and everything below it.

Injection positions

Position	Effect
`APPEND`	Insert as the anchor’s last child.
`PREPEND`	Insert as the anchor’s first child.
`BEFORE` / `AFTER`	Insert as a sibling.
`REPLACE`	Clear the anchor’s children and insert inside it.

REPLACE keeps the anchor elementREPLACE empties the anchor and renders inside it; it does not remove the anchor. If your site’s code later rewrites that element’s content, it will silently overwrite the treatment. Pick an element your site does not re-render.

Using Google Tag Manager

For the best performance, we recommend you add the SDK directly to your site’s codeThrough GTM, the SDK starts loading only after the GTM container has loaded and the tag’s trigger has fired, so treatments appear later than with the direct install in steps 1 and 2. Use GTM when editing your site’s code is not an option.

You can add the SDK through a Custom HTML tag instead of editing your site’s code. Create a Custom HTML tag that loads the SDK script and calls Auxia.initialize() once the script has loaded, pass the user ID in from a GTM variable (for example, a Data Layer Variable), and set the tag to fire on every page where treatments may appear, only after the user ID is available.

<script>
  (function () {
    var s = document.createElement("script");
    s.src = "https://auxia.net/interactions/v1/interactions.js";
    s.onload = function () {
      Auxia.initialize({
        apiKey: "YOUR_API_KEY",
        projectId: "YOUR_PROJECT_ID",
        userId: "{{Auxia User ID}}"
      });
    };
    document.head.appendChild(s);
  })();
</script>

How the SDK behaves on your site

It loads your surface configuration from Auxia and caches it in the browser.
On each page, it renders treatments only on the surfaces whose page paths match, waiting for elements that load late.
Views, clicks and dismissals are recorded automatically. See Interaction tracking.
Single-page app navigation is handled: surfaces are removed and re-rendered as the path changes.
Failures are contained. If anything goes wrong, the page is left untouched, no error is thrown into your code, and first paint is never blocked.

Interaction tracking

A view is recorded automatically once at least half of the treatment has been visible for one second. Clicks and dismissals are recorded only on elements in the Layout or Design template that carry data-aux-button-name:

Attribute	Value
`data-aux-button-name`	A name for the button, recorded with the interaction.
`data-aux-button-interaction`	`CLICKED` (default) or `DISMISSED`. `DISMISSED` also hides the treatment.

<button data-aux-button-name="cta" data-aux-button-interaction="CLICKED">Learn more</button>
<button data-aux-button-name="close" data-aux-button-interaction="DISMISSED">Close</button>

Clicks on elements without data-aux-button-name are not recorded.

Contextual attributes from your page

Pass context only your page knows, such as a membership tier or a cart value, as contextual attributes, and Auxia uses it to choose and personalize treatments on your Console-managed surfaces.

Send the attribute keys agreed with your Auxia representative. A key that hasn’t been set up for your project is ignored, so check with them before adding a new one.

<script>
  const auxia = Auxia.initialize({
    apiKey: "YOUR_API_KEY",
    projectId: "YOUR_PROJECT_ID",
    userId: "user-123",
    contextualAttributes: { membership_tier: "gold" }
  });

  // Page-scoped: cleared when the URL path changes.
  loadCart().then((cart) => {
    auxia.setContextualAttributes({ cart_value: cart.total }, { scope: "page" });
  });

  // null removes a key.
  function onMembershipCancelled() {
    auxia.setContextualAttributes({ membership_tier: null });
  }
</script>

Pass values known at page load to initialize({ contextualAttributes }), so the first request carries them.
setContextualAttributes(attributes, { scope }) merges into what is already set, and null removes a key. It sends no request by itself: values go out with the SDK’s next request, or immediately for a placement set to refresh on that attribute.
Values can be a string, number, boolean or Date.
scope only matters in a single-page app. Every value is cleared when the page reloads (the SDK starts fresh); with "page", it is also cleared when the URL path changes, while "session" (default) keeps it across route changes.
It throws on an empty or reserved key (any auxia_* key, user_id, surfaces and a few others), an unsupported value type or an unknown scope. NaN, Infinity and invalid Dates are skipped with a console error.

Refresh a placement when an attribute changes

By default, a placement fetches once per page view, so a value set later is used from the next request on. To have a placement fetch again when a specific attribute changes, turn it on for that placement in the Auxia Console (Placement step → Advanced · Refresh on context change), add the attribute, and choose what happens when it changes:

Fill if empty (default): fetch again only while the placement is showing nothing. Content already on the page stays.
Replace content: fetch again every time the value changes and show the new result. If nothing comes back, the current content stays.

Styling

Surfaces render inside a Shadow DOM, so your page stylesheet does not reach them. Reusing your own class names styles nothing. CSS custom properties do cross the boundary, so tokens defined on the page are readable from inside the surface:

/* Inside the Layout template, in the Console */
.cta { background: var(--brand-primary, #0b5fff); }

Backgrounds, section padding and container width usually live on page elements outside the surface, which the SDK leaves alone. Do not re-implement them inside the template. Please reach out to your Auxia contact for further styling support.

Moving a surface from your own code to the Console

A surface you already render from your own code keeps working as it is. To hand it over to the Console:

Remove its fetchAndRenderTreatments() or getTreatments() call. Calls for your other surfaces keep working.
Its container element and surfaceHtmlElementId are replaced by a placement picked in the Console.
data-aux-* interaction attributes move from your page markup into the Layout and Design templates in the Console.
Contextual attributes are set once with setContextualAttributes() instead of on each call.

Troubleshooting

If a surface does not render, check that:

The SDK status column appears in the Console. If it does not, Console-managed rendering is not yet enabled for your project.
Auxia.initialize() is called with a non-empty userId.
The surface’s page paths match the page you are on.
The element the surface is placed on exists on the page.
The surface has a published Layout and at least one live treatment.

If it still does not render, send your Auxia contact the page URL and the surface name.

​Prerequisites

​1. Install

​2. Initialize

​3. Enable Console-managed rendering for your project

​4. Set up surfaces and treatments

​Page paths

​Injection positions

​Using Google Tag Manager

​How the SDK behaves on your site

​Interaction tracking

​Contextual attributes from your page

​Refresh a placement when an attribute changes

​Styling

​Moving a surface from your own code to the Console

​Troubleshooting

Prerequisites

1. Install

2. Initialize

3. Enable Console-managed rendering for your project

4. Set up surfaces and treatments

Page paths

Injection positions

Using Google Tag Manager

How the SDK behaves on your site

Interaction tracking

Contextual attributes from your page

Refresh a placement when an attribute changes

Styling

Moving a surface from your own code to the Console

Troubleshooting