1. Home
  2. Developers
  3. Cordova
  4. Integrating the Apptentive Cordova SDK Plugin

Integrating the Apptentive Cordova SDK Plugin

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

Cordova Versions

Required Minimum Versions

The latest version of our plugin will not work on Cordova versions below the following:

Cordova Platform: 7.0.1

Cordova Android: 6.3.0

Cordova iOS: 4.3.1

Tested Versions

We have tested our plugin with the following Cordova and Node versions:

  • Cordova Platform: 7.0.1 – 8.1.2
  • Cordova Android Platform: 6.3.0 – 7.1.1
  • Cordova iOS Platform: 4.3.1 – 4.5.4
  • Node: v5.6.0 – v9.9.0
  • NPM: 2.14.4 – 5.8.0

Supported Platforms

This Cordova Plugin wraps our native SDKs. The complete descriptions for the features contained in our SDKs are located here:

Apptentive Android & iOS SDKs

This plugin wraps our existing native Android and iOS SDKs. The versions of the SDKs are as follows:

Registering Apps

You will need to create an app in your Apptentive account for each of the platforms you wish to use Apptentive on. Even though there is a single plugin for Cordova that works on both Android and iOS, you will need to create a separate Android and iOS app on our website.

Once you have created an Android and iOS app, you will need to access the Apptentive App Key and Apptentive App Signature for each app here.

Adding the Plugin to Your App

Our plugin is hosted on NPMJS or Github. Installation is easy, and involves pointing at our repo and passing in both of the API Keys you got from the previous step.

cordova plugin add apptentive-cordova --variable ANDROID_APP_KEY="" --variable ANDROID_APP_SIGNATURE="" --variable IOS_APP_KEY="" --variable IOS_APP_SIGNATURE=""

Note: Do not reuse the same Apptentive Keys for Android and iOS.

If you need to remove this plugin in the future, it can easily be removed with the following command:

cordova plugin remove com.apptentive.cordova

If you have trouble upgrading to a new version of Apptentive, try removing the plugin and re-adding it. In rare cases, Cordova may be in a bad stat, and you may have to remove all plugins and platforms, then re-add them.

Android-P Support

Apptentive Android SDK requires targetSdkVersion to be set to 28. If your Cordova installation does not support API 28 you would need to add a before_build hook to your config.xml file:

<?xml version='1.0' encoding='utf-8'?>
<widget ...>
    ...
    <platform name="android">
        <hook src="plugins/apptentive-cordova/scripts/androidApptentiveBeforeBuild.js" type="before_build" />
    </platform>
    ...
</widget>

Initialize Apptentive

Make sure you call Apptentive.deviceReady() when your app has started.

onDeviceReady: function() {
  Apptentive.deviceReady(successCallback, failureCallback);
}

Optional Integration

Message Center

The Message Center is a messaging UI that allows you to talk with your customer. You should find a place in your app where you can create a link or button that opens your Message Center.

Apptentive.showMessageCenter(successCallback, failureCallback);

Send Custom Data With a Message

Additionally, you can supply custom key/value pairs that will be sent in the next message that the customer sends while Message Center is open. For instance, if you have a dining app, you could pass in a key of restaurant and value of Joe's Pizza. If the customer sends a more than one message, only the first message will include this custom data. If you wish to add more custom data to another subsequent message, you will need to call this method with custom data again.

Apptentive.showMessageCenter(successCallback, failureCallback, {"key": "value"});

New Message Notification

You can be notified any time the number of unread messages in Message Center changes, by registering a listener when your device finishes initializing. You can add this next to your existing call to Apptentive.deviceReady();

Apptentive.addUnreadMessagesListener(unreadMessagesCallback, errorCallback);

When the number of unread messages changes, this listener will be called, and an integer representing the number of unread messages will be passed to it.

onDeviceReady: function() {
  Apptentive.deviceReady(app.successLogger, app.errorAlert);
  Apptentive.addUnreadMessagesListener(
    function(unreadMessages) {
      console.log("UnreadMessages: " + unreadMessages);
    },
    function (errorMessage) {
      console.log("Error: " + errorMessage);
    }
  );
}

Device Storage Encryption

