Integrate the iOS SDK

You can integrate the MobilePush SDK into your iOS app to enable push notifications and user engagement features.

There are three ways to implement the SDK:

To add the SDK as a dependency in your app’s Podfile, add the pod to your Xcode project. See Using CocoaPods: Adding Pods to an Xcode project.

Next, open the .xcworkspace created by the install process using Xcode and start using the SDK.

Don’t open .xcodeproj directly. Opening a project file instead of a workspace can lead to errors.

Starting with version 8.0.0 of the MobilePush SDK, you can implement the SDK using Swift Package Manager (SPM).

  1. In your Xcode project, go to the Package Dependencies tab of your project’s settings.

    The Xcode project settings page with the Package Dependencies tab highlighted

  2. Add a package by clicking the plus sign (+).

  3. Search for the package MarketingCloudSDK using the url https://github.com/salesforce-marketingcloud/MarketingCloudSDK-iOS.git

    The Swift Package Manager screen with the marketingcloudsdk-ios package highlighted

  4. Select the package to include it in your app.

    A list of package products in Swift Package Manager for the marketingcloudsdk-ios package

For information about migrating from older versions of the SDK to version 8, see Migrate to the Next-Gen MobilePush SDK for iOS.

To implement the SDK manually, complete these steps.

  1. Download the SDKs MarketingCloudSDK and SFMCSDK.

  2. Copy the MarketingCloudSDK.xcframework and SFMCSDK.xcframework directories from your downloads folder to your project directory.

    A file manager, showing the MarketingCloudSDK.xcframework and SFMCSDK.xcframework directories selected

  3. Open your application project and select the appropriate target.

    An Xcode project, showing a target selected

  4. Add MarketingCloudSDK.xcframework and SFMCSDK.xcframework to Frameworks, Libraries, and Embedded Content in your target’s General settings.

    The target’s General settings, showing the MarketingCloudSDK.xcframework and SFMCSDK.xcframework added to the Frameworks, Libraries, and Embedded Content section

  5. Add MarketingCloudSDK.bundle to Copy Bundle Resources in your target’s Build Phases settings.

    The Build Phases settings, showing the MarketingCloudSDK.bundle added to the Copy Bundle Resources section

  6. Add -ObjC to your target’s Other Linker Flags build settings.

    The Build Settings tab, showing the -ObjC option added to the Other Linker Flags section

For reference documentation on SDK configuration methods, refer to these links:

The configuration example in this section uses the MarketingCloudSDK ConfigBuilder configuration method, as it’s the most flexible means to support your application’s usage of the MobilePush SDK.

Configuring the SDK using a JSON file is deprecated. Move existing implementations to the builder method. For more information about configuration methods, see the MarketingCloudSDKConfigBuilder reference for SDK version 7 and later, and the PushConfigBuilder reference for SDK versions 8 and later.

All method names contain the prefix sfmc_. This convention allows the application implementing the SDK to avoid namespace collisions between the external libraries it uses. The MarketingCloudSDK doesn’t cause compile, link, or runtime collisions with other code your application implements. For more information, see Apple Developer Documentation: Customizing Existing Classes.

Configure the SDK in your application using the Access Token, App ID, App Endpoint, and MID values noted when you Retrieve Required SDK Configuration Data.

If your app uses version 8 of the SDK, use this code.

If your app uses version 7 of the SDK, use this code.

Enable or disable analytics, location, or inbox entries depending on the application’s needs and your usage of Marketing Cloud Engagement.

iOS Data Protection affects the SDK as described in this table.

iOS Data Protection LevelSDK Behavior
No protectionSDK works in the foreground and background
Complete until first user authenticationSDK works in the foreground and background after first unlock
Complete unless openSDK works in the foreground and background after first unlock
CompleteSDK works only in the foreground after the device is unlocked

Before you enable push notifications, provision your app for push notifications.

  1. Enable push notifications in your target’s Capabilities settings.

  2. Set your AppDelegate class to adhere to the UIApplicationDelegate and UNUserNotificationCenterDelegate protocol.

  3. Extend the SDK configuration code outlined in Configure the SDK to add support for push registration. This code example shows how to configure the version 9 and later of the SDK for iOS apps.

    If your app uses version 10 of the SDK, use this code.

    If your app uses version 8 of the SDK, use this code.

    This code example shows how to configure the version 7 of the SDK for iOS apps.

  4. Add the required UIApplicationDelegate protocol methods to support push registration to your AppDelegate class. This code example shows how to configure the version 8 and later of the SDK for iOS apps.

    If your app uses version 10 of the SDK, use this code.

    If your app uses version 8 of the SDK, use this code.

    This code example shows how to configure the version 7 and earlier of the SDK for iOS apps.

  5. Add the required UNUserNotificationCenterDelegate protocol methods to support push notifications to your AppDelegate class.

    If your app uses version 10 of the SDK, use this code.

    If your app uses version 9 of the SDK, use this code.

    If your app uses version 8 of the SDK, use this code.

    If your app uses version 7 of the SDK, use this code.

    The methods described in this procedure use MarketingCloud SDK APIs to facilitate the framework’s functionality to manage push notifications, which include contact registration and push analytics tracking. If you implement the methods without using the MarketingCloud SDK methods, these features don’t work as expected.