Iterable's iOS SDK

Iterable's iOS SDK supports features such as push notifications, in-app messages, deep links, and Mobile Inbox. It can be used with iOS 9 and higher.

This document describes how to install and configure the SDK to work with Iterable.

# Table of contents

To install and configure Iterable's iOS SDK, follow these steps:

# 1. Create a Notification Service Extension (if necessary)

For an iOS app to support push notifications that contain action buttons, images, videos or custom sounds, its Xcode project must contain a Notification Service Extension. It's helpful to set your app's Notification Service Extension target up before installing and configuring the SDK.

To add a Notification Service Extension target to your Xcode project:

1. Open your app's Xcode project.

2. Choose File > New > Target.

3. On the iOS tab, select Notification Service Extension:

   

4. Click Next.

5. Provide all necessary configuration information for the Notification Service Extension.

6. Click Finish.

Next, install the SDK using one of the methods described below. Then, configure the Notification Service Extension

# 2. Install the SDK

To install the SDK, use the Swift Package Manager, CocoaPods, Carthage, or install it manually.

# 2.1. Install the SDK with the Swift Package Manager

Swift Package Manager is an Xcode tool that installs project dependencies. To use it to install Iterable's iOS SDK, follow these steps:

1. In Xcode, click File > Add Packages....

2. In the window that opens, enter https://github.com/iterable/swift-sdk in the upper-right corner:

   

3. Use the Dependency Rule and Add to Project options to specify which version of the SDK you'd like to add, and the project to which you'd like to add it. For example, to use the latest version of the SDK found the current major version sequence, choose Up to Next Major Version for Dependency Rule and enter 6.0.0 for the lower version number.

   For more information about these options, see the Decide on Package Requirements section of Apple's guide, Adding Package Dependencies to Your App.

4. Click Add Package.

5. When prompted to choose package products:

   

   • Check IterableSDK, and choose the target associated with your app.

   • If you'll send push notifications with action buttons, images, videos, or custom sounds, check IterableAppExtensions. Then, choose the target associated with your app's Notification Service Extension.

6. Click Add Package.

The packages will be added to your app.

# 2.2. Install the SDK with CocoaPods

To use CocoaPods to install Iterable's iOS SDK, follow these steps:

1. Install CocoaPods.

2. If your project does not yet have a Podfile, create one:

   • In the terminal, navigate to the directory containing your project's .xcodeproj file.

   • Run this command: pod init.

3. Edit the Podfile:

   • In this file, add the Iterable-iOS-SDK pod to your project's app target.

   • If your will send push notifications that contain action buttons, images, videos or custom sounds, add the Iterable-iOS-AppExtensions pod to your project's Notification Service Extension.

   • After these changes, your Podfile should look similar to the following:

     platform :ios, '11.0'
     
     target '<YOUR_APP_TARGET>' do
         pod 'Iterable-iOS-SDK'
     end
     
     target '<YOUR_NOTIFICATION_EXTENSION_TARGET>' do
         pod 'Iterable-iOS-AppExtensions'
     end
     

     NOTE

     In versions 6.3.3 and above, it's no longer necessary to include use_frameworks! in your Podfile.

4. In the terminal, run pod install to install the pods you configured in the previous step. If you see errors, try pod install --repo-update.

5. Your project now has an .xcworkspace file. Use this file to open your project, instead of its .xcodeproj file.

For more information, read the CocoaPods documentation.

# 2.3. Install the SDK with Carthage

To use Carthage to install Iterable's iOS SDK, follow these steps:

# 2.3.1. Add IterableSDK.framework

First, add IterableSDK.framework to your project:

1. Install Carthage.

2. Create a Cartfile in the same directory as your .xcodeproj or .xcworkspace file.

3. Add this line to the Cartfile:

   github "Iterable/swift-sdk" 
   

4. Open a terminal window. In it, navigate to the same directory as your Cartfile.

5. Run this command: carthage update.

6. From the terminal, open a Finder window: open .. In this window, navigate to the Carthage/Build/iOS subdirectory. Keep this window open.

7. Open your app's Xcode project.

8. From the Finder window opened above, drag IterableSDK.framework onto Xcode's Project Navigator (far left column). When prompted, add the framework to your app target.

