The Apptentive iOS SDK lets you provide a powerful and simple channel to your customers. With it, you can manage your app's ratings, let your customers give you feedback, respond to customer feedback, show surveys at specific points within your app, and more.
There have been many recent API changes for the 1.0 release. Please see docs/APIChanges.md.
Note: For developers with apps created before June 28, 2013, please contact us to have your account upgraded to the new Message Center UI on our website.
This guide will walk you through implementing Apptentive within your iOS app. Below is a video demonstration of how quick and easy this integration is.
All of our client code is open source and available on GitHub.
You can clone our iOS SDK using git: git clone https://github.com:apptentive/apptentive-ios.git.
Please note that if you use CocoaPods to get Apptentive, you can skip workspace configuration and go directly to Apptentive implementation below.
- Search for Apptentive's pod information on CocoaPods.
- List and save the dependencies in a text file named "Podfile" in your Xcode project directory. It should look something like this:
platform :ios, '6.0'
pod 'apptentive-ios'
Now you can install the dependencies in your project. Run this command in your Xcode project directory in Terminal:
$ pod install
First, drag the ApptentiveConnect.xcodeproj project file (located in the ApptentiveConnect folder of our source code) to your project in Xcode 5 and add it as a subproject.
Next, in order to use ApptentiveConnect, your project must link against the
following frameworks:
- Accelerate
- CoreData
- CoreText
- CoreGraphics
- CoreTelephony
- Foundation
- QuartzCore
- StoreKit
- SystemConfiguration
- UIKit
Note: If your app uses Core Data and you listen for Core Data related notifications, you will want to filter them based upon your managed object context. Learn more from Apple's documentation.
- Click on your Xcode project in the file browser sidebar.
- Go to your Xcode project's
Build Phasestab. - Expand "Link Binary With Libraries".
- Click on the
+button and add the frameworks listed above.
- Click on your Xcode project in the file navigator sidebar.
- Go to your Xcode project's
Build Settingstab. - Search for
Other Linker Flags - Double click in the blank area to the right of
Other Linker Flagsbut under the "Yes" ofLink With Standard Libraries - Click on the
+button and add the following:
-ObjC -all_load
Note: If you can't use the -all_load flag in your project, you can use the -force_load flag instead:
-force_load $(BUILT_PRODUCTS_DIR)/libApptentiveConnect.a
- Go back to your Xcode project's
Build Phasestab. - Add the
ApptentiveConnectandApptentiveResourcesas targets in your project'sTarget Dependencies.
Under Link Binary With Libraries, add libApptentiveConnect.a.
Building for iOS devices first works around a bug in Xcode 5.
- In the upper left corner of your Xcode window, click on your project name in the scheme picker.
- Select
Apptentive Resources. - Click to the right of the arrow next to
Apptentive Resources. - Select
iOS Devices. - Under
Productin your Mac's menu bar, click onBuild.
- In the file navigator, expand the ApptentiveConnect project.
- Expand
Products. - Under your Xcode project's
Build Phases, expandCopy Bundle Resources. - Drag
ApptentiveResources.bundlefrom theApptentiveConnectproducts in the file navigator intoCopy Bundle Resources.
- In the file navigator, expand
sourceunder the ApptentiveConnect project. - Drag
ATConnect.hfromApptentiveConnect.xcodeprojto your app's file list.
ApptentiveConnect queues feedback and attempts to upload in the background. This
is intended to provide as quick a mechanism for submitting feedback as possible.
In order for queued/interrupted feedback uploads to continue uploading, we
recommending instantiating ATConnect and setting the API key at application
startup.
- Open up your app's
AppDelegate.mfile. - Under
#import "AppDelegate.h", import theATConnect.hfile. - Under implementation, edit the
applicationDidFinishLaunchingmethod to look like so:
#include "ATConnect.h"
// ...
- (void)applicationDidFinishLaunching:(UIApplication *)application /* ... */ {
ATConnect *connection = [ATConnect sharedConnection];
connection.apiKey = @"<Your API Key>";
// ...
}If there isn't an applicationDidFinishLaunching method, add the above code snippet to your App Delegate's implementation.
As soon as you set the API key on the shared connection object, any queued feedback will start to upload, pending network availability. You also should not have to set the API key again on the shared connection object.
Now, whereever you want to launch the Apptentive feedback UI from...
- Include the
ATConnect.hheader file. - Add the following code to whichever method responds to feedback.
#include "ATConnect.h"
// ...
ATConnect *connection = [ATConnect sharedConnection];
[connection presentMessageCenterFromViewController:viewController];
ApptentiveConnect now provides an app rating flow similar to other projects
such as Appirater. This uses the number
of launches of your application, the amount of time users have been using it, and
the number of significant events the user has completed (for example, levels passed)
to determine when to display a ratings dialog.
To use it...
- Open your project's
AppDelegate.mfile. - Add the
ATAppRatingFlow.hheader file to your project. - Instantiate a shared
ATAppRatingFlowobject with your iTunes App ID (see "Finding Your iTunes App ID" below):
#include "ATAppRatingFlow.h"
// ...
- (void)applicationDidFinishLaunching:(UIApplication *)application /* ... */ {
ATAppRatingFlow *sharedFlow = [ATAppRatingFlow sharedRatingFlow];
sharedFlow.appID = @"<Your iTunes App ID>";
// ...
}Finding Your iTunes App ID
In iTunesConnect, go to "Manage Your Applications" and click on your application. In the "App Information" section of the page, look for the "Apple ID". It will be a number. This is your iTunes application ID.
The ratings flow won't show unless you call the following:
[[ATAppRatingFlow sharedRatingFlow] showRatingFlowFromViewControllerIfConditionsAreMet:viewController];The viewController parameter is necessary in order to be able to show the
feedback view controller if a user is unhappy with your app.
You'll want to add calls to -showRatingFlowFromViewControllerIfConditionsAreMet: wherever it makes sense in the context of your app.
If you're using significant events to determine when to show the ratings flow, you can increment the number of significant events by calling:
[sharedFlow logSignificantEvent];You can modify the parameters which determine when the ratings dialog will be shown in your app settings on Apptentive.
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.
To present an upgrade message, engage the code point app.launch when your application becomes active:
- (void)applicationDidBecomeActive:(UIApplication *)application {
[[ATConnect sharedConnection] engage:@"app.launch" fromViewController:viewController];
}Upgrade Messages are created and configured online via your Apptentive dashboard.
Surveys can be created on our website and presented, in-app, to users.
Surveys are cached and will only be re-downloaded every 24 hours, to cut down on network connections. When developing your app and testing Apptentive, force a cache refresh by delete the app from your device and re-running.
To begin using surveys...
- In the file navigator, expand
sourceunder the ApptentiveConnect project. - Drag
ATConnect.hfromApptentiveConnect.xcodeprojto your app's file list. - Import
ATSurveys.hinto the file where you need it.
There are both tagged surveys and untagged surveys. Tags are useful for defining surveys that should be shown only in certain instances.
To check if a survey with a given set of tags is available to be shown, call:
NSSet *tags = [NSSet setWithArray:@[@"bigWin", @"endOfLevel", @"usedItem"]];
if ([ATSurveys hasSurveyAvailableWithTags:tags]) {
[ATSurveys presentSurveyControllerWithTags:tags fromViewController:viewController];
}Note: Tags for a particular survey are set on the Apptentive website.
To show a survey without tags, use:
if ([ATSurveys hasSurveyAvailableWithNoTags]) {
[ATSurveys presentSurveyControllerWithNoTagsFromViewController:viewController];
}New surveys will be retrieved automatically. When a new survey becomes available,
the ATSurveyNewSurveyAvailableNotification notification will be sent.
#include "ATSurveys.h"
// ...
- (void)applicationDidFinishLaunching:(UIApplication *)application /* ... */ {
// ...
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(surveyBecameAvailable:) name:ATSurveyNewSurveyAvailableNotification object:nil];
}
- (void)surveyBecameAvailable:(NSNotification *)notification {
// Present survey here as appropriate.
}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, NSDate, or NSNull.
- (void)addCustomPersonData:(NSObject<NSCoding> *)object withKey:(NSString *)key;
- (void)addCustomDeviceData:(NSObject<NSCoding> *)object 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.
Metrics provide insight into exactly where people begin and end interactions with your app and with feedback, ratings, and surveys. You can enable and disable metrics on your app settings page on Apptentive.
The sample application FeedbackDemo demonstrates how to integrate the SDK with your application.
The demo app includes integration of the message center, surveys, and the
ratings flow. You use it by editing the defines.h file and entering in
the Apple ID for your app and your Apptentive API token.
The rating flow can be activated by clicking on the Ratings button. It asks the user if they are happy with the app. If not, then a simplified feedback window is opened. If they are happy with the app, they are prompted to rate the app in the App Store:
