1. Home
  2. Developer Guides
  3. mParticle
  4. mParticle Integration: iOS

mParticle Integration: iOS

This document will guide you through setting up the 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.

1. Adding Apptentive to Your App

We support using mParticle with CocoaPods or Carthage.

CocoaPods

In your podfile, add the Apptentive kit alongside the mParticle SDK:

pod 'mParticle-Apptentive'

Carthage

If using Carthage, add the Apptentive kit alongside the mParticle SDK using:

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

2. Set Up Apptentive in the mParticle Dashboard

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

Add Output: Apptentive

  1. If you haven’t already, create an 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 Apptentive’s API & Development page, fill in the Apptentive API Key and Apptentive API Signature fields
  8. Click Save

Connect iOS Input to the 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

Note

There may be a delay of several minutes before this configuration is downloaded by mParticle, and Apptentive is enable in your app.

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 Apptentive and the Event names you passed into logEvent() will be available for segmentation and targeting of 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 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 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 Apptentive Events page

4. Configure Custom Data

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

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

Second, you can see these values in many types of Appentive 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 Apptentive, including mParticle ID, focussing 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 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");

5. Configure Apptentive Interactions

The Apptentive kit for mParticle allows you to use every kind of Apptentive Interaction. All you need to do is configure them in your Apptentive 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.

Notes

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

6. 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 Apptentive may not be enabled via your mParticle dashboard, and because you may have disabled Message Center in the Apptentive 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 Apptentive Features

Customizing the Look and Feel

By default, 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, Notes, and Apptentive Rating Dialogs use default OS alert styling. The Apple Rating Dialog uses styling provided by Google.

Updated on January 29, 2021

Was this article helpful?

Related Articles