Alchemer Mobile mParticle Integration Guide: iOS

This document will guide you through setting up the Alchemer Mobile ( formerly Apptentive) mParticle Kit through your existing mParticle integration. If you are not using mParticle, you should use the native integration documentation.

Please see our system requirements.

Check out our example app.

View GitHub details here and podspec file here.

1. Adding Alchemer Mobile (formerly Apptentive) to Your App

We support using mParticle with CocoaPods or Carthage.

CocoaPods

In your podfile, add the Alchemer Mobile (formerly Apptentive) kit alongside the mParticle SDK:

pod 'mParticle-Apptentive'

Carthage

If using Carthage, add the Alchemer Mobile (Apptentive) kit alongside the mParticle SDK using:

github "mparticle-integrations/mparticle-apple-integration-apptentive"

2. Set Up Alchemer Mobile (formerly Apptentive) in the mParticle Dashboard

You’ll need an Alchemer Mobile Dashboard to proceed. Need help creating one? Reach out to your contact at Alchemer Mobile (Apptentive) or contact support. Let us know the name of your company and apps, then we’ll get you set up as soon as possible.

Add Output: Alchemer Mobile (Apptentive)

1. If you haven’t already, create an Alchemer Mobile (Apptentive) account, and create a new iOS app in the Apptentive Dashboard
2. In the mParticle Directory, click Apptentive
3. Click +Add Apptentive to Setup
4. Check the box Output: Event
5. Click Add to Setup
6. In the next screen, give your configuration the name iOS
7. Using the values found in Alchemer Mobile (Apptentive’s) API & Development page, fill in the Alchemer Mobile API Key and Alchemer Mobile API Signature fields
8. Click Save

Connect iOS Input to the Alchemer Mobile (Apptentive) Output

1. In the mParticle menu, click Connections
2. Under Available Inputs, click iOS
3. Under Connected Outputs, click Connect Output
4. Click Apptentive
5. Select Configuration iOS
6. Turn Status on to Active
7. Click Add Connection
   

3. Configure Events

If you have already been using mParticle in your app, you will most likely have calls to MParticle.logEvent(). These calls will be delegated through to Alchemer Mobile (Apptentive) and the Event names you passed into logEvent() will be available for segmentation and targeting of Alchemer Mobile (Apptentive) Interactions. If you haven’t already logged Events in your app, you should do so now.

We recommend sending 20 to 50 Events to Alchemer Mobile (Apptentive), and these can be adjusted at any time. Instead of sending all Events, focus on those that you’d like to use for segmentation (e.g. show a Survey to customers that have triggered x Event) or for displaying Alchemer Mobile (Apptentive dialogs) (e.g. show a Love Dialog on x page when that Event is triggered).

Once Events have been toggled on in your mParticle dashboard, then triggered within your apps, they will be displayed on your Alchemer Mobile Events page. 

There are two kinds of events that are able to be passed from mParticle to Alchemer Mobile (Apptentive). Using mParticle’s terminology, those are: “Events” and “Screens”. Details on each are below.

mParticle “Events”

• Naming conventions:
  • “Events” in mParticle = “Events” in Apptentive
  • “Event Attributes” in mParticle = “Event Custom Data” in Apptentive

“Event Attributes”, which are nested under the events themselves, cannot be used in Apptentive.

mParticle “Screens”

• Naming convention:
  • “Screens” or “screen events” in mParticle = Events in Apptentive

Description from mParticle: Screen events are a special event type used for tracking navigation within your app… For most use cases, the best course of action will be to log your navigation events as screen views and let mParticle translate your data into the appropriate format for each output integration. Many output integrations are only interested in the screen name, but you can also include a set of custom attributes with a screen event.

Uncheck the box to “Send new data points by default.” Like any other Events, you should send through only screen events that will be useful to use in targeting Alchemer Mobile interactions.

As described above, mParticle allows companies to define screen event attributes. Similar to Event Attributes, Alchemer Mobile does not support this type of data for targeting at this time.

4. Configure Custom Data

User Attributes in mParticle can be sent to Alchemer Mobile (Apptentive) and used as Person Custom Data.  Alchemer Mobile (Apptentive) allows you to use this data in two ways.