9. In Xcode's Project Navigator, select the top item, which corresponds to the project itself.

10. Under Targets, select your app.

11. Navigate to Build Phases.

12. Add a build phase by clicking + and selecting New Run Script Phase. A Run Script section will appear.

13. In the new Run Script section, add this command in the text area:

    /usr/local/bin/carthage copy-frameworks
    

14. In the Input Files section, click + and add:

    $(SRCROOT)/Carthage/Build/iOS/IterableSDK.framework
    

15. In the Output Files section, add the path to the copied framework:

    $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/IterableSDK.framework
    

# 2.3.2. Add IterableAppExtensions.framework

If you will send push notifications that have action buttons, images, videos or custom sounds, follow these steps, too:

1. Open your app's Xcode project.

2. From the Finder window opened in the previous section, drag IterableAppExtensions.framework onto Xcode's Project Navigator (far left column). When prompted, add the framework to your Notification Service Extension target.

3. In Xcode's Project Navigator, select the top item, which corresponds to the project itself.

4. Under Targets, select your Notification Service Extension.

5. Navigate to Build Phases.

6. Add a build phase by clicking + and selecting New Run Script Phase. A Run Script section will appear.

7. In the new Run Script section, in the script text area, add this command:

   /usr/local/bin/carthage copy-frameworks
   

8. In the Input Files section, click + and add this path:

   $(SRCROOT)/Carthage/Build/iOS/IterableAppExtensions.framework
   

9. In the Output Files section, add the path to the copied framework:

   $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/IterableAppExtensions.framework
   

# 3. Configure the Notification Service Extension (if necessary)

If you added a Notification Service Extension to your project (above), you can now set it up to handle media attachments and action buttons. To do this, use the ITBNotificationServiceExtension class provided by Iterable's iOS SDK:

• Open the NotificationService class (auto-generated by Xcode when you added the Notification Service Extension to your project).

• For Swift-based projects:

  • Add an import: import IterableAppExtensions.

  • Update NotificationService so that it extends ITBNotificationServiceExtension, and contains no other code:

    import UserNotifications
    import IterableAppExtensions
    
    class NotificationService: ITBNotificationServiceExtension { }
    

• For Objective-C projects:

  • Add an import: @import IterableAppExtensions;.

  • Configure the class so that it's similar to the following:

    // File: NotificationService.m
    #import "NotificationService.h"
    
    @import IterableAppExtensions;
    
    @interface NotificationService ()
    
    @property (nonatomic, strong) ITBNotificationServiceExtension *baseExtension;
    @end
    
    @implementation NotificationService
    - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
        self.baseExtension = [[ITBNotificationServiceExtension alloc] init];
        [self.baseExtension didReceiveNotificationRequest:request withContentHandler:contentHandler];
    }
    
    - (void)serviceExtensionTimeWillExpire {
        [self.baseExtension serviceExtensionTimeWillExpire];
    }
    @end
    

# 4. Import IterableSDK wherever necessary

To use Iterable's iOS SDK in your app's code, import it at the top of any Swift or Objective-C files that reference it. For example:

Swift

// In AppDelegate.swift and any other file where you're using IterableSDK
import IterableSDK

Objective-C

// In AppDelegate.m and any other file where you're using IterableSDK
@import IterableSDK;

# 5. Create a mobile API key

To make calls to Iterable's's API, the SDK needs a mobile API key. To learn how to create one, read API Keys

If necessary, use different API keys for debug and production builds.

# 6. Initialize the SDK with your API key

Next, you'll need to make a few updates in your app delegate's application(_:didFinishLaunchingWithOptions:) method:

# 6.1. Call IterableAPI.initialize

Call initialize(apiKey:launchOptions:config:), passing your Iterable API key as a parameter:

Swift

let config = IterableConfig()
IterableAPI.initialize(apiKey: "<YOUR_API_KEY>", launchOptions: launchOptions, config: config)

Objective-C

IterableConfig *config = [[IterableConfig alloc] init];
[IterableAPI initializeWithApiKey:@"<YOUR_API_KEY>" launchOptions:launchOptions config:config]

