1. Home
  2. Apptentive iOS SDK

Apptentive iOS SDK

The Apptentive iOS SDK provides a powerful and simple channel to communicate with your customers in-app.

Use Apptentive features to manage your app’s ratings, collect and respond to customers’ feedback, show surveys at specific points within your app, and more.

There are several API changes for the 3.0 release. Please see docs/APIChanges.md.

Apptentive Example App

An Example app is included in this repository along with the SDK. The app demonstrates how you might integrate the Apptentive SDK with your own apps, including setting your API key, engaging events, and integrating with Message Center.

Install Guide

Apptentive can be installed manually as an Xcode subproject or via the dependency manager CocoaPods.

The following linked guides walk you through the integration process.

Install using CocoaPods

The Apptentive iOS SDK is available via CocoaPods, a dependency manager for Objective-C.

Please see the Apptentive CocoaPods installation guide to integrate Apptentive via CocoaPods.

Install as an Xcode subproject

The Apptentive iOS SDK can also be installed manually as an Xcode subproject.

Please see the Apptentive Xcode project setup guide to install Apptentive manually as an Xcode subproject or git submodule.

Start using Apptentive

Be sure to first integrate Apptentive as an Xcode subproject or by using CocoaPods. Please see the sections above.

Once Apptentive has been added to your Xcode project you can begin using its features. Import the Apptentive.h header file to use Apptentive in your project files:

#import "Apptentive.h"

You will primarily interact with Apptentive’s sharedConnection shared instance singleton.

[Apptentive sharedConnection]

The following sections will explain how to integrate Apptentive’s features in your app.

Set Apptentive API key

For the initial connection to the server, an app-specific API key must be set
on the Apptentive singleton. This should be done early in the app’s
lifecycle. You can find your API key in the Settings section of the Apptentive dashboard.

  1. In your app’s AppDelegate.m file, import Apptentive.h.
  2. Set your Apptentive API key in the app delegate’s application:didFinishLaunchingWithOptions: method:
#import "Apptentive.h"
// ...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...
    [Apptentive sharedConnection].APIKey = @"<#your Apptentive API key#>";
    // ...
}

If there isn’t an application:didFinishLaunchingWithOptions: method, add the above code snippet elsewhere in your app delegate’s implementation.

As soon as you set the API key on the shared connection object, any queued messages will start to upload, pending network availability. You do not have
to set the API key again on the shared connection object.

Message Center

The Apptentive Message Center provides an interface for you to communicate
directly with your customers. People using your app are able to send you
messages, which are routed to your Apptentive dashboard. When you reply to customer feedback via the dashboard, your response will
show up in the Message Center in their app.

To launch the Apptentive Message Center, import Apptentive.h and then call presentMessageCenterFromViewController::

[[Apptentive sharedConnection] presentMessageCenterFromViewController:viewController];

The viewController parameter should be the currently frontmost view controller, and will typically be set to self.

Message Center

In SDK version 2.1 and later, Message Center allows users to attach up to four images to a message. To enable this feature, ensure that your app is configured to support portrait orientation on iPhone, and that it has an entry for the NSPhotoLibraryUsageDescription key (“Privacy – Photo Library Usage Description”) in its Info.plist file (required for iOS 10 and later).

Message Center Button

Your app should include a button or similar mechanism to allow users to open Message Center. This will allow them to send feedback at any point, rather than only when prompted by a Note or Enjoyment Dialog. You might label the button “Contact Us”, “Give Feedback”, or “Support”. A Settings menu is often a good place for this feature.

Give Feedback button

Unread Messages

Use the unreadMessageCount property on the Apptentive singleton to get the current number of unread messages:

NSInteger unreadMessageCount = [[Apptentive sharedConnection] unreadMessageCount];

You can also listen for the ApptentiveMessageCenterUnreadCountChangedNotification notification to be alerted immediately when a new message arrives or when the user reads a message in Message Center.

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(unreadMessageCountChanged:) name:ApptentiveMessageCenterUnreadCountChangedNotification object:nil];

If listening for the notification via the code above, you would then implement the unreadMessageCountChanged: method. This will be called every time the unread message count changes.

- (void)unreadMessageCountChanged:(NSNotification *)notification {
    // Unread message count is contained in the notification's userInfo dictionary.
    NSNumber *unreadMessageCount = notification.userInfo[@"count"];

    // Update your UI or alert the user when a new message arrives.
    NSLog(@"You have %@ unread Apptentive messages", unreadMessageCount);
}

Events

The Ratings Prompt and other Apptentive interactions are targeted to certain Apptentive events. For example, you could decide to show the Ratings Prompt at the event user_completed_level. Later, you can reconfigure the Ratings Prompt interaction via the Apptentive dashboard to show at user_logged_in instead.

