1. Home
  2. Developers
  3. Web SDK
  4. Integrating the Apptentive Web SDK

Integrating the Apptentive Web SDK

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

Supported Platforms

We have tested our WebSDK with the following browser versions:

  • Chrome: 52 – 54.0.2840.41 beta (64-bit)
  • Firefox: 48.0.1
  • macOS Safari: 10.0 (12602.1.50.0.5)
  • iOS Safari: 10.0
  • Internet Explorer: 10.0.22 – 11.0.10240.16841
  • Edge: 20.10240.163840.0

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 the WebSDK 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 first script below is a minified stub to prevent our SDK from erring out in the event that the SDK is for whatever reason unreachable.

<script>(function(){var a=window.ApptentiveSDK=window.ApptentiveSDK||[];if(!a.version&&!a.loaded){a.loaded=!0;a.methods="buildDevice createConversation createMessage engage getInteractions identifyPerson setPageName".split(" ");a.factory=function(c){return function(){for(var b=arguments.length,d=Array(b),e=0;e<b;e++)d[e]=arguments[e];b=Array.prototype.slice.call(d);b.unshift(c);a.push(b);return a}};for(var c=0;c<a.methods.length;c++){var d=a.methods[c];a[d]=a.factory(d)}a.LOADER_VERSION="1.0.0"}})();</script>
<script async src="https://sdk.apptentive.com/v1/apps/YOUR_APP_ID/websdk"></script>

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.

Configure Interactions

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

Surveys

Surveys are configured from the server. First, make sure you have created some Events, then go to Interactions -> Surveys. Create a new survey. You can give it a title and description, then add questions, and finally set targeting and limiting constraints so it’s shown to the right people. After your survey is live, you will start to see results in the Surveys page.

Survey Styles

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

Page Tracking

You can optionally add an additional name to a tracked page, other than that default <title> tag, by using setPageName for an added level of tracking. This value will persist and will need to be updated as the user navigates your website.

ApptentiveSDK.setPageName('User Profile');
ApptentiveSDK.engage('profile-view');

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
  }
});

Custom Integration

Although it is possible to integrate the Apptentive WebSDK 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 March 27, 2017

Was this article helpful?

Related Articles