IterableConfig provides configuration and customization options for the Iterable SDK. You'll use it later to set up push notifications and in-app messages.

# 6.2. Set the allowedProtocols field

Starting with version 6.4.0 of Iterable's iOS SDK, you'll need to declare the specific URL protocols that the SDK can expect to see on incoming links (and that it should handle as needed). This prevents the SDK from opening links that use unexpected URL protocols.

To do this, set the allowedProtocols field (on the IterableConfig object you pass to the SDK's initialize method) to an array that contains the protocols you'd like the SDK to support.

For example, this code allows the SDK to handle http://, tel://, and custom:// links:

Swift

let config = IterableConfig()
config.allowedProtocols = ["http", "tel", "custom"]
IterableAPI.initialize(apiKey: "<YOUR_API_KEY>", launchOptions: launchOptions, config: config)

Objective-C

IterableConfig *config = [[IterableConfig alloc] init];
config allowedProtocols = @["http", "tel", "custom"];
[IterableAPI initializeWithApiKey:@"<YOUR_API_KEY>" launchOptions:launchOptions config:config]

# 6.3. Set up a push integration

In Iterable, you'll create logical mobile apps to store information about your real mobile apps—including information about the configuration parameters Iterable needs to send push notifications to them. Iterable refers to these push notification configuration parameters as push integrations.

By default, the SDK expects your push integration's name to match your app's bundle ID. However, if your Iterable push integration was created before August 2019, it may have a custom name. To handle this, do one of the following things:

• In Iterable, assign the existing push integration to a mobile app. If you do this, the SDK will use the push integration that matches your mobile app's bundle ID.

• Alternatively, specify the custom push integration name when initializing the SDK:

  Swift

  let config = IterableConfig()
  config.pushIntegrationName = "<PUSH_INTEGRATION_NAME>"
  IterableAPI.initialize(apiKey: "<YOUR_API_KEY>", launchOptions: launchOptions, config: config)
  

  Objective-C

  IterableConfig *config = [[IterableConfig alloc] init];
  config.pushIntegrationName = @"<PUSH_INTEGRATION_NAME>";
  [IterableAPI initializeWithApiKey:@"<YOUR_API_KEY>" launchOptions:launchOptions config:config]
  

  TIP

  To find the name of your Iterable push integration, navigate in Iterable to Settings > Mobile Apps, open the mobile app that's associated with your actual app, look at the Push section, and find the Name column for the relevant push integration.

  

# 6.4. Enable your JWT-enabled API key

If you're using a JWT-Enabled API Key, you'll also need to implement the auth token requested callback. This callback should fetch (from your server) a valid JWT (for the current user) and provide it to the SDK:

The examples below are based on extending your AppDelegate to implement the IterableAuthDelegate, and assume that the SDK is initialized within.

Swift

extension AppDelegate: IterableAuthDelegate {
    func onAuthTokenRequested(completion: @escaping AuthTokenRetrievalHandler) {
        // insert your implementation here:
        var token = customCustomerImplementation.getTokenFromBackend()

        // ...

        completion(token)
    }
}

let config = IterableConfig()
config.authDelegate = self

IterableAPI.initialize(apiKey: "<YOUR_API_KEY>", launchOptions: launchOptions, config: config)

Objective-C

// AppDelegate.h
@import IterableSDK;

@interface AppDelegate : UIResponder <UIApplicationDelegate, IterableAuthDelegate>
@end

// AppDelegate.m
#import "AppDelegate.h"

@implementation AppDelegate
- (void)onAuthTokenRequestedWithCompletion:(void (^ _Nonnull)(NSString * _Nullable))completion {
   // insert your implementation here:
   String *token = [customCustomerImplementation getTokenFromBackend];

   // ...

   completion(token);
}
@end

To make requests to Iterable's API using a JWT-enabled API key, you should first fetch a valid JWT for your app's current user from your own server, which must generate it. onAuthTokenRequested provides this JWT to Iterable's iOS SDK, which can then append the JWT to subsequent API requests. The SDK automatically calls onAuthTokenRequested at various times:

• When your app sets the user's email or user ID.
• When your app updates the user's email.
• Before the current JWT expires (at a configurable interval set by expiringAuthTokenRefreshPeriod, in seconds, on IterableConfig).
• When your app receives a 401 response from Iterable's API with a InvalidJwtPayload error code. (however, if the SDK receives a second consecutive 401 with an InvalidJwtPayload error when it makes a request with the new token, it won't call the authHandler again until you call setEmail or setUserId.

# 7. Enable push notifications

To enable push notifications, follow the steps described below.

# 7.1. Set up iOS push notifications in Iterable

Follow the instructions in Iterable's Setting up iOS Push Notifications guide. This document describes how to configure your iOS app's App ID to use push notifications, and how to set up a mobile app (and associated push integration) in Iterable's web app.

# 7.2. Add the Push Notifications capability to your app

Follow Apple's instructions to add the Push Notifications capability to your app.

If you'll be sending Time Sensitive push notifications (introduced in iOS 15), also add the Time Sensitive Notifications capability. For more information about Time Sensitive notifications, check out this WWDC 2021 talk.

# 7.3. Enable the Remote Notifications background mode

Follow Apple's instructions to enable the Remote Notifications background mode in your app.

# 7.4. Fetch a device token from Apple and register it with Iterable

For Iterable to send push notifications to an iOS device, it must know the unique token assigned to that device by Apple.

By default, Iterable's SDK automatically fetches this token from Apple when the application's code sets IterableAPI.email or IterableAPI.userId (which also disables the device token for the previous email or userId, preventing Iterable from sending push notifications to that user on that device). To fetch the token, the SDK calls registerForRemoteNotifications() on UIApplication.

After fetching a device token, iOS passes it to the application(_:didRegisterForRemoteNotificationsWithDeviceToken:) method on the app delegate. Configure this method to register the token with Iterable's SDK, which saves it the user's Iterable profile:

Swift

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    IterableAPI.register(token: deviceToken)
}

