Chat Widget Setup

Use the Applied chat widget to add AI support to your website.

1. Add the widget script

<script src="https://cdn.applied.guide/artifacts/applied-chat.umd.js"></script>
<applied-chat agent-id="YOUR_AGENT_ID" />

Place the script once per page. The applied-chat element can appear wherever you want the widget to live.

2. Configuration options

If you want a full-page experience, set size="full" and wrap it in a container that fills the page.

Metadata structure

The metadata attribute is a JSON object. Contact attributes (name, email, and any custom fields you want the agent to see about the user) must be nested inside a context object — they are not read if placed at the top level of metadata.

{
  "context": {
    "name": "Alex",
    "email": "alex@example.com",
    "accountTier": "pro"
  },
  "groups": ["vip"]
}

groups (array of contact group names) is the other supported top-level field.

3. JavaScript API

Once the widget loads, you can control it with window.applied:

window.applied.show();
window.applied.hide();
window.applied.setOpen(true);

These controls are useful if you want to open the widget after a user action.

Metadata helpers

window.applied.getMetadata();
window.applied.setMetadata({
  context: { name: 'Alex', email: 'alex@example.com' },
});

Metadata merges with any existing values, so you can update only what changed.

Message callback

window.applied.setOnMessage(message => {
  console.log(message.type, message);
});

Use this callback to capture events or sync analytics in your own system.

Theme control

window.applied.setTheme('dark');

4. Event system

You can subscribe to widget events:

const subId = window.applied.events.subscribeEvent('applied:', payload => {
  console.log(payload.event, payload.data);
});
 
window.applied.events.unsubscribeEvent(subId);

The subscribeEvent method works with prefixes, so applied: will capture all widget events.

Built-in events

• applied:chat:open
• applied:chat:close
• applied:conversation:message
• applied:conversation:update

Tracking semantic interactions (recommended)

The chat widget can record semantic, GA4-style interaction events (like add_to_cart, begin_checkout, and select_item) so Applied can tailor proactive prompts and recommendations to the user’s current session.

Important:

• Only a supported allowlist of event names is stored; unsupported names are ignored.
• Only supported semantic property keys are stored; unsupported keys are dropped.

Supported event names:

• view_item
• view_item_list
• select_item
• add_to_cart
• view_cart
• begin_checkout
• generate_lead
• sign_up
• search
• ui_modal_open
• ui_tab_open
• ui_accordion_open

Supported semantic property keys:

• item_id
• item_name
• item_variant
• item_brand
• item_category
• price
• currency
• quantity
• value
• variant_key
• variant_value
• ui_label
• ui_kind
• ui_target
• search_term

There are three ways to instrument these events:

A) Data attributes (no-JS, works anywhere)

Add data-applied-event to any clickable element (or a parent wrapper) and optionally add data-applied-event-props for structured metadata.

<button
  data-applied-event="add_to_cart"
  data-applied-event-props='{"item_id":"sku_123","quantity":1}'>
  Add to cart
</button>

You can also track non-ecommerce UI intent events (custom GA4 events), for example a size chart modal:

<a
  href="#size-chart"
  data-applied-event="ui_modal_open"
  data-applied-event-props='{"ui_label":"size guide"}'>
  Size chart
</a>

B) JavaScript API (best for SPAs + variant selection)

Call window.applied.trackInteraction(...) to record a semantic event.

Variant selection is captured as key/value pairs:

window.applied.trackInteraction('select_item', {
  item_id: 'sku_123',
  variant_key: 'size',
  variant_value: 'M',
});

Advanced form (optional source/entity metadata):

window.applied.trackInteraction(
  {
    name: 'view_item',
    source: 'manual',
    entityType: 'product',
    entityId: 'sku_123',
    entityLabel: 'Starter Bundle',
  },
  { item_id: 'sku_123', item_name: 'Starter Bundle' },
);

C) GA4 / GTM dataLayer events (automatic if you already use GA4)

If you already push GA4 events to window.dataLayer, the widget can pick them up automatically.

Important: ensure window.dataLayer exists before the widget initializes:

<script>
  window.dataLayer = window.dataLayer || [];
</script>
<script src="https://cdn.applied.guide/artifacts/applied-chat.umd.js"></script>
<applied-chat agent-id="YOUR_AGENT_ID" />

Notes:

• The widget listens to future window.dataLayer.push(...) calls (it does not backfill old entries already in the array).
• For product metadata, it reads from ecommerce.items[0].

Then pushes like this will be captured:

window.dataLayer.push({
  event: 'begin_checkout',
  ecommerce: { items: [{ item_id: 'sku_123', item_name: 'Starter Bundle' }] },
});

Enabling heuristic (inferred) events (optional)

By default, the widget only records semantic events you explicitly emit (A/B/C above). If you want the widget to also infer some events via conservative DOM and network heuristics (for example: variant change detection, cart/add and checkout navigation), enable heuristics on the agent:

What heuristics currently infer:

• add_to_cart from successful requests to /cart/add, /cart/add.js, or ?wc-ajax=add_to_cart.
• begin_checkout from successful requests to /checkout.
• select_item from likely variant change events (for example Shopify option selectors in add-to-cart forms).
• UI intent events from click text/labels for size guide, shipping/returns, reviews, compare, and wishlist.

Enable it on the agent as:

• agent.metadata.instrumentation.enableHeuristicEvents = true

Heuristics are opt-in because they can produce false positives on some sites.

Debugging

To verify events are being recorded, listen for the browser event:

window.addEventListener('applied:interaction', e => {
  console.log('interaction', e.detail);
});

Or inspect local storage (events are buffered client-side):

Object.keys(localStorage)
  .filter(key => key.startsWith('al_user_interaction_events:'))
  .forEach(key => console.log(key, JSON.parse(localStorage.getItem(key) || '[]')));

Need help?

Contact support@appliedlabs.ai if you need help with installation.

For widget theming and advanced brand customization, see Chatbot Styling.