Iterable's iOS SDK

This document describes how to set up and test the Iterable iOS SDK. You can add the SDK via Cocoapods, Carthage, direct import of the libraries, and, as of version 6.2.0, through the Swift Package Manager. They should all have the same result.

# Table of contents

# CocoaPods

To use CocoaPods to install Iterable's iOS SDK, first install CocoaPods.

sudo gem install cocoapods

Then, follow these steps:

1. 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 the following command:

     pod init
     

2. Edit your project's Podfile.

   • Add the Iterable-iOS-SDK pod to your project's app target.

   • If your app will receive push notifications containing media attachments (images, etc.), add the Iterable-iOS-AppExtensions pod to your project's Notification Service Extension target.

   

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

   platform :ios, '11.0'
   
   use_frameworks!
   
   target 'swift-sample-app' do
       pod 'Iterable-iOS-SDK'
   end
   
   target 'swift-sample-app-notification-extension' do
       pod 'Iterable-iOS-AppExtensions'
   end
   

   You must include use_frameworks! in your Podfile, no matter if your app is based on Swift or Objective-C. If your project cannot use this option, install the SDK manually.

3. In the terminal, run the following command to install the SDK (and app extensions, if necessary):

   pod install
   

   This will create an .xcworkspace file. To open your project in Xcode, use this file instead of the .xcodeproj file.

For more information, take a look at the CocoaPods documentation.

# Carthage

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

1. If it does not yet exist, create a file named Cartfile in the same directory as your Xcode project.

2. Edit Cartfile, adding the following line:

   github "Iterable/swift-sdk" 
   

3. In the terminal, in the same directory as your Cartfile, run the following command:

   carthage update
   

4. In Xcode, navigate to the Build Phases section for your app's target. Click the + icon and select New Run Script Phase. A Run Script section will appear.

5. In the Run Script section, below the Shell input, add the following command:

   /usr/local/bin/carthage copy-frameworks
   

6. In the Input Files section, click + and add the following path:

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

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

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

8. Add <Xcode project directory>/Carthage/Build/iOS/IterableSDK.framework to your Xcode project by dragging it into the Xcode Project Navigator. When prompted by Xcode, add the framework to your app's target.

9. If your app will be using push notifications that contain media attachments (images, etc.), repeat steps 6 through 8, substituting IterableAppExtensions.framework for IterableSDK.framework. In step 8, add IterableAppExtensions.framework to your project's Notification Service Extension target (instead of the app target).

For more information, take a look at the Carthage documentation.

# Installing manually

Attached to the release, you will find two framework bundles: IterableSDK.framework and IterableAppExtensions.framework.

1. In Xcode, choose the target for your app. Now, add the IterableSDK.framework to the Embedded Binaries section. If you want to use an Iterable Rich Notification Extension, you will have to add IterableAppExtensions.framework to the embedded binaries section as well.

   

2. If you want to use an Iterable Rich Notifiation Extension, you will need to add IterableAppExtension.framework to Linked Frameworks and Libraries section of your app extension target (not app target). Please note that you will have to add the IterableAppExtension.framework bundle to both the app target (step 1) and app extension target (step 2) of your project. In the app target, it goes in the Embedded Binaries section and in app extension target it goes in the Linked Frameworks and Libraries section.

   

3. In build settings, set Always Embed Swift Standard Libraries setting to Yes. This is necessary for both Swift and Objective-C projects.

# Swift Package Manager

In Xcode 11, Apple integrated the Swift Package Manager into Xcode—an intuitive, easy way to add dependencies to your project.

1. To include Iterable's SDK, navigate in Xcode to File > Swift Packages > Add Package Dependency.

2. Enter https://github.com/iterable/swift-sdk as the package repository URL.

3. Select the version of the SDK you'd like to install (the default settings will be set to the latest stable version).

4. Select IterableSDK. If necessary for your use case, also select IterableAppExtensions.

5. Click Finish.

# Initializing

After adding the SDK to the app, initialize it:

• Import the IterableSDK module
• Set the API and Configuring the SDK Initialize

# 1. Import the IterableSDK module

To use the IterableSDK module, import it at the top of your Objective-C or Swift files:

Swift

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

Objective-C

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

# 2. Create mobile API Key

Go to Integrations > API Keys and create a mobile specific API for your app, as shown below:

Screenshot of selection choice.

# 3. Set the API and initialize the SDK

In the application:didFinishLaunchingWithOptions: method of your app delegate, call initialize(apiKey:launchOptions:config:), passing in your Iterable API key:

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]

# 4. Add code to your app delegate

We will cover this code in more detail in each section later but for now, please add this code to your AppDelegate file.

# Code for push notifications

Swift

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

Objective-C

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

# Code for push tracking

From this method, call the userNotificationCenter(_:didReceive:withCompletionHandler:) method on IterableAppIntegration. This tracks a push open event and performs the associated action.

Swift

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

Objective-C

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

# Code for in-app messages

In-app messages are handled via silent push messages from the server. When your application receives a silent push, call the Iterable iOS SDK in your app delegate, as follows:

Swift

// In AppDelegate.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];
}

Turn on Remote Notifications under Signing and Capabilities in Your Xcode Target.

# 5. Create a test user

Register a test email right after the config file and you should now see a test user within the Contact Lookup section of the platform.

Swift

IterableAPI.email = "test@test.com"
IterableAPI.updateUser(["init_test": "test"], mergeNestedObjects: false)

Objective-C

IterableAPI.email = @"test@test.com";

Go to Iterable, select Audiences > Segmentation and click refresh to see your test user!

If you do not see your test user, read Testing and Troubleshooting the Iterable SDK.

# Next steps

After the SDK has been installed, read about Identifying the User.