Objective-C

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [IterableAPI registerToken:deviceToken];
}

# 7.5. Handle incoming push notifications and enable push notification tracking

To handle incoming push notifications, and to allow Iterable to track events when a user interacts with push notifications, follow these steps:

1. For some object in your app, conform to the UNUserNotificationCenterDelegate protocol (apps commonly use the app delegate for this purpose). Import the UserNotifications framework, indicate that the class conforms to the protocol, and implement these methods:

   • userNotificationCenter(_:willPresent:withCompletionHandler:)

     This method can be used to allow your app to display incoming push notifications when it is in the foreground.

   • userNotificationCenter(_:didReceive:withCompletionHandler:)

     iOS calls this method when a user interacts with a push notification. From here, Iterable's SDK can create events associated with these interactions.

2. Set this object as the delegate for the current UNUserNotificationCenter.

For example, Iterable's Swift and Objective-C sample projects have app delegate code similar to the following:

Swift

class AppDelegate: UIResponder, UIApplicationDelegate {
    // ...
    private func setupNotifications() {
        UNUserNotificationCenter.current().delegate = self
        // ...
    }
    // ...
}

extension AppDelegate: UNUserNotificationCenterDelegate {
    public func userNotificationCenter(_: UNUserNotificationCenter, willPresent _: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        completionHandler([.badge, .banner, .list, .sound])
    }

    public func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
        IterableAppIntegration.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
    }
}

Objective-C

@implementation AppDelegate

// In its .h file, the AppDelegate class declares that it conforms to UNUserNotificationCenterDelegate

#pragma mark - UNUserNotificationCenterDelegate
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionBanner | UNNotificationPresentationOptionList | UNNotificationPresentationOptionSound);
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    [IterableAppIntegration userNotificationCenter:center didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
}

// ...
#pragma mark - private
- (void)setupNotifications {
    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    center.delegate = self;
    // ...
}
@end

# 7.6. (Optional) Request authorization to display push notifications

iOS apps must have explicit user permission to display push notification alerts, play push notification sounds or update icon badges based on push notifications.

To request this permission, display a prompt by calling the requestAuthorization(options:completionHandler:) method on UNUserNotificationCenter. This is usually done from somewhere in the app delegate. For example:

Swift

UNUserNotificationCenter.current().requestAuthorization(options:[.alert, .badge, .sound]) { (success, error) in
    if success == true {
        // ...
    }
}

