Appcircle React Native CodePush SDK

Table of Contents

1. Overview
2. Features
3. Installation
4. Platform Setup
   • iOS Setup
   • Android Setup
5. Basic Usage
6. Releasing Updates
   • Manual Release
   • Automated Release
7. Multi-Deployment Testing
8. Code Signing

Overview

Appcircle React Native CodePush SDK enables you to deploy mobile app updates directly to your users' devices through Appcircle's CI/CD platform. This integration allows you to automate your deployment process and manage your app updates efficiently.

Features

• Appcircle Integration: Seamless integration with Appcircle CI/CD platform
• Automated Deployments: Automatic deployment of updates through Appcircle workflows
• Instant Updates: Deploy updates to your users' devices instantly
• Rollback Support: Automatically rollback to previous versions if issues occur
• Differential Updates: Only download the files that have changed
• Multi-Platform Support: Works with iOS, Android, and Windows
• TypeScript Support: Full TypeScript definitions included

Installation

Run the following command to add the Appcircle CodePush SDK to your project.

npm install @appcircle/react-native-code-push

Supported Versions

| React Native version(s) | Supporting CodePush version(s) | | --- | --- | | <v0.76 | Consider microsoft/code-push-react-native | | v0.76, v0.77, v0.78, v0.79 | v0.0.3+ (Available for Old/New Architecture) | | v0.80 | v0.0.4+ (Available for Old/New Architecture) | | v0.81+ | v0.1.0+ (Available for Old/New Architecture) | | v0.82+ | v0.1.0+ (Available for New Architecture) |

Platform Setup

iOS Setup

1. Add the following to your Podfile:

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

2. Run pod install in the iOS directory

Android Setup

1. Add the following to your android/settings.gradle:

include ':appcircle-react-native-code-push'
project(':appcircle-react-native-code-push').projectDir = new File(rootProject.projectDir, '../node_modules/@appcircle/react-native-code-push/android/app')

2. Add the following to your android/app/build.gradle:

dependencies {
    implementation project(':appcircle-react-native-code-push')
}

Basic Usage

JavaScript Integration

import codePush from "@appcircle/react-native-code-push";

// For class components
class MyApp extends Component {
  // Your component code
}
MyApp = codePush(MyApp);

// For functional components
const MyApp = () => {
  // Your component code
}
export default codePush(MyApp);

Configuration Options

let codePushOptions = { 
  checkFrequency: codePush.CheckFrequency.ON_APP_RESUME 
};

// Apply options
MyApp = codePush(codePushOptions)(MyApp);

Releasing Updates

Manual Release

Use the Appcircle CLI to release updates:

# Basic release
appcircle-code-push release-react -a <AppName>/<Deployment Name>

# Release with specific options
appcircle-code-push release-react -a <AppName>/<DeplymentName> -m --description "Update description"

The release-react command enables such a simple workflow because it provides many sensible defaults (like generating a release bundle, assuming your app's entry file on iOS is either index.ios.js or index.js). However, all of these defaults can be customized to allow incremental flexibility as necessary, which makes it a good fit for most scenarios.

Automated Release

For Appcircle CodePush release automation, please visit the Appcircle CodePush workflow step documentation.

Multi-Deployment Testing

The SDK supports multiple deployment environments through Appcircle:

• Staging: For testing updates before production
• Production: For end-user updates
• Custom Deployments: For A/B testing or specific user groups

Code Signing

The SDK supports code signing which ensures that every over‑the‑air (OTA) JavaScript bundle your React Native application receives originates from a trusted source and has not been altered in transit.

Configuration of Code Signing

Generate the key pairs. Use OpenSSL (or your preferred cryptographic toolkit) to create a 4096‑bit RSA key pair—or an ECC key with curve P‑256—store the private key securely. And then store the private key securely.

# generate private RSA key
openssl genrsa -out private_codepush_signing_key.pem
# export public key
openssl rsa -pubout -in private_codepush_signing_key.pem -out public_codepush_signing_key.pem

Setup and Installation

After generating the private and public keys locally, you must make a few configuration changes in your application. Begin by adding the generated public key to the project that you intend to sign, ensuring it is accessible at build time for signature verification.

For iOS, add the following to the Info.plist:

<key>CodePushPublicKey</key>
    <string>-----BEGIN PUBLIC KEY-----
        Here is your public key
    -----END PUBLIC KEY-----</string>

For Android, add the following to the Strings.xml:

<resources>
    <string name="app_name">my_app</string>
    <string name="CodePushPublicKey">-----BEGIN PUBLIC KEY-----
        Here is your public key
    -----END PUBLIC KEY-----</string>
</resources>

Signing CodePush Release

To create a signed CodePush release, you must first generate a build from your codebase with the public key already embedded. The resulting .ipa and .apk artifacts now contain the public key, enabling them to identify properly signed CodePush releases and safely apply OTA updates.

Once your binary is configured with the public key, you can publish a signed CodePush release through the Appcircle CodePush CLI:

appcircle-code-push release-react <YOUR_APP_PROFILE_NAME> <platform> -d <DEPLOYMENT_CHANNEL_NAME> --privateKeyPath <YOUR_PRIVATE_KEY_PATH>

Replace <YOUR_APP_PROFILE_NAME> with the CodePush Profile name shown in the Appcircle dashboard, update the -d flag as needed (e.g., Staging). The --privateKeyPath flag must reference the same private key you used to generate the public key embedded in the app; the CLI will sign the bundle before uploading it to Appcircle.

For more details, refer to the Appcircle documentation.

Contributing

This project has adopted the Microsoft Open Source Code of Conduct.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support with Appcircle integration:

• Visit Appcircle Documentation
• Contact Appcircle Support