An event is a record of your customer performing an action in your app. Generate events by calling engage:fromViewController:. Apptentive stores a record of all events, which you can later use to show specific interactions to your customer.

    [[Apptentive sharedConnection] engage:@"completed_level" fromViewController:viewController];

The viewController parameter is necessary in order to show interactions such as a Ratings Prompt, Note, Survey, or Message Center when the event is engaged. You may pass nil for the viewController parameter under two circumstances: if you are absolutely certain that you will never use the event as the Where for an interaction, or if you provide a delegate (conforming to ApptentiveDelegate) to provide a view controller for presenting interactions.

The events you choose to log will be different depending on the specifics of your app. For example, if you were to release a game, you would want engage some of the following events:

  • Completed Level (engage:@"completed_level_8")
  • Ran Out of Lives (engage:@"game_over")
  • Quit Level (engage:@"quit_level_9")
  • Made In-App Purchase
  • Etc.

You’ll want to add calls to engage:fromViewController: wherever it makes sense in the context of your app. Engage more events than you think you will need, as you may want to use them later. Common app events that we recommend logging include:

  • When your app finishes loading and is ready to present a view. (engage:@"app_became_active")
  • Completes an in-app purchase. (engage:@"completed_in_app_purchase")
  • User finishes logging in. (did_log_in)
  • Completes a level. (completed_level_8)
  • Finishes watching a video. (finished_video)
  • Exits out of a video before completing it.
  • Sends a message.
  • Switches navigation tabs.
  • Etc., depending on the specifics of your app.

Be sure to add these events prior to uploading the app to the App Store, even if you are not currently using all of the events to show interactions. Later, without having to re-upload a new version, you can re-target the Ratings Prompt or other Apptentive interactions to different events.

Interactions

An Apptentive interaction is a specific piece of your app that can be shown in response to a person’s events. For example, Surveys, Message Center, and the Apptentive Ratings Prompt are all unique interactions. When users engage certain events, you can decide (based on pre-defined conditions) to show a specific interaction in your app.

Interactions are Configurable via the Apptentive Dashboard

The real strength of Apptentive Events and Interactions come from their remote configurability.

Prior to releasing your app on the App Store, seed your app with certain events.

Later, after shipping the app, you can configure the interactions that will run whenever a customer hits one of your events.

  • The 10th time they complete a level, ask them to rate the app.
  • When they beat the game, ask for feedback about their experience.
  • After making an in-app purchase, ask them to take a survey.

Interactions can be modified, remotely, without shipping a new app update to the App Store. You can easily change a particular event to show a Survey rather than collect Feedback. The remote configurability of Apptentive interactions make them perfect for A/B testing and quick iteration. You can configure interactions and when they are displayed from the Interactions section of the Apptentive dashboard.

Ratings Prompt

Apptentive provides an app Ratings Prompt interaction that aims to provide the best feedback for both you and your customers.

Customers who love your app are asked to rate the app on the App Store. Those who dislike your app are instead directed to the Apptentive Message Center, where they can communicate directly with your team. You are then able to respond directly to customer issues or feature requests.

The Ratings Prompt is configured online in your Apptentive dashboard. At that time you will configure it to be shown when a certain event is engaged. You can also edit the exact text that will be displayed.

Thus, the only code needed to display a Ratings Prompt is to engage events using the engage:fromViewController: method. The Ratings Prompt is otherwise configured from your Apptentive dashboard.

    [[Apptentive sharedConnection] engage:@"completed_level" fromViewController:viewController];

One you have engaged some events, you can create a Ratings Prompt and modify the parameters which determine when it will be shown in your interaction settings on Apptentive.

Enjoyment Dialog

spacer image

Enjoyment Dialog

spacer image

Enjoyment Dialog

Surveys

Apptentive Surveys are created on the Apptentive dashboard and presented natively in your app.

Surveys are cached and are only re-downloaded intermittently to cut down on network connections. If you create a survey online, you may not immediately see it on your device. To test the survey, force a cache refresh by deleting and re-running your app or reseting the iOS simulator.

Like all Apptentive interactions, Surveys are targeted at an event you engage in your app:

    [[Apptentive sharedConnection] engage:@"completed_in_app_purchase" fromViewController:viewController];

Engaging the completed_in_app_purchase event above will allow you to show a survey after users of your app complete an in-app purchase. Target the event during the survey creation process:

Target a survey to an event.

When your survey goes live, it will be presented to app users who engage an in-app purchase event:

Survey

Upgrade Messages

In iOS 7, users are upgraded automatically when a new version of your app is released. Unfortunately, this means they will rarely (if ever) see your App Store release notes!

Apptentive’s Upgrade Message feature allows you to display a brief message when your app has been updated. You can speak directly to your users and let them know what has changed in the release.

Upgrade Messages are targeted at an event via the Apptentive dashboard. You will likely want this event to be engaged soon after your app launches and is able to display a view.

- (void)applicationDidBecomeActive:(UIApplication *)application {
    [[Apptentive sharedConnection] engage:@"app_became_active" fromViewController:viewController];
}

