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.

Please note that while this implementation method allows most Appcues experiences to work in applications utilizing Turbolinks, it currently does not provide support for Banners or Pins using the overlaid embed options. Pins set to the inline embed option will show live, but they will not show in the Builder.  

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 id='appcues-turbolinks' 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 id='appcues-turbo' 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();
    }
});