Remote Navigator

Implementing Remote Navigator in Guideflow requires technical knowledge and may necessitate the involvement of a developer from your team.

Guideflows are modular, interactive guides that autonomously operate when embedded into your platform. Users typically progress through a Guideflow by engaging with interactive elements or "hotspots." However, suppose you wish to provide an alternate navigation method for your Guideflows, bypassing the need for direct interaction with these hotspots.

What is Remote Navigator?

Remote Navigator empowers users to control the Guideflow directly from your website. This feature removes the necessity for users to interact with hotspots to navigate through the Guideflow. With Remote Navigator, you can create a customized navigation interface for your Guideflows.

An example showcasing the functionality:

https://gssjx2.csb.app/

How does Remote Navigator function?

To facilitate the creation of a customizable navigation UI by your website, we opted not to integrate the navigation UI within the Guideflow itself. Our strategy involves transmitting information about the Guideflow to the host website, enabling the construction of a navigation interface.

A straightforward method to achieve this involves utilizing the “window.postMessage()” API, which is widely supported across major web browsers.

The window.postMessage() method allows for safe cross-origin communication between Window objects, such as between a page and its spawned pop-up or an embedded iframe.

The communication process involves two primary interactions:

• Guideflow to Host: transmits Guideflow metadata upon initialization and during navigation events within the Guideflow (e.g., transitioning between steps).

• Host to Guideflow: allows the host to send commands to the Guideflow to navigate to a specific step upon user interaction with the custom navigation interface.

At the start, the Guideflow sends a postMessage to the host containing:

window.parent.postMessage({
event: 'state-update',
guideflow: {
id: '123',
name: 'My Engaging Guideflow',
description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
steps: [{
id: '456',
name: 'Step 1 name',
description: '<reserved for future use>',
order: 1,
isActive: true
},
{
id: '789',
name: 'Step 2 name',
description: '<reserved for future use>',
order: 2,
isActive: false
}],
},
}, '*')

This message includes essential metadata about the Guideflow and its steps, enabling the host to create a customized navigation interface.

Should the Guideflow's state change (e.g., a user progresses through steps), an updated postMessage is sent, similar to the initial payload, with adjustments to the isActive status reflecting the current active step.

Host websites must establish a listener for these messages. Here's how to set up a listener:

// Add postMessage listener on the Host
function processIncomingMsg(evt) {
// Verify the event originates from Guideflow and is user-generated
if (evt.origin !== 'https://app.guideflow.com' || !evt.isTrusted) {
return;
}
if (evt.data.event === 'state-update') {
setGuideflow(evt.data.guideflow);
}
};

window.addEventListener('message', processIncomingMsg);

Ensure you validate the evt.origin to confirm the message's source as Guideflow and verify the event is user-generated (evt.isTrusted). Guideflow may send additional events in the future, so it's crucial to listen for the specific 'state-update' event.

To interact with the Guideflow through your custom UI, send a postMessage to the desired Guideflow. For instance, to navigate to a specific step, you can use:

// Navigate to a step in the Guideflow
const iframe = document.getElementById(guideflowId);
iframe?.contentWindow?.postMessage({
event: 'go-to-step',
stepId: <step id>, // The step ID to navigate to
}, ‘*’);

This directs your postMessage to the iframe containing the Guideflow, instructing it to navigate to the specified step. The Guideflow responds by navigating to the chosen step and sends a state-update postMessage back to the host.

To navigate to the next/previous step you can use:

const iframe = document.getElementById(guideflowId);

// Navigate to the next step
iframe?.contentWindow?.postMessage({
event: 'go-next'
}, ‘*’);

// Navigate to the previous step
iframe?.contentWindow?.postMessage({
event: 'go-prev'
}, ‘*’);

Example

An example showcasing the functionality:

https://gssjx2.csb.app/