trailhead

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 merge your existing modules with Mobile SDK modules.

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.
  • SmartSync Data Framework—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 SmartSync Data Framework, 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 www.cocoapods.org. Mobile SDK 7.0 accepts pod versions 1.2 to 1.6.
  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 'https://github.com/forcedotcom/SalesforceMobileSDK-iOS-Specs.git' # needs to be first 
    source 'https://github.com/CocoaPods/Specs.git'
    ...
  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 'https://github.com/forcedotcom/SalesforceMobileSDK-iOS-Specs.git' # needs to be first 
    source 'https://github.com/CocoaPods/Specs.git'
    
    pod 'SalesforceSDKCore'
    
    end
    
    This pod configuration is the minimum for a Mobile SDK app. Note that SalesforceSDKCore implicitly includes the third-party SqlCipher pod.
  4. To add other modules, replace SalesforceSDKCore with a different pod declaration. For example, to use SmartSync Data Framework:
    target 'YourAppName' do
    source 'https://github.com/forcedotcom/SalesforceMobileSDK-iOS-Specs.git' # needs to be first 
    source 'https://github.com/CocoaPods/Specs.git'
    
    pod 'SmartSync'
    
    end
    Since the SmartSync 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 github.com/forcedotcom/SalesforceMobileSDK-iOS locally at the desired commit.
    2. At the Terminal window, run git checkout dev to switch to the development branch.
    3. Run ./install.sh 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 'https://github.com/forcedotcom/SalesforceMobileSDK-iOS-Specs.git' # need to be first 
    source 'https://github.com/CocoaPods/Specs.git'
    
    # 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 'SmartSync', :path => '/<path-to-clone-of>/SalesforceMobileSDK-iOS/'
    
    end
  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.
    Important

    Important

    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 Swift apps, be sure to specify use_frameworks! in your Podfile.
    2. In Swift source files, remember to import modules instead of header files. For example:
      import SalesforceSDKCore
retargeting