Advanced Usage

This page covers advanced usage of the Remark SDK, providing developers with more sophisticated control over the chat widget and user experience.

Initialization

Safely wait for the SDK before calling window.remark.

Widget Control

Programmatically open, close, hide, and show the chat widget.

Event Handling

Listen to user interactions and create custom integrations.

Waiting for Remark to initialize

Because the Remark script loads asynchronously, window.remark may not be available when your code runs. Before calling window.remark, wait for the remark:session-initialized event on window:

window.addEventListener('remark:session-initialized', () => {
  // window.remark is now ready
  window.remark('open');
});

If your code might run before or after initialization, you can check whether window.remark is already available:

function whenRemarkReady(callback) {
  if (typeof window.remark === 'function') {
    callback();
  } else {
    window.addEventListener('remark:session-initialized', callback, { once: true });
  }
}

// Usage
whenRemarkReady(() => {
  window.remark('open');
});

Customizing your user experience with the Remark SDK

The Remark SDK can also be used to control the state of the chat widget. You may wish, for example, to temporarily close the chat widget when displaying full-screen promotions or open the chat widget when a customer clicks on a certain call-to-action on your site. You can open, close, hide, and show the chat widget using one of the options in the following code.

// To open the chat widget:
window.remark('open');
document.querySelector('remark-chat-widget').setAttribute('open', '');

// To close the chat widget:
window.remark('close');
document.querySelector('remark-chat-widget').removeAttribute('open');

// To entirely hide the chat widget:
window.remark('hide');
document.querySelector('remark-chat-widget').setAttribute('hidden', '');

// To show the chat widget again:
window.remark('show');
document.querySelector('remark-chat-widget').removeAttribute('hidden');

Remark saves the hidden state in the browser, so the widget stays hidden on later page loads until you call show. To close the chat panel for a moment, use close instead. In addition to simply opening the widget, you can pass options to prefill a message or send it right away.

window.remark('open', {
  message: 'Hi there! Can you help me find the right item?',
  mode: 'send'
});

Available options

message – Text for the chat input. On its own, it fills the input and leaves sending to the shopper.
mode – Set to 'send' to send message right away, starting a conversation (or reopening a closed one) if needed. The default, 'pre-fill', only fills the input.

Embedded and floating widget coordination: When both the floating chat (<remark-chat-widget>) and embedded chat (<remark-qa-activator>) appear on the same page, they coordinate automatically. Only one widget holds the active conversation at a time — the other shows a “paused” state with the matched expert’s avatar and a button to resume the conversation there.On mobile viewports (480 px and below), tapping a prompt in the embedded chat opens the floating widget full-screen instead of starting an inline conversation. The floating widget does not auto-reopen from persisted state across page navigations on mobile — it stays closed unless explicitly opened via remark_open=true or window.remark('open').

The widget uses English unless your workspace has more languages enabled. To add languages, contact support@remark.ai. With more than one language enabled, the widget follows the storefront’s language: Shopify’s active locale, then the page’s <html lang> attribute, then the browser language. To set the language yourself, pass a language code or tag:

window.remark('setLanguage', 'fr');   // or a tag such as 'fr-CA' or 'zh-TW'
window.remark('setLanguage', 'auto'); // follow the page and browser language

Remark saves your choice in the browser and uses it on later page loads until you set the language again.

URL Parameters

Remark recognizes several URL parameters for controlling widget behavior without writing code. These are useful for testing and sharing links that demonstrate a specific widget configuration.

Parameter	Effect
`remark_open=true`	Opens the floating chat widget on page load
`remark_force_widget=true`	Moves the visitor into the A/B test’s treatment group on this browser and shows Remark, even on pages your rules exclude or while chat is unavailable
`remark_preview_inline_elements=true`	Shows the embedded chat even when it is disabled in the dashboard
`remark_preview_floating_widget=true`	Shows the floating chat widget even when Inline activator only is turned on in the dashboard
`remark_reset_chat=true`	Clears Remark’s saved conversation, visitor ID, A/B assignment, and widget preferences in this browser, so the page loads as a new visitor

Append them as query parameters to any page URL:

https://www.example.com/products/hiking-boots?remark_force_widget=true

The preview parameters only override the dashboard setting. For a visitor in the A/B control group, or on a page your rules exclude, add remark_force_widget=true as well. remark_force_widget, remark_preview_inline_elements, and remark_preview_floating_widget are also written to sessionStorage when set via URL, so the override persists across page navigations within the same tab. You can also set them directly in sessionStorage, which helps in browsers or environments that strip query parameters:

sessionStorage.setItem('remark_force_widget', 'true');
sessionStorage.setItem('remark_preview_inline_elements', 'true');
sessionStorage.setItem('remark_preview_floating_widget', 'true');