First, it can be used in targeting Alchemer Mobile (Apptentive) Interactions. For example, you could show an Alchemer Mobile (Apptentive) Love Dialog only to customers with a specific Person Custom Data value.

Second, you can see these values in many types of Alchemer Mobile (Apptentive) reporting. For example, if you displayed a Survey to all customers, you could see the Person Custom Data values for specific customers in line with their responses to the Survey.

If you have already been using User Attributes on mParticle, you can send them to Apptentive as Custom Data from the Connections page of mParticle. We recommend sending 5 to 10 Person Custom Data fields to Alchemer Mobile (Apptentive), focusing on those that would be most useful to you. Please do not send all fields or any PII.

Create an instance of the current user to add custom data to:

val currentUser = MParticle.getInstance()!!.Identity().currentUser

Set the user’s key/value attributes using user.setUserAttribute(). You can add String, Integer, or Boolean values as user attributes to send as Person Custom Data:

currentUser!!.setUserAttribute("location_region", "Iceland")
currentUser.setUserAttribute("number_books_read", 45)
currentUser.setUserAttribute("have_gone_to_italy", true)

You can also add a list of attributes, which are sent as a String to Alchemer Mobile (Apptentive):

val attributeList: MutableList<String> = ArrayList()
attributeList.add("Antarctica")
attributeList.add("Rome")
attributeList.add("Greenland")

currentUser.setUserAttributeList(“destinations”, attributeList)

If you want to remove an attribute from a user:

currentUser.removeUserAttribute("top_region");

Once sent through, Alchemer Mobile (Apptentive) will automatically detect whether each user attribute is a boolean, string, or number. User attributes that are detected as either a boolean or number will be sent twice – once as a string and once with a suffix added to show the detected type “flag” (boolean) or “number”. The different types will allow you enhanced targeting options, such as “greater than” and “less than” targeting for integers.

5. Configure Alchemer Mobile (Apptentive) Interactions

The Alchemer Mobile (Apptentive) kit for mParticle allows you to use every kind of Alchemer Mobile (Apptentive) Interaction. All you need to do is configure them in your Alchemer Mobile Dashboard via the Interactions tab. Details on each type can be found below. 

Love Dialog & Rating Dialogs

Love Dialogs can help learn about your customers, ask customers that love your app to rate it in the applicable app store, and ask customers who don’t love it yet to give you feedback or answer a Survey.

Prompting customers to leave ratings and reviews with an in-app Rating Dialog is a great way to engage customers and request feedback. 

Surveys

Surveys are a powerful tool for learning about your customers’ needs.

Prompts

Prompts (formerly Notes) allow you to show an alert to customers, and optionally direct them to a Survey, Message Center, Deep Link, or simply dismiss the Prompts.

Message Center

A vital part of our product is the ability to talk to your customers using Message Center. The mParticle API doesn’t have a concept of feedback or messaging, so you will need to call into our native SDK directly.

if let apptentive = mParticle.sharedInstance().kitInstance(MPKitInstanceApptentive) {
    apptentive.presentMessageCenterFromViewController(viewController)
}

(viewController should be a view controller that is able to present a modal view controller).

You should find a place in your app where you can add a feedback button that will open Message Center. Because Alchemer Mobile (Apptentive) may not be enabled via your mParticle dashboard, and because you may have disabled Message Center in the Alchemer Mobile dashboard, you should check for availability before you show your feedback button. Here is an example:

override func viewDidLoad() {
    if let apptentive = mParticle.sharedInstance().kitInstance(MPKitInstanceApptentive) where apptentive.canShowMessageCenter() {
        feedbackButton.enabled = true
    } else {
        feedbackButton.enabled = false
    }
}

7. Other Alchemer Mobile (Apptentive) Features

Customizing the Look and Feel

By default, Alchemer Mobile (Apptentive) Surveys and Message Center will inherit your global styling. If you’d like, you can override many of those global styles. For full details, refer to our Interface Customization Guide. 

Please note that Love Dialogs, Prompts, and Alchemer Mobile Rating Dialogs use default OS alert styling. The Apple Rating Dialog uses styling provided by Google.