Objective-C

[[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionBadge | UNAuthorizationOptionSound) completionHandler:^(BOOL granted, NSError * _Nullable error) {
    if (granted) {
        dispatch_async(dispatch_get_main_queue(), ^{
            // ...
        });
    } 
}];

# 8. Enable in-app messages

To enable in-app messages, follow these steps:

1. Enable push notifications.

   Iterable uses silent push notifications to notify an app about new in-app messages awaiting delivery. Because of this, enable push notifications even if you don't plan to send push notification campaigns.

2. Let Iterable's SDK know when the app receives a push notification. This way, it knows to go fetch waiting in-app messages.

   To do this, implement the app delegate's application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method. In it, call the identically named method on IterableAppIntegration. For example:

   Swift

   func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
       IterableAppIntegration.application(application, didReceiveRemoteNotification: userInfo, fetchCompletionHandler: completionHandler)
   }
   

   Objective-C

   - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
       [IterableAppIntegration application:application didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
   }
   

# 9. Verify that the SDK can communicate with Iterable

To test that your app can communicate with Iterable:

1. In your app's code, after initializing the SDK with your API key, set IterableAPI.email to a specific email address:

   Swift

   let config = IterableConfig()
   IterableAPI.initialize(apiKey: "<YOUR_API_KEY>", launchOptions: launchOptions, config: config)
   IterableAPI.email = "docs@iterable.com"
   

   Objective-C

   IterableConfig *config = [[IterableConfig alloc] init];
   [IterableAPI initializeWithApiKey:@"<YOUR_API_KEY>" launchOptions:launchOptions config:config]
   IterableAPI.email = @"docs@iterable.com";
   

2. Run the app on a physical device (not the simulator).

   Registering for a push notification token from Apple can only be done on a physical device.

3. Check to make sure the new user is visible in Iterable:

   • Open the Iterable project associated with the API key used in your app's code.

   • Navigate to Audience > Contact Lookup.

   • Enter the email address used above and click Search Users.

   • The user's profile should appear.

If you're having trouble, make sure that you have:

• Added the push notification capability to your app
• Enabled the remote notifications background mode

# Upgrading the SDK

This section describes how to upgrade from earlier versions of Iterable's iOS SDK.

# Upgrading to 6.4.0+

Starting with version 6.4.0 of Iterable's iOS SDK, you'll need to declare the URL protocols that the SDK should expect to see on incoming links (and then handle as needed). For more information, read Set the allowedProtocols field.

# Upgrading from a version prior to 6.1.0

• Versions 6.1.0+ of the SDK require Xcode 10.2 or higher.

• In-app messages

  • spawnInAppNotification

    The spawnInAppNotification method is no longer needed, and will fail to compile. The SDK now displays in-app messages automatically. There is no need to poll the server for new messages.

  • Handling manually

    To manually control when in-app messages display, set IterableConfig.inAppDelegate (an IterableInAppDelegate object). From its onNew method, return .skip.

    To get the queue of available in-app messages, call IterableApi.inAppManager.getMessages(). Then, call IterableApi.inAppManager.show(message) to show a specific message.

  • Custom actions

    The SDK now reserves the iterable:// URL scheme for Iterable-defined actions handled by the SDK, and the action:// URL scheme for custom actions handled by the mobile application's custom action handler.

    If you are currently using the itbl:// URL scheme for custom actions, the SDK will still pass these actions to the custom action handler. However, support for this URL scheme will eventually be removed (timeline TBD), so it is best to move to the action:// URL scheme as you can.

• Consolidated deep link URL handling

  By default, the SDK handles deep links using the URL delegate assigned to IterableConfig.

# Further reading

• Identifying the User
• Updating User Profiles
• Tracking Events with Iterable's Mobile SDKs
• Setting up iOS Push Notifications
• Advanced iOS Push Notifications
• In-App Messages on iOS
• Setting up Mobile Inbox on iOS
• Customizing Mobile Inbox on iOS
• iOS Universal Links
• Deep Links in Push Notifications
• Sample apps that use Iterable's iOS SDK
• Sending Domains, Tracking Domains and Deep Links.
• JWT-Enabled API Keys