To clear an override, close the tab or remove the key from sessionStorage in DevTools. remark_reset_chat applies once, on the page load that carries it, and Remark doesn’t save it.

Listening for Remark Events

Remark fires remark:-prefixed DOM events from the floating widget, the embedded chat, and the page itself. Listen on window to receive all of them:

window.addEventListener("remark:mute-chat", (event) => {
  console.log("Muted:", event.detail.newValue);
});

Listen to all Remark Events

To listen to all the events, you can use the window.remark.events.listenAll function. It takes a callback, called with every remark event. The payload received by the callback is an object:

with an event__type key, one of the remark events listed below
any other details payload the event has with it

listenAll returns an object with an unsubscribe function. Calling that unsubscribe function will stop the callback from being called again.

// typescript function declaration of listenAll
declare function listenAll(cb: (payload: {event__type: string} & {[key: string]: any}) => void) => {unsubscribe(): void};

// example calling listenAll
const listener = window.remark.events.listenAll(
  ({event__type, ...detail}) => {
    console.log(`The event fired is ${event__type} with this information ${detail}`)
  }
);

// unsubscribing the listener
listener.unsubscribe();

List of Remark Events

Event	Description
`remark:session-initialized`	Our client session has initialized, with basic information for the widget
`remark:open-widget`	Remark chat widget has opened
`remark:close-chat-from-header`	Customer has closed the chat window via the chat header button
`remark:mute-chat`	Fires when chat mutes or unmutes
`remark:dismiss-floating-prompts`	Customer has closed the floating prompts on the activator
`remark:dismiss-unread-message`	Customer has dismissed the unread message on the activator
`remark:finding-expert`	Customer is waiting to be paired with an expert
`remark:send-message`	Customer has sent a message
`remark:select-landing-prompt`	Customer has selected a suggested question on the floating landing screen
`remark:select-floating-activator-prompt`	Customer has selected a suggested question from the floating activator
`remark:select-embedded-prompt`	Customer has selected a suggested question from the embedded widget
`remark:select-conversation-starter`	Customer has selected a conversation starter in chat
`remark:follow-up-suggestions-shown`	Customer has been shown follow-up suggestions after an AI answer
`remark:select-follow-up-suggestion`	Customer has selected a follow-up suggestion after an AI answer
`remark:select-live-try-on`	Customer has opened live try on from the try-on entry beside the suggested questions
`remark:click-recommended-product`	Customer has clicked a recommended product
`remark:add-recommended-product-to-cart`	Customer has added a recommended product to cart
`remark:click-showcase-product`	Customer has clicked a product link in a presented showcase hover card
`remark:add-showcase-product-to-cart`	Customer has added a product from a presented showcase to cart
`remark:add-live-try-on-product-to-cart`	Customer has added the product they tried on to cart from the live try on wrap-up
`remark:agent-add-item-to-cart`	Agent has added item(s) to cart
`remark:adjust-cart-item-quantity`	Customer has adjusted cart item quantity in the cart dialog
`remark:click-checkout-button`	Customer has clicked checkout from the cart dialog
`remark:apply-discount`	Customer has applied a discount code from a discount card
`remark:change-widget-size`	Customer has changed the widget size
`remark:change-widget-position`	Customer has changed the widget position
`remark:change-activator-type`	Customer has changed the activator type
`remark:view-expert-profile`	Customer is viewing the expert profile
`remark:close-expert-profile`	Customer has closed the expert profile
`remark:view-expert-gallery`	Customer is viewing the expert’s gallery
`remark:submit-pii`	Customer has submitted requested PII
`remark:decline-pii-request`	Customer has declined a requested PII form
`remark:open-nps`	Customer has opened the NPS survey
`remark:submit-nps`	Customer has submitted a Customer Feedback Survey
`remark:edit-nps`	Customer has edited a Customer Feedback Survey
`remark:cancel-nps`	Customer has canceled editing a Customer Feedback Survey
`remark:sdk-initialized`	Deprecated; use `remark:session-initialized` instead

Getting Started

Guides

Dashboard

API

Integrations

Initialization

Widget Control

Event Handling

Waiting for Remark to initialize

Customizing your user experience with the Remark SDK

Opening the widget with options

Available options

Setting the widget language

URL Parameters

Listening for Remark Events

Listen to all Remark Events

List of Remark Events

Initialization

Widget Control

Event Handling

​Waiting for Remark to initialize

​Customizing your user experience with the Remark SDK

​Opening the widget with options

​Available options

​Setting the widget language

​URL Parameters

​Listening for Remark Events

​Listen to all Remark Events

​List of Remark Events

Waiting for Remark to initialize

Customizing your user experience with the Remark SDK

Opening the widget with options

Available options

Setting the widget language

URL Parameters

Listening for Remark Events

Listen to all Remark Events

List of Remark Events