setup-ios.md

iOS Setup

Once you've acquired the CodePush plugin, you need to integrate it into the Xcode project of your React Native app and configure it correctly. To do this, take the following steps:

Plugin Installation (iOS)

In order to accommodate as many developer preferences as possible, the CodePush plugin supports iOS installation via three mechanisms:

1. RNPM - React Native Package Manager (RNPM) is an awesome tool that provides the simplest installation experience possible for React Native plugins. If you're already using it, or you want to use it, then we recommend this approach.

2. CocoaPods - If you're building a native iOS app that is embedding React Native into it, or you simply prefer using CocoaPods, then we recommend using the Podspec file that we ship as part of our plugin.

3. "Manual" - If you don't want to depend on any additional tools or are fine with a few extra installation steps (it's a one-time thing), then go with this approach.

Plugin Installation (iOS - RNPM)

1. As of v0.27 of React Native, rnpm link has already been merged into the React Native CLI. Simply run:

   react-native link react-native-code-push
   

   If your app uses a version of React Native that is lower than v0.27, run the following:

   rnpm link react-native-code-push
   

   Note: If you don't already have RNPM installed, you can do so by simply running npm i -g rnpm and then executing the above command. If you already have RNPM installed, make sure you have v1.9.0+ in order to benefit from this one step install.

2. You will be prompted for the deployment key you'd like to use. If you don't already have it, you can retrieve this value by running code-push deployment ls <appName> -k, or you can choose to ignore it (by simply hitting <ENTER>) and add it in later. To get started, we would recommend just using your Staging deployment key, so that you can test out the CodePush end-to-end.

And that's it! Isn't RNPM awesome? :)

Plugin Installation (iOS - CocoaPods)

1. Add the CodePush plugin dependency to your Podfile, pointing at the path where NPM installed it

   pod 'CodePush', :path => '../node_modules/react-native-code-push'

   CodePush depends on an internal copy of the SSZipArchive library, so if your project already includes it (either directly or via a transitive dependency), then you can install a version of CodePush which excludes it by depending specifically on the Core subspec:

   pod 'CodePush', :path => '../node_modules/react-native-code-push', :subspecs => ['Core']

   NOTE: The above paths needs to be relative to your app's Podfile, so adjust it as nec cessary.

2. Run pod install

NOTE: The CodePush .podspec depends on the React pod, and so in order to ensure that it can correctly use the version of React Native that your app is built with, please make sure to define the React dependency in your app's Podfile as explained here.

Plugin Installation (iOS - Manual)

1. Open your app's Xcode project

2. Find the CodePush.xcodeproj file within the node_modules/react-native-code-push/ios directory (or node_modules/react-native-code-push for <=1.7.3-beta installations) and drag it into the Libraries node in Xcode

   

3. Select the project node in Xcode and select the "Build Phases" tab of your project configuration.

4. Drag libCodePush.a from Libraries/CodePush.xcodeproj/Products into the "Link Binary With Libraries" section of your project's "Build Phases" configuration.

   

5. Click the plus sign underneath the "Link Binary With Libraries" list and select the libz.tbd library underneath the iOS 9.1 node.

   

   Note: Alternatively, if you prefer, you can add the -lz flag to the Other Linker Flags field in the Linking section of the Build Settings.

Plugin Configuration (iOS)

NOTE: If you used RNPM or react-native link to automatically link the plugin, these steps have already been done for you so you may skip this section.

Once your Xcode project has been setup to build/link the CodePush plugin, you need to configure your app to consult CodePush for the location of your JS bundle, since it is responsible for synchronizing it with updates that are released to the CodePush server. To do this, perform the following steps:

1. Open up the AppDelegate.m file, and add an import statement for the CodePush headers:

   #import <CodePush/CodePush.h>

2. Find the following line of code, which loads your JS Bundle from the app binary for production releases:

   jsCodeLocation = [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];

3. Replace it with this line:

   jsCodeLocation = [CodePush bundleURL];

This change configures your app to always load the most recent version of your app's JS bundle. On the first launch, this will correspond to the file that was compiled with the app. However, after an update has been pushed via CodePush, this will return the location of the most recently installed update.

NOTE: The bundleURL method assumes your app's JS bundle is named main.jsbundle. If you have configured your app to use a different file name, simply call the bundleURLForResource: method (which assumes you're using the .jsbundle extension) or bundleURLForResource:withExtension: method instead, in order to overwrite that default behavior

Typically, you're only going to want to use CodePush to resolve your JS bundle location within release builds, and therefore, we recommend using the DEBUG pre-processor macro to dynamically switch between using the packager server and CodePush, depending on whether you are debugging or not. This will make it much simpler to ensure you get the right behavior you want in production, while still being able to use the Chrome Dev Tools, live reload, etc. at debug-time.

NSURL *jsCodeLocation;

#ifdef DEBUG
    jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.ios.bundle?platform=ios&dev=true"];
#else
    jsCodeLocation = [CodePush bundleURL];
#endif

To let the CodePush runtime know which deployment it should query for updates against, open your app's Info.plist file and add a new entry named CodePushDeploymentKey, whose value is the key of the deployment you want to configure this app against (e.g. the key for the Staging deployment for the FooBar app). You can retrieve this value by running code-push deployment ls <appName> -k in the CodePush CLI (the -k flag is necessary since keys aren't displayed by default) and copying the value of the Deployment Key column which corresponds to the deployment you want to use (see below). Note that using the deployment's name (e.g. Staging) will not work. That "friendly name" is intended only for authenticated management usage from the CLI, and not for public consumption within your app.

In order to effectively make use of the Staging and Production deployments that were created along with your CodePush app, refer to the multi-deployment testing docs below before actually moving your app's usage of CodePush into production.

HTTP exception domains configuration (iOS)

CodePush plugin makes HTTPS requests to the following domains:

• codepush.azurewebsites.net
• codepush.blob.core.windows.net
• codepushupdates.azureedge.net

If you want to change the default HTTP security configuration for any of these domains, you have to define the NSAppTransportSecurity (ATS) configuration inside your Info.plist file:

<plist version="1.0">
  <dict>
    <!-- ...other configs... -->

    <key>NSAppTransportSecurity</key>
    <dict>
      <key>NSExceptionDomains</key>
      <dict>
        <key>codepush.azurewebsites.net</key>
        <dict><!-- read the ATS Apple Docs for available options --></dict>
      </dict>
    </dict>

    <!-- ...other configs... -->
  </dict>
</plist>

Before doing anything, please read the docs first.