Like the Rating Dialog, Upgrade Messages are created and configured online via your Apptentive dashboard.

Custom Data

Custom data can be attached to a device, Apptentive user, or individual message. This data will then be displayed for reference alongside the conversation on the Apptentive website.

Custom data should be of type NSString, NSNumber, or BOOL.

- (void)addCustomPersonDataString:(NSString *)string withKey:(NSString *)key;
- (void)addCustomPersonDataNumber:(NSNumber *)number withKey:(NSString *)key;
- (void)addCustomPersonDataBool:(BOOL)bool withKey:(NSString *)key;
- (void)addCustomDeviceDataString:(NSString *)string withKey:(NSString *)key;
- (void)addCustomDeviceDataNumber:(NSNumber *)number withKey:(NSString *)key;
- (void)addCustomDeviceDataBool:(BOOL)bool withKey:(NSString *)key;
- (void)presentMessageCenterFromViewController:(UIViewController *)viewController withCustomData:(NSDictionary *)customData;

When Message Center is presented with custom data, that custom data will be attached to the first message in the Message Center session.

Attachments

The methods below can be used to attach text, images, or files to the user’s feedback.

These attachments will appear in your online Apptentive dashboard, but will not appear in Message Center on the user’s device. They may be useful for sending debug logs or other pertinent information.

- (void)sendAttachmentText:(NSString *)text;
- (void)sendAttachmentImage:(UIImage *)image;
- (void)sendAttachmentFile:(NSData *)fileData withMimeType:(NSString *)mimeType;

Push Notifications

Apptentive has native support for sending Push Notifications when new messages arrive in Message Center.

Apptentive can also integrate with your existing Urban Airship, Parse, or Amazon Simple Notification Service (SNS) account to offer these notifications.

Only one Push Notification provider can be added at a time via the setPushNotificationIntegration:withDeviceToken: API method. Calling the method a second time will delete the previous Push Notification integration.

To set up the Push integration, log in to your Apptentive dashboard on the web. Under “App Settings”, select “Integrations”. Add a new integration by entering the required information and keys.

You will be responsible for registering for Remote Notifications in your iOS app. Registering for Remote Notifications will ask for Permissions, so this should be done at the proper time and place. The code for registering for Push should look something like the following. You may have this code in your app already, if you offer any other forms of Push.

if ([[UIApplication sharedApplication] respondsToSelector:@selector(registerUserNotificationSettings:)]) {
    UIUserNotificationSettings *notificationSettings = [UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert categories:nil];

    [[UIApplication sharedApplication] registerUserNotificationSettings:notificationSettings];
} else {
    UIRemoteNotificationType notificationTypes = UIRemoteNotificationTypeAlert;

    [[UIApplication sharedApplication] registerForRemoteNotificationTypes:notificationTypes];
}

Next, in your iOS app, add an Apptentive integration with your device token. This device token will be obtained from your app delegate’s application:didRegisterForRemoteNotificationsWithDeviceToken: method:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

    // Apptentive Push
    [[Apptentive sharedConnection] setPushNotificationIntegration:ApptentivePushProviderApptentive withDeviceToken:deviceToken];

    /*
     // Use one of the following Push Providers. Only one can be used at a time.
     ApptentivePushProviderApptentive
     ApptentivePushProviderUrbanAirship
     ApptentivePushProviderAmazonSNS
     ApptentivePushProviderParse
    */
}

When push notifications arrive, pass them to Apptentive:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler{
    UIViewController *viewController = self.window.rootViewController;

    BOOL apptentiveNotification = [[Apptentive sharedConnection] didReceiveRemoteNotification:userInfo fromViewController:viewController fetchCompletionHandler:completionHandler];

    if (apptentiveNotification) {
        // If the notification came from Apptentive, the `completionHandler` block will be called automatically.
    } else {
        // If the notification did not come from Apptentive, you are responsible for calling the `completionHandler` block.
        completionHandler(UIBackgroundFetchResultNoData);
    }
}

If the push notification was sent by Apptentive, we will then present Message Center from the viewController parameter.

Finally, to enable fetching new messages when your app is in the background, select “Remote Notifications” in the “Background Modes” section of the capabilities for your app target in Xcode.

Customization

For information on customizing the UI and text of apptentive-ios, please see the Apptentive iOS SDK’s customization guide.

Testing Apptentive Features

Apptentive interactions are only shown if the conditions set on your Apptentive dashboard are met. Your Ratings Prompt might only show 3 days after installing the app, for example.

This can make some Apptentive features somewhat hard to invoke and test. An interaction may or may not be shown whenever you engage an event in your app.

Please see the Apptentive testing guide for directions on how to test that the Ratings Prompt, Surveys, and other Apptentive features have been configured correctly.

Updated on December 13, 2016

Was this article helpful?