Browser JavaScript commands and events

Use the browser API to identify a visitor, control widgets, or respond to RightMessage activity on the current page. Commands use tuples passed to window.RM.push. Events use document.addEventListener. Neither interface is the local RM object available inside a flow Code node.

The API requires the RightMessage installation snippet. These commands act on the current visitor. They do not create or publish project configuration. Publish changes to flows, widgets, or segments before normal visitors use them. Commands that identify a visitor or alter answers can affect personalization and connected-provider activity immediately.

Queue and return contract

Illustrative queue setup, not executed:

window.RM = window.RM || [];
window.RM.push(['trigger', 'wdg_workforge_demo']);

Before initialization, RM is an array. push() returns its new length, not a Promise or a command result. When RightMessage initializes, it processes queued tuples and replaces push with a command dispatcher. Calls then execute immediately. Multiple tuples execute in order, and push returns the last command's return value.

There is no Promise that represents a previously queued call. lookup and identifyByEmail support callbacks for results across this boundary. A callback is a success-path callback, not an error-first callback. Use a returned Promise only when your code already knows that the dispatcher is initialized.

Unknown command names have no defined error behavior, and there is no general argument validation. Pass the exact command spelling and IDs from the current project.

Identification commands

lookup

Without an integration, the command warns and rejects with 'No integration configured'. With an integration but no email, it returns undefined. Other lookup failures follow the provider Promise. The optional callback runs only when that Promise resolves.

A lookup is not contact creation, opt-in, or identification. Its miss result depends on the provider lookup. Use identifyByEmail when the goal is to adopt an existing contact.

identify

A nonempty ID becomes the current subscriber identifier before a forced profile read. With no ID argument, the runtime refreshes the current identity rather than clearing it. Without an integration, it warns and returns undefined.

The returned Promise settles through the refresh path even when the profile read fails. Resolution is not proof that a valid profile was found. Provider identification events can describe anonymous or failed states too.

identifyByEmail

Missing email rejects with 'Email address required'. Missing integration rejects with 'No integration configured'. Lookup errors warn and become null. A lookup miss does not replace the existing identity. A newer lookup supersedes an older one, so an old response cannot restore a previous visitor identity.

The command waits for the adopted identity's profile fetch attempt. A contact ID result does not guarantee that every profile field loaded successfully. A callback exception can reject the returned Promise.

Illustrative queued call, not executed:

window.RM = window.RM || [];
window.RM.push([
	'identifyByEmail',
	'visitor@example.com',
	(contactId) => {
		console.log(contactId === null ? 'No contact adopted' : 'Contact adopted');
	}
]);

An illustrative callback value is 'contact_workforge_42' when lookup and identity adoption succeed, or null when they do not. Identification is not authentication. Never use this result to grant account access.

prepopulate

This forces a refresh of the connected profile and joins compatible in-flight work. Without an integration, it logs a message and returns undefined. As with identify, Promise resolution is not a provider-success receipt.

Widget and rendering commands

Widget IDs are strings such as wdg_workforge_demo. Triggering does not return proof of visibility. personalize does not republish configuration, reroll unchanged holdbacks, or repeat an unchanged campaign exposure.

Normal SPA routes are observed automatically. A second route hook that calls reset is unnecessary. See Use RightMessage in a single-page application.

Answers and browser data

A removed answer can still match a segment through its signal rules or connected profile. These commands do not delete segment definitions. Unlike Code-node segment methods, the browser tuples emit refresh events for external callers.

clearAllData preserves debugger preferences. It does not delete the email-platform contact, undo completed provider writes, or delete historical server-side analytics. Storage removal is best effort.

Illustrative result shape, not executed:

{
	"localStorageKeys": ["rm_variables", "rmpanda.rightask.answers"],
	"sessionStorageKeys": ["rm_dismissed_widgets"],
	"removedVisitorContextCookie": true
}

The arrays list matching keys selected for removal. The cookie boolean indicates that the host was eligible for the context-cookie removal attempt. Neither is proof that the browser accepted every removal.

DOM CustomEvents

Listeners belong on document. Payloads are in event.detail. These events report runtime activity, not a transactional provider receipt or a promise of delivery to your listener. Register listeners before the activity you need to observe.

The first five events have bubbles: true and cancelable: true. The widget events above are dispatched directly on document with the default non-bubbling, non-cancelable flags. No listed event provides a supported preventDefault() veto over conversions, navigation, or provider writes.

In debugger sessions, RightMessage can record these events as proposed writes rather than dispatching them to your listeners.

Illustrative listener and event detail, not executed:

document.addEventListener('rm:widget:answer', (event) => {
	const { dimensionId, segmentId } = event.detail;
	console.log({ dimensionId, segmentId });
});

{
	"widgetId": "wdg_workforge_quiz",
	"widgetName": "WorkForge quiz",
	"dimensionId": "dim_workforge_role",
	"dimensionName": "Role",
	"segmentId": "seg_workforge_manager",
	"segmentName": "Manager"
}

Avoid forwarding entire event payloads to third-party analytics. Identification and form events can contain email addresses and other personal data.

Exclude a form from automatic observation

The presence of data-rm-form-ignore on a form opts it out of RightMessage's automatic form observer. The value is not interpreted as a boolean, so data-rm-form-ignore="false" still opts out.

The form observer is created for a Popup widget using After a form is submitted. Installing the snippet alone does not enable this observer for every site form. The opt-out applies to that observer, not every identification path. See Identify visitors automatically for Email Watcher and other supported methods.

Illustrative markup, not executed:

<form action="https://example.com/search" data-rm-form-ignore>
	<input name="query" type="search">
	<button type="submit">Search WorkForge</button>
</form>

This exclusion does not prevent your own JavaScript from calling identification commands. Runtime-owned attributes such as data-rm-form-id and data-rm-question-input are not substitutes for the opt-out attribute.

Related implementation guides

• Use RightMessage in a single-page application for client-side route changes.
• Carry visitor context across domains for link and redirect handoffs between websites.
• Code node JavaScript API for methods available inside a flow rather than the browser command queue.