Cross-Frame Events

Tourial Event Propagation

Overview

Tourial Event Propagation allows embedded demos to send events (eg: CTA clicks) to hosting websites or wherever else they are embedded.

For example, you could set up event propagation so when visitors click on a CTA, a message is sent that can trigger all kinds of creative ideas such as:

• Launch a chat window

• Display instant schedulers like Calendly

• Send data to your analytics stack like Google Analytics

• Trigger Webhooks

Implementation

Do I need a developer to help implement this?

Implementing Tourial Event Propagation will take a little bit of code (to add Event Listeners) so you'll need someone who can help with that.

How does it work?

When a Tourial is embedded on a webpage, user interactions within the tour will trigger events that will be sent through window.postMessage().

You will subscribe to the above events like below in your webpage so it can be processed

// Including the <script> wrapper will depend on the website builder you're using (some add them automatically)
<script>
  window.addEventListener("message", e => {
    if (e.data.type === "TOURIAL_EVENT") {
      // Do something with the event here.
      console.log("tourial event", e.data?.payload);
    }
  });
</script>

What events are propagated?

Below are the different types of demo events sent from Tourial.

SESSION_START: When Tourial starts after the first visitor interaction

{
  eventType: "SESSION_START";
  tourId: 'your-tourial-id';
  activeVariantName: "variantDesktop" || "variantMobile"; 
  stepId: "abc_xyz"; 
}

TOURIAL_VIEW: Whenever a step is displayed. Note: This will be the first event. (The SESSION_START event is not triggered until the first visitor interaction.)

{
  eventType: "TOURIAL_VIEW";
  tourId: 'your-tourial-id';
  activeVariantName: "variantDesktop" || "variantMobile"; 
  stepId: "abc_xyz"; 
}

CLICK: when a visitor clicks on something

{
  eventType: "CLICK";
  tourId: "your-tourial-id";
  activeVariantName: "variantDesktop";
  stepId: "abc_xyz";
  interaction: {
    toolId: "id_of_clicked_tool";
    dispatchEvent: "DISPLAY_TOOL" || "HIDE_TOOL" || "TOGGLE_TOOL" || "EXTERNAL_LINK" || "SUBMIT_FORM" || "TRIGGER_FORM" || "NEXT_PAGE" || "NEXT_ZOOM" || "CHANGE_PAGE" || "CHANGE_ZOOM" || "PREVIOUS_ZOOM" || "PREVIOUS_PAGE";
    href?: "EXTERNAL_LINK href";
    formId?: "TRIGGER_FORM id of the form that was opened";
  }
};

FORM_SUBMIT: when a visitor submits a form

{  
eventType: "FORM_SUBMIT";
  tourId: "644293103c3573a4d2cf0cda";
  stepId: "5667a5e5-048c-4cc5-9e06-c094cc6a5335_MAIN";
  activeVariantName: "variantDesktop";
  interaction: {
      toolId: "6442daa85f3a19d55faea4fb";
      triggeredByAction: "FORM_SUBMIT";
      dispatchEvent: "SUBMIT_FORM";
      formId: "6442daa85f3a19d55faea4fb"
  }
};

Example: Google Tag Manager

1. In your Google Analytics Tag Manager account, create a new custom HTML tag.

2. Copy and paste the following code into the "HTML" section of the tag:

<script>
  // This might already exist on page - typical GTM boilerplate
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments)};
  gtag('js', new Date());
  
  // Listen to TOURIAL_EVENT
  // we can push the Tourial events to Google Analytics events
  window.addEventListener('message', function(event) {
if (event.data.type === 'TOURIAL_EVENT') { 
  gtag('event', event.data.payload.eventType, event.data.payload);
  }
  });
</script>

This code sets up the Google Analytics tracking script, listens for Tourial postMessage events, and pushes the event data to Google Analytics as a custom event.

3. Save the custom HTML tag.

4. Create a new trigger in your Google Tag Manager account.

5. Set the trigger's type to "Custom Event".

6. In the "Event Name" field of the trigger, enter the event type you want to trigger. It will be one of the following:

   1. SESSION_START

   2. TOURIAL_VIEW

   3. CLICK

   4. FORM_SUBMIT

7. Save the trigger.

8. Create a new tag in your Google Tag Manager account.

9. Set the tag's "Tag Type" to "GA4".

10. Configure the tag with your Google Analytics tracking ID and any other relevant settings.

11. In the "Triggering" section of the tag, select the "Custom Event" trigger that you created earlier.

12. Save the tag.

13. Publish your changes to your Google Tag Manager account.

Now, whenever a Tourial postMessage event is sent from your iFrame, the custom HTML tag will capture the event data and push it to Google Analytics as a custom event. The "Custom Event" trigger will fire whenever any "TOURIAL_EVENT" is detected, passing along the “Event Name”, and allowing you to track Tourial events in Google Analytics.