Required Configuration Data

Before you configure the SDK during SDK setup, locate your app endpoint, access token, and app ID on your app’s administration page in MobilePush Administration.

App Endpoint (Tenant-Specific Endpoint)

New implementations: Your app must use your app’s Marketing Cloud app endpoint value as part of the SDK configuration. For JSON configuration, set this value as the marketing_cloud_server_url. For builder method, pass this value to sfmc_setMarketingCloudServerUrl().

Upgrades: If you upgrade to the SDK version released with the April 2019 release or later, update your configuration to include the app endpoint value. App endpoint is required beginning with the April 2019 release. If your app isn’t configured with an app endpoint, the SDK returns an error from the configuration method, and the SDK does not function.

Access Token

For JSON configurations, set this value as the accesstoken. For builder method, pass this value to sfmc_setAccessToken().

App ID

For JSON configurations, set this value as the appid. For builder method, pass this value to sfmc_setApplicationId().

1. Provision your app with Apple

  1. Provision your mobile app in your Apple developer account.
  2. To integrate the MarketingCloudSDK with your iOS mobile app and enable push notifications, follow Apple’s Xcode instructions.

The APNS (push) certificate issued when you provision your app is valid for one year. To keep the ability to send push notifications, renew the APNS certificate annually before it expires. To create or renew certificates, follow Apple’s Xcode instructions.

If you aren’t using Xcode’s Automatically Manage Signing, ensure that you create a provisioning profile in your Apple Developer account for your new app. These settings may vary depending on your testing and distribution needs; at a minimum, you need a valid provisioning profile to send push messages through your app.

2. Create your app in Marketing Cloud

To connect your iOS app to Marketing Cloud, create a MobilePush app in MobilePush in Marketing Cloud. This connection allows your app to use MobilePush to communicate with your users via push notifications. Marketing Cloud classifies MobilePush apps as consumer-grade applications. MobilePush apps use long-lived limited-access tokens.

Follow these steps to create a new MobilePush app:

  1. Log in to Marketing Cloud.
  2. From the Mobile Studio menu, choose MobilePush.
  3. On the Administration page, click Create New App in the upper right corner.
  4. Enter the name and description for the app.
  5. Click Choose file and upload the icon for the MobilePush app.
  6. To upload an APNS certificate, click Change and choose the certificate on your computer to upload. Enter the password for the certificate.

    To create or renew APNS (push) certificates, follow Apple’s Xcode instructions.

  7. Make any applicable changes to the optional settings.
  8. Click Save.

  9. Validate correct certificate is uploaded. The certificate should be for Push Notifications (APNS), not the signing certificate used in the creation of the APNS certificate.

    Double-check to ensure that the certificate uploaded is a current APNS (push) certificate, as they expire after 1 year.

Review MobilePush documentation for more information.

3. Implement the SDK

To implement the MarketingCloudSDK framework in your application, either use CocoaPods or manually set up the SDK.

Option 1: Implement the SDK with CocoaPods

  1. Follow the CocoaPods instructions using MarketingCloudSDK as a dependency in the podfile.
  2. Download this JSON file and add it to your application project in Xcode. You must select Copy items if needed.


  3. Open the .xcworkspace created by the install process with Xcode and start using the SDK.

    Do NOT open .xcodeproj. An error occurs if you open up a project file instead of a workspace.

Option 2: Implement the SDK manually

  1. Download the SDK.
  2. Copy the MarketingCloudSDK directory from your downloads to your project directory.

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

  4. Add MarketingCloudSDK.framework to Linked Frameworks and Libraries in your target’s General settings.

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

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

    Review additional information from Apple about this linker flag.

4. Configure the SDK

See the SDK header MarketingCloudSDK/MarketingCloudSDK+Base.h (AppleDoc) for alternate configuration methods.

Configure the MarketingCloudSDK framework via a JSON file that you add to your application. This file contains the parameters unique to your application and feature needs. The MarketingCloudSDK framework reads the values in this file and completes its configuration based on these settings.

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. MarketingCloudSDK does not cause compile, link, or runtime collisions with other code your application implements. Review Apple’s documentation on customizing existing classes for further information.

  1. Add MarketingCloudSDKConfiguration.json to Copy Bundle Resources in your target’s Build Phases settings.

  2. Change the appid and accesstoken values to match the information from your Marketing Cloud account when you configured your application. These values represent the unique pairing of this iOS application with the Marketing Cloud account used for MobilePush.
  3. Change the marketing_cloud_server_url value to match information from your Marketing Cloud account when you configured your application. This value represents the server to which the SDK will communicate.

  4. Change the mid value to match information from your Marketing Cloud account when you configured your application. Select your account name in the upper-right corner of the MobilePush Administration site and copy the “MID” value (numbers only).

  5. Enable or disable etanalytics, pianalytics, location, or inbox entries depending on the unique needs of your application and your usage of Marketing Cloud.

5. Implement Push

  1. To implement push notification handling in your application, ensure that you created an APNS Push Certificate in the Apple developer portal and added it to your Marketing Cloud account. Make sure that you added the push notifications feature to your application in the Apple developer portal. Enable push notifications in your target’s Capabilities settings.
  2. In your application delegate, import the framework header to enable MarketingCloudSDK functionality.
  3. In your application delegate class, add the following sections of code to ensure that your application registers for and handles push notifications. Set your AppDelegate class to adhere to the UNUserNotificationCenterDelegate protocol.
  4. In your application delegate method -application:didFinishLaunchingWithOptions:, create an instance of the MarketingCloudSDK and configure it for use, setting the push delegate and requesting push authorization. Only configure in didFinishingLaunching.

To configure the iOS MarketingCloudSDK, make a call to sfmc_configure. The configuration is synchronously performed and blocks the calling thread. To verify successful configuration, check both the return value and the error value. See the MarketingCloudSDK+Base.h header file for additional configuration methods.

Review the MarketingCloudSDK+Base.h header file for additional methods for configuration.

Add the required delegate methods to support push notifications to your AppDelegate class.

These methods use MarketingCloudSDK methods to enable the framework’s functionality to manage push notifications, which includes MobilePush contact registration and push analytics tracking.

If you implement the following methods without using the MarketingCloudSDK methods as shown, MobilePush functionality does not work as expected. If you don’t implement the methods below, MobilePush functionality does not work as expected.