1. Home
  2. Developers
  3. Apptentive for Web
  4. Integrating Apptentive for Web

Integrating Apptentive for Web

This document will show you how to integrate the Apptentive for Web into your website, configure it, and test to make sure it’s working properly.

Supported Platforms

We have tested Apptentive for Web with the following browser versions:

  • Chrome: 52 – 81
  • Firefox: 48.0.1 – 74.0
  • macOS Safari: 13.1
  • iOS Safari: 10.0
  • Internet Explorer: 10.0.22 – 11
  • Edge: 20

Registering Apps

You will need to create an app in your Apptentive account for each of the websites you wish to use Apptentive on. You will need to create a separate app for each website on your dashboard.

Once you have created an app, you will need to access the snippet here.

Adding Apptentive for Web to Your Website

Installation is easy, and involves adding a snippet of code to your website just before the closing header tag, </head>, and adding event calls where applicable. Make sure you replace YOUR_APP_ID with your own Apptentive App ID. The script provides a minified stub to prevent our SDK from erring out in the event that the SDK is for whatever reason unreachable. You can find this script for your app here.

Note: Do not reuse the same tracking app for multiple websites unless you intend on tracking them as a single entity.

Mobile Websites

It is important that your site has the proper viewport scale set in the <head> <meta /> tags if you haven’t already:

<meta name="viewport" content="width=device-width, initial-scale=1">

Integration

If you have the snippet added to your page, you are ready to begin by creating a Conversation which will be used when integrating Events. You cannot engage Events without a Conversation.

Creating a Conversation

The primary interaction with your customers is through a Conversation, all Events and Interactions are tied to this conversation. To start the conversation, you will simply call ApptentiveSDK.createConversation(options);. You can optionally configure your app_release for tracking versioning, person if you know the customer information before the conversation starts, and a device object if you need more information than we collect by default. Below are both a minimal and detailed example:

ApptentiveSDK.createConversation();
ApptentiveSDK.createConversation({
  app_release: {
    version: '1.0.0'
  },
  person: {
    unique_token: 'UNIQUE_IDENTIFIER',
    name: 'Full Name',
    email: 'user@domain.tld',
    custom_data: {
      age: 30
    }
  },
  device: {
    custom_data: {
      flash: true,
      es6: false
    }
  }
});

Set Customer Contact Information

If you already know the customer’s name and/or email address, you can pass it to us during (as seen above) or after you have started a conversation using ApptentiveSDK.identifyPerson. Simply call:

ApptentiveSDK.identifyPerson({
  unique_token: 'UNIQUE_IDENTIFIER',
  name: 'Full Name',
  email: 'user@domain.tld'
});

The unique_token field is required, and should be unique to each person, such as a user ID.

Adding Events

You should add a handful of Events to your website when you integrate. Since Events are both records of an action within your website being performed, and an opportunity to show an Interaction, you should choose places within your website that would be appropriate to interact with your customer, as well as places where a significant event has occurred. The more Events you add during integration, the more you will learn about your customers, and the more fine tuned your communications with them can be.

To add an Event and possibly show an Interaction, simply call ApptentiveSDK.engage("eventName"); with an "eventName" of your choosing:

ApptentiveSDK.engage('myEventName');

Note: Each Event may be used in multiple places throughout your code. Events are grouped by their name, so for any differentiation between sections or contexts you will need to use a different Event name.

Message Center

With the Apptentive Message Center for Web, your customers can send feedback and you can easily send replies directly to their emails.

Message Center can be launched in two ways. First, it can be launched directly from a button on your website. To do so, call the following method:

ApptentiveSDK.showMessageCenter()

It can also be launched from other Apptentive Interactions, specifically from the Love Dialog when a customer says “No” or from Notes.

We recommend using a combination of both methods. This is the best of both worlds and allows customers to contact you when they need help, as well as prompting them for specific feedback at meaningful moments.

Replying to Customers

In order to reply to customers, you must have their emails. You can make this a requested or required field from your Apptentive Dashboard with no code changes necessary.

We also recommend that you pre-populate those fields for any customers whose information you know using the instructions to set customer contact information.

Configure Interactions

Once you have added several Events to your app, you can configure Interactions on your Apptentive dashboard.

Interaction Styles

You have some control over the appearance of the Interactions on your site through the Interactions -> Interaction Styling section of your Apptentive account. Any style modifications outside of this are not recommended and not supported.

Custom Data

You can send Custom Data associated with either the device, or the person using the app. This is useful for sending user IDs and other information that helps you support your users better. Custom Data can also be used for configuring when Interactions will run.

ApptentiveSDK.buildDevice({
  custom_data: {
    flash: true,
    html: false
  }
});
ApptentiveSDK.identifyPerson({
  unique_token: 'UNIQUE_IDENTIFIER',
  custom_data: {
    purchase: true,
    age: 30
  }
});

Changing Options

In some instances you may want to change defaults on page, to do so you will use the "setOption" method of the SDK.

Option: domNode

In some environments such as kiosks or other special HTML driven environments you may want to render Interactions into a target DOM node for layering considerations. This can be set with the "domNode" option which takes any valid CSS selector string. This can and should be called as early as possible when setting up the SDK.

ApptentiveSDK.setOption('domNode', '#target-dom-node');

Custom Integration

Although it is possible to integrate Apptentive for Web into other types of JavaScript based environments, this integration is currently unsupported. You may need to use this option if you are building an Electron app or some other web-like environment. To make use of the SDK in this way you can call the SDK directly. To do this we need to instantiate a new instance:

<script src="https://sdk.apptentive.com/v0/sdk.min.js"></script>
<script>
// Our SDK object we will use through out our code.
var ApptentiveSDK;
ApptentiveSDK = new ApptentiveBase({
  debug: false,
  token: 'API_TOKEN'
});
</script>

From here the rest of the examples above apply. You can optionally enable a debug flag which can be useful while integrating, but should be left off for production use.

Updated on June 8, 2020

Was this article helpful?

Related Articles