Home Integrations Customer Feedback Appcues Integration

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Appcues Integration

In this article you'll learn:

  • Steps to connect Appcues as either a source or a destination
  • What types of events are automatically captured via this integration
This doc is for: Admins Architects

Overview

Heap has a bi-directional integration with Appcues that allows you to both measure the outcome of Appcues flows in Heap and activate Heap segments in Appcues for personalized targeting based on behavioral data.

There are two integrations between Heap and Appcues:

Integration DirectionBenefitsSetup
Source: Appcues data into HeapUnderstand how Appcues flows performed and measure the resulting actionsSet up the integration from the Appcues UI.
Destination: Heap segments into AppcuesPersonalize Appcues flow targeting based on past user behaviorsReach out to your Account Manager or support@heap.io to enable a trial. Then, set up the integration from Heap.

Source

The Appcues source automatically sends all Appcues tour events as events in Heap to make it easy to analyze the effectiveness of your walkthroughs.

With Heap’s Appcues source, you’ll be able to:

  • Understand what drives feature engagement and customer retention.
  • Find bottlenecks in sign up and onboarding flows.
  • Attribute conversion and identify the best performing marketing channels.

Setup

To set up the Heap Appcues source, all you need to do is select Heap in the Appcues integration page and click Activate.

Data Format

Once enabled, Heap will automatically capture all Appcues flow events:

  • Flow Started: Fired when the first step of a flow is started or displayed on the page. If this event is fired, then the Flow Aborted and Flow Error events should not be fired. This should be fired before the Step Started event.
  • Flow Completed: Fired when the user completes the last step of the flow. This should be fired after the Step Completed event.
  • Flow Skipped: Fired when the user chooses to skip a flow. This should fire after the Step Skipped event is fired for the corresponding step.
  • Flow Aborted: Fired when there is a “fatal” error that prevents starting or completing a flow. If this event is fired before the first step is started, then Flow Started should not be fired. This should be fired after the Flow Error event.
  • Step Started: Fired when the step-group is run or displayed on the page. If this event is fired, then the Step Aborted and Step Error events should not be fired. This should be fired before Step Child Activated or Step Child Recovered events are fired.
  • Step Completed: Fired when the user completes a step-group. For modals and tooltips, this means closing the content with the “complete button”. For hotspots, this means clicking on the last hotspot. This should be fired before the Flow Completed event.
  • Step Skipped: Fired when the user chooses to skip a step-group or flow. This should be fired before the Flow Skipped event.
  • Step Aborted: Fired when there is a “fatal” error that prevents starting or completing a step-group. If this event is fired before we show the step-group, then Step Started should not be fired. This should be fired before the Flow Aborted event.
  • Step Interacted: Fired when a user interacts with a step-group in some way.  Currently we track when a user does any of the following: clicks a link in a flow, clicks a button (built-in or custom) in a flow, submits a form in a flow, clicks on a hotspot to expand it.
  • Form Submitted: Fired when a user submits a form in a modal. This should be fired before the Step Child Deactivated event it may trigger and before the Form Field Submitted event(s) that it will trigger.
  • Form Field Submitted: Fired for each field in a form that a user submits in a modal. This should be fired after the Form Submitted event.
  • NPS Survey Started: Fired when a user has seen the NPS survey.
  • NPS Score Submitted: Fired when a user has submitted an NPS score.
  • NPS Feedback Submitted: Fired when a user has submitted NPS feedback after selecting an NPS score.
  • NPS Ask Me Later Selected: Fired when a user selects the “Ask Me Later” button.
  • NPS Update Score Selected: Fired when a user that has already submitted an NPS score selected the “Update Score” option and potentially changed their NPS score.

For a full list of events and properties that Appcues sends to Heap, check out the Appcues event reference guide.

Please refer to Appcues’s documentation for more information on the Heap Appcues source.

Event Schema

The events will have the following event properties when provided by Appcues.

EventProperty
Flow Started
Flow Completed
Flow Skipped
Flow Aborted		Flow ID
Flow Name
Flow Version
Timestamp
Step Started
Step Completed
Step Skipped
Step Aborted
Flow ID
Flow Name
Flow Version
Timestamp
Step ID
Step Type
Step InteractedFlow ID
Flow Name
Flow Version
Timestamp
Step Child ID
Step Child Number
Step Type
Form Submitted
Flow ID
Flow Name
Flow Version
Timestamp
Step ID
Step Type
Interaction Type
Form ID
Form Field SubmittedFlow ID
Flow Name
Flow Version
Timestamp
Step ID
Step Type
Interaction Type
Category
Form ID
Field ID
Label
Value
NPS Survey Started
NPS Ask Me Later Selected		Timestamp
Page Title
Page URL
NPS Score Submitted
NPS Update Score Selected		Timestamp
Page Title
Page URL
NPS Score
NPS Feedback SubmittedTimestamp
Page Title
Page URL
NPS Feedback

All Event Properties

  • Flow ID: The ID of the flow
  • Flow Name: The human-readable title of the flow
  • Flow Version: Indicates a particular version of the flow (currently the same as the updated at timestamp)
  • Timestamp: Timestamp when the event occurs
  • Step ID: The ID of the step-group
  • Step Type: The type of pattern of this step-group (hotspot-group, modal, etc)
  • Interaction Type: How the user interacted with the step-group (click, hover, submit, etc)
  • Interaction: An object representing information about the user’s interaction
  • Category: Category of the thing upon which the interactionType was performed
  • Destination: Where the user is directed (for clicks on links or buttons)
  • Form ID: The ID of the form object that was submitted
  • Response: List of response objects
  • Field ID: The ID of a specific field in a form
  • Label: The label describing the form field
  • Value: The value the user entered in the form field
  • Page Title: The title of the page the user was on when the event was completed
  • Page URL: The url of the page the user was on when the event was completed
  • NPS Score: The score that the user selected
  • NPS Feedback: The qualitative feedback the user provided

Destination

Appcues data-out is only available for customers on a paid plan. To upgrade, contact sales@heap.io.

The Appcues destination can be used to create and send Heap segments to Appcues to personalize flow targeting based on users’ past behaviors. If you’re interested, please reach out to your Account Manager or support@heap.io to enable a trial.

Sync Limits

After you enable this integration, you can initiate an unlimited number of one-time segment syncs and up to 30 recurring segment syncs to Appcues.

Setup

Requirements: Shared Identity & Appcues Installation

User profiles in Heap must have an ID whose value matches the identities in Appcues (e.g. Heap user property some_user_prop has value 123 when Appcues user identity has value 123). You can send this ID to Heap using identify or as a user property. Alternatively, you can set up the Appcues source, which will automatically attach the Appcues identity as a user property called appcuesUserID in Heap.

Appcues must also be installed everywhere Heap is installed for this integration to work.

After the integration is enabled, you’ll need to enter the following setup information in the Connect UI:

  • Appcues Account ID, which can be found in Settings > Account > Account ID in the Appcues UI.
  • Appcues API key, which can be found in Settings > Account > API keys > Legacy API Key (copy the key column) in the Appcues UI.
  • Identity Property, which is the user property in Heap that contains the same value as identities in Appcues (see Requirements: Shared Identity & Appcues Installation above for more information)

After this one-time setup, you should be able to navigate to your Heap segments and sync segments to Appcues.

When completing this setup, please note the following:

  • You must select as the Identity Property whichever Heap user property corresponds to Appcues identities. The values of the property selected in Heap must match the values of Appcues identities. Otherwise, segments of users from Heap will not be recognizable in Appcues for targeting.
  • You must be an Admin in Heap to sync data to Appcues.

Segment Sync

Step 1: You can sync any public segment from Heap to Appcues in the Segments view. Once segments are synced, the last sync timestamp will be displayed in the segment’s Appcues section. Simply navigate to the segment in Heap via Define > Segments, then click the toggle next to Appcues.

An Heap users segment categorized under Appcues Test where the mouse is clicking the 'Sync segment to Appcues' toggle

Once you click the toggle, you’ll have the option to do a one-time immediate sync, or schedule a recurring sync. If you choose recurring, the segment will be updated hourly. Note that you can only schedule a maximum of ten recurring syncs at a time.

Step 2: The segment will be synced to Appcues as an Appcues custom property with the name “[Heap] ”. You can view the properties in the Appcues settings page.

The Appcues Settings > Events and properties page with a clicked widget event is listed

Step 3: To target users in the segment, you can create an Appcues segment with a rule that filters for the value “true” on the custom property.

The net result of this sync will be a list of users that is refreshed each sync. The Data Type as it appears in Appcues is a boolean (true / false).

The Appcues Segments page

Event Sync to Appcues

The above setup only lets you send segments to Appcues. If you want to track events in Heap and forward them to Appcues, there is a workaround using our Snapshots feature. You can create a Snapshot on any defined event in Heap and use that snapshot to trigger a “track event” action into Appcues.

Note that Snapshots fire based on event definition selectors only, regardless of event definition filters. Any event definition filters present will not prevent a Snapshot from firing.

Step 1: Define an event in Heap and add a new Snapshot property on the event from the events view.

The Add Snapshot button on an events page under the Snapshot properties header

Step 2: Set the property value to Appcues.track("event name"); where the event name can be replaced with any event name you want to show up in Appcues for this event.

Step 3: Test performing that event on your site and see if the event appears in Appcues.

Frequently Asked Questions

What happens when I change the name of the segment in Heap? 

We will continue syncing the segment to Appcues using the original segment name from first sync to Appcues. This name is shown in the Heap segment UI next to the sync toggle. If you want to update the name in Appcues, you can change the display name in the Appcues UI under Settings > Events and Properties > Custom properties > Display Name column.