Appcues + Turbolinks Implementation

With SDK version 4.53.0 and later Appcues now has a path forward for web applications running Turbolinks frameworks. This document will contain the steps needed in order to properly implement Appcues with this framework.

Adjusting Appcues script settings

Including the customContainer property in the window.AppcuesSettings object will allow you to specify where on your web application Appcues content will load. Subsequently, this allows you to establish a permanent container that Turbolinks will ignore so your Appcues experiences will not be interrupted.

<script>
  window.AppcuesSettings = {
    customContainer: '.appcues-wrapper'
  };
</script>
<script src="//fast.appcues.com/ACCOUNT_ID.js"></script>

Create Appcues permanent container

In your web application, you will need to create a permanent home for where your Appcues content container will live.  In our example, we use a div at the end of the application page body.

<div data-turbolinks-permanent>
  <div class='appcues-wrapper'></div>
</div>

Create an Appcues page callback

You will want to create a callback that's initialized after Appcues identification to trigger the Appcues.page call on every turbolinks load call if you're not looking at a cached "preview" of the page:

document.addEventListener("turbolinks:load", function (e) {
    if (!document.documentElement.hasAttribute("data-turbolinks-preview")) {
      window.Appcues.page();
    }
});

Using a newer Turbolinks library?

A similar implementation process applies to the latest version of Turbo, just replace "turbolinks" with "turbo" in the property and event names.

<div data-turbo-permanent>
  <div class='appcues-wrapper'></div>
</div>

document.addEventListener("turbo:load", function (e) {
    if (!document.documentElement.hasAttribute("data-turbo-preview")) {
      window.Appcues.page();
    }
});