Start tracking your progress
Trailhead Home
Trailhead Home

Add Mobile SDK to an Existing Project

Learning Objectives

After completing this unit, you'll be able to:

  • Use CocoaPods to add.Mobile SDK to an existing native iOS app.
  • Use CocoaPods to update an existing Mobile SDK app for native iOS.
  • Understand how Mobile SDK pods depend on each other.

Using CocoaPods with Mobile SDK

If you have existing iOS apps that you’re upgrading with Mobile SDK, this unit can help you use CocoaPods to merge your existing modules with Mobile SDK modules. To get started with CocoaPods, see


CocoaPods is a third-party open-source dependency manager. It’s supported by Mobile SDK and required by forceios, but it is not required for Mobile SDK development on iOS. See “Resources” at the end of this page for a link to manual project instructions.

In Mobile SDK 4.0 and later, forceios uses CocoaPods to create projects. Developers can also use CocoaPods manually to add Mobile SDK to existing iOS apps.

Mobile SDK provides CocoaPods pod specifications, or podspecs, for each Mobile SDK module.

  • SalesforceSDKCore—Implements OAuth, passcodes, networking, and REST APIs. All other pods depend on this pod, either directly or indirectly.
  • SmartStore—Implements secure offline storage. Depends on SalesforceSDKCore.
  • Mobile Sync—Implements offline synchronization. Depends on SmartStore.
  • SalesforceAnalytics—Implements a reporting mechanism that sends Salesforce anonymous statistics on Mobile SDK feature usage and popularity.
  • SalesforceSDKCommon—Utilities shared throughout the SDK.
The following chart shows the dependencies between specs. In this chart, the arrows point from the dependent specs to their dependencies.
SalesforceMobileSDK-iOS.podspec subspec dependencies
If you declare a pod, you automatically get everything in that pod’s dependency chain. For example, by declaring a pod for Mobile Sync, you automatically get the SmartStore and SalesforceSDKCore pods. This shortcut applies only to production pods.

To use CocoaPods with the current Mobile SDK release, follow these steps.

  1. Be sure you’ve installed the cocoapods Ruby gem as described at Mobile SDK 8.1 accepts pod versions 1.7.2 to 1.8.
  2. In your project's Podfile, add the SalesforceMobileSDK-iOS-Specs repo as a source. Make sure that you put this entry first, before the CocoaPods source path.
    target 'YourAppName' do
    source '' # needs to be first 
    source ''
  3. Reference the Mobile SDK podspec that you intend to merge into your app. For example, to add OAuth and passcode modules to your app, declare the SalesforceSDKCore pod in your Podfile. For example:
    target 'YourAppName' do
    source '' # needs to be first 
    source ''
    pod 'SalesforceSDKCore'
    This pod configuration is the minimum for a Mobile SDK app.
  4. To add other modules, replace SalesforceSDKCore with a different pod declaration. For example, to use Mobile Sync:
    target 'YourAppName' do
    source '' # needs to be first 
    source ''
    pod 'MobileSync'
    Since the MobileSync pod depends on SmartStore and SalesforceSDKCore, you don’t need to declare those pods explicitly.
  5. (Alternate method) To work with the upcoming release of Mobile SDK, you clone the SalesforceMobileSDK-iOS repo, check out the dev branch, and then pull resources from it. In this case, you must declare each pre-release dependency explicitly so you can indicate its repo path. If you omit a dependency declaration, CocoaPods loads its production version.
    1. Clone locally at the desired commit.
    2. At the Terminal window, run git checkout dev to switch to the development branch.
    3. Run ./ in the root directory of your clone.
    4. To each pod call in your Podfile, add a :path parameter that points to your clone.
    Here's the previous example repurposed to pull resources from a local clone:
    target 'YourAppName' do
    source '' # need to be first 
    source ''
    # Specify each pre-release pod 
    pod 'SalesforceSDKCore', :path => '/<path-to-clone-of>/SalesforceMobileSDK-iOS/'
    pod 'SalesforceAnalytics', :path => '/<path-to-clone-of>/SalesforceMobileSDK-iOS/'
    pod 'SmartStore', :path => '/<path-to-clone-of>/SalesforceMobileSDK-iOS/'
    pod 'MobileSync', :path => '/<path-to-clone-of>/SalesforceMobileSDK-iOS/'
  6. In a Terminal window, run pod install from your project directory. CocoaPods downloads the dependencies for your requested pods, merges them into your project, and creates a workspace containing the newly merged project.


    After running CocoaPods, always access your project only from the workspace that pod install creates. For example, instead of opening MyProject.xcodeproj, open MyProject.xcworkspace.

  7. To use Mobile SDK APIs in your merged app, remember these important tips.
    1. In Objective-C apps, import header files using angle brackets (“<” and “>”) rather than double quotes. For example:
      #import <SalesforceSDKCore/SFRestAPI.h>