If your application maintain sensitive user data (account numbers, health information, etc) and you pass it to Apptentive SDK (as a custom person/device data) – you may want to enable encrypted device storage.

Pass ANDROID_USES_DEVICE_ENCRYPTION variable while adding Apptentive plugin:

cordova plugin add apptentive-cordova --variable ANDROID_USES_DEVICE_ENCRYPTION="true" --variable ANDROID_APP_KEY="" --variable ANDROID_APP_SIGNATURE="" --variable IOS_APP_KEY="" --variable IOS_APP_SIGNATURE=""

Most of developers would not need this option since Apptentive SDK does not store sensitive or security vulnerable information (anything an attacker can use to compromise user accounts).

Adding Events

You should add a handful of Events to your app when you integrate. Since Events are both records of an action within your app being performed, and an opportunity to show an Interaction, you should choose places within your app that would be appropriate to interact with your customer, as well as places where a significant event has occured. 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. Here is a list of potential places to add Events.

Places where you might want to show an Interaction:

  • The app opens
  • Settings view gains focus
  • Customer performs an action that indicates they are confused
  • There is a natural pause in the app’s UI where starting a conversation would not interrupt the customer

Places where you might want to record an Event:

  • Customer makes a purchase
  • Customer declines to make a purchase
  • Customer beats a level
  • Customer performs an action that indicates they know how to use your app
  • Customer performs an action that indicates they are confused
  • Your app crashes

As you can see, there is some overlap in whether you want to just record an Event, or also show an Interaction.

To add an Event and possibly show an Interaction, simply call Apptentive.engage(successCallback, errorCallback, eventName, customData)
with an eventName of your choosing.

Apptentive.engage(successCallback, errorCallback, 'myEventName', customData);

Note: Each Event must have a unique name.

Configure Interactions

Once you have configured your app to use several Events, you can configure Interactions on apptentive.com

Ratings Prompt

To set up the Ratings Prompt Interaction, first make sure you have created a few Events in your app. Then, go to Interactions -> Ratings Prompt. In the tab labeled The Prompt, you can customize the text and behavior of the dialogs that make up the Ratings Prompt. The Targeting tab lets you create user segments that will see the Ratings Prompt, as well as define the conditions necessary for the Ratings Prompt to display. You will also need to pick which Event will display the Ratings Prompt will be shown, by entering an Event name in the Where section of that page.

Surveys

Surveys can also be 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.

Upgrade Messages

When you release a new version of your app, you should create an Upgrade Message to tell your customers what’s new. To do so, go to Interactions -> Upgrade Messages. You can use the editor to write out details about this release, and then target the message to display when a customer upgrades your app to a specific version name or code.

Note: Upgrade Messages are only shown if the app is upgrading from a previous version. If you are installing a version of your app that has an Upgrade Message targeted to it, but it is not upgrading from a previous version, the Upgrade Message will not be shown.

Push Notifications

Push notifications are not currently supported in our Cordova Plugin. If you are interested in using push notifications to let your customers know when you reply to their feedback, please drop us a line at support@apptentive.com

Set Customer Contact Information

If you already know the customer’s email address, you can pass it to us during initialization. Simply call

Apptentive.setPersonEmail(successCallback, errorCallback, email);

If you know their name, and would like to see it displayed when you are communicating with them through the Apptentive dashboard, call

Apptentive.setPersonName(successCallback, errorCallback, name);

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.

Apptentive.addCustomDeviceData(successCallback, errorCallback, key, value);
Apptentive.addCustomPersonData(successCallback, errorCallback, key, value);

Attachments

Our native SDKs support sending attachments to our server. This is useful for sending logs and other artifacts that help you understand customer issues. This is not currently supported in the Cordova Plugin, but if you are interested in this feature, please let us know at support@apptentive.com.

Setting Rating Provider

If your app is built for Android and you are deploying your Cordova app to Amazon’s Appstore instead of Google Play, you will need to use the following function. Pass in the string “amazon”. If you publish your app with Google Play, this step is not necessary.

Apptentive.setRatingProvider(successCallback, errorCallback, "amazon");
Updated on February 1, 2019

Was this article helpful?