diff --git a/android/app/src/main/java/com/microsoft/codepush/react/CodePush.java b/android/app/src/main/java/com/microsoft/codepush/react/CodePush.java index 8f3f87a9..f19a0de0 100644 --- a/android/app/src/main/java/com/microsoft/codepush/react/CodePush.java +++ b/android/app/src/main/java/com/microsoft/codepush/react/CodePush.java @@ -51,6 +51,9 @@ public static String getServiceUrl() { return mServerUrl; } + /** + * Entry point used by React Native autolinking to create and retain the package instance. + */ public static synchronized CodePush getInstance(Context context, boolean isDebugMode) { if (mCurrentInstance == null) { mCurrentInstance = new CodePush(context, isDebugMode); diff --git a/docs/api-android.md b/docs/api-android.md index 7b5e4214..08184f9c 100644 --- a/docs/api-android.md +++ b/docs/api-android.md @@ -1,72 +1,29 @@ -### Java API Reference (Android) +## Java API Reference (Android) -### API for React Native 0.60 version and above +CodePush is initialized through React Native autolinking. See the [Android setup](../README.md#android-manual-setup) for the required app integration. -Since `autolinking` uses `react-native.config.js` to link plugins, constructors are specified in that file. But you can override custom variables to manage the CodePush plugin by placing these values in string resources. +### Configuration -* __Server Url__ - used for specifying CodePush Server Url. - The Default value: "https://codepush.appcenter.ms/" is overridden by adding your path to `strings.xml` with name `CodePushServerUrl`. CodePush automatically gets this property and will use this path to send requests. For example: - ```xml - https://yourcodepush.server.com - ``` +#### Server URL -### API for React Native lower than 0.60 +To override the default server URL (`https://codepush.appcenter.ms/`), add `CodePushServerUrl` to `strings.xml`: -The Java API is made available by importing the `com.microsoft.codepush.react.CodePush` class into your `MainActivity.java` file, and consists of a single public class named `CodePush`. - -#### CodePush - -Constructs the CodePush client runtime and represents the `ReactPackage` instance that you add to you app's list of packages. - -##### Constructors - -- __CodePush(String deploymentKey, Activity mainActivity)__ - Creates a new instance of the CodePush runtime, that will be used to query the service for updates via the provided deployment key. The `mainActivity` parameter should always be set to `this` when configuring your React packages list inside the `MainActivity` class. This constructor puts the CodePush runtime into "release mode", so if you want to enable debugging behavior, use the following constructor instead. - -- __CodePush(String deploymentKey, Activity mainActivity, bool isDebugMode)__ - Equivalent to the previous constructor but allows you to specify whether you want the CodePush runtime to be in debug mode or not. When using this constructor, the `isDebugMode` parameter should always be set to `BuildConfig.DEBUG` in order to stay synchronized with your build type. When putting CodePush into debug mode, the following behaviors are enabled: - - 1. Old CodePush updates aren't deleted from storage whenever a new binary is deployed to the emulator/device. This behavior enables you to deploy new binaries, without bumping the version during development, and without continuously getting the same update every time your app calls `sync`. - - 2. The local cache that the React Native runtime maintains in debug mode is deleted whenever a CodePush update is installed. This ensures that when the app is restarted after an update is applied, you will see the expected changes. As soon as [this PR](https://github.com/facebook/react-native/pull/4738) is merged, we won't need to do this anymore. - -- __CodePush(String deploymentKey, Context context, boolean isDebugMode, String serverUrl)__ Constructor allows you to specify CodePush Server Url. The Default value: `"https://codepush.appcenter.ms/"` is overridden by value specified in `serverUrl`. - -##### Builder - -As an alternative to constructors *you can also use `CodePushBuilder`* to setup a CodePush instance configured with *only parameters you want*. - -```java - @Override - protected List getPackages() { - return Arrays.asList( - new MainReactPackage(), - new CodePushBuilder("deployment-key-here",getApplicationContext()) - .setIsDebugMode(BuildConfig.DEBUG) - .setServerUrl("https://yourcodepush.server.com") - .build() //return configured CodePush instance - ); - } +```xml +https://your-code-push-server.example.com ``` -`CodePushBuilder` methods: - -* __public CodePushBuilder(String deploymentKey, Context context)__ - setup same parameters as via __CodePush(String deploymentKey, Activity mainActivity)__ - -* __public CodePushBuilder setIsDebugMode(boolean isDebugMode)__ - allows you to specify whether you want the CodePush runtime to be in debug mode or not. Default value: `false`. - -* __public CodePushBuilder setServerUrl(String serverUrl)__ - allows you to specify CodePush Server Url. Default value: `"https://codepush.appcenter.ms/"`. - -* __public CodePush build()__ - return configured `CodePush` instance. +### Methods -##### Public Methods +- **`static CodePush getInstance(Context context, boolean isDebugMode)`** - Returns the singleton package instance used by autolinking. Applications normally do not need to call this directly. -- __setDeploymentKey(String deploymentKey)__ - Sets the deployment key that the app should use when querying for updates. This is a dynamic alternative to setting the deployment key in Codepush constructor/builder and/or specifying a deployment key in JS when calling `checkForUpdate` or `sync`. +- **`static String getJSBundleFile()`** - Returns the latest compatible JavaScript bundle, using `index.android.bundle` as the embedded bundle name. -##### Static Methods +- **`static String getJSBundleFile(String assetsBundleFileName)`** - Returns the latest compatible JavaScript bundle using the specified embedded bundle name. -- __getBundleUrl()__ - Returns the path to the most recent version of your app's JS bundle file, assuming that the resource name is `index.android.bundle`. If your app is using a different bundle name, then use the overloaded version of this method which allows specifying it. This method has the same resolution behavior as the Objective-C equivalent described above. +- **`String getPackageFolder()`** - Returns the current update folder, or `null` when no update is installed. -- __getBundleUrl(String bundleName)__ - Returns the path to the most recent version of your app's JS bundle file, using the specified resource name (like `index.android.bundle`). This method has the same resolution behavior as the Objective-C equivalent described above. +- **`static void overrideAppVersion(String appVersionOverride)`** - Overrides the binary version used for update compatibility checks. Call this before CodePush is initialized. -- __getPackageFolder()__ - Returns the path to the current update folder. +### Deprecated methods -- __overrideAppVersion(String appVersionOverride)__ - Sets the version of the application's binary interface, which would otherwise default to the Play Store version specified as the `versionName` in the `build.gradle`. This should be called a single time, before the CodePush instance is constructed. +- **`getBundleUrl()`** and **`getBundleUrl(String assetsBundleFileName)`** - Use the corresponding `getJSBundleFile` method instead. diff --git a/docs/api-ios.md b/docs/api-ios.md index 7481daa1..0b42acf8 100644 --- a/docs/api-ios.md +++ b/docs/api-ios.md @@ -1,31 +1,21 @@ -### Objective-C API Reference (iOS) +## Objective-C API Reference (iOS) -The Objective-C API is made available by importing the `CodePush.h` header into your `AppDelegate.m` file, and consists of a single public class named `CodePush`. +Import `CodePush.h` and use the `CodePush` class when configuring the React Native bundle URL. See the [iOS setup](../README.md#2-edit-appdelegate-code) for the standard integration. -#### CodePush +### Bundle resolution -Contains static methods for retreiving the `NSURL` that represents the most recent JavaScript bundle file, and can be passed to the `RCTRootView`'s `initWithBundleURL` method when bootstrapping your app in the `AppDelegate.m` file. +The following methods return the latest compatible CodePush update when one is installed, or the bundle embedded in the app otherwise: -The `CodePush` class' methods can be thought of as composite resolvers which always load the appropriate bundle, in order to accommodate the following scenarios: +- **`+ (NSURL *)bundleURL`** - Uses `main.jsbundle` as the embedded bundle. -1. When an end-user installs your app from the store (like `1.0.0`), they will get the JS bundle that is contained within the binary. This is the behavior you would get without using CodePush, but we make sure it doesn't break :) +- **`+ (NSURL *)bundleURLForResource:(NSString *)resourceName`** - Uses the specified embedded bundle name and the `jsbundle` extension. -2. As soon as you begin releasing CodePush updates, your end-users will get the JS bundle that represents the latest release for the configured deployment. This is the behavior that allows you to iterate beyond what you shipped to the store. +- **`+ (NSURL *)bundleURLForResource:(NSString *)resourceName withExtension:(NSString *)resourceExtension`** - Uses the specified embedded bundle name and extension. -3. As soon as you release an update to the app store (like `1.1.0`), and your end-users update it, they will once again get the JS bundle that is contained within the binary. This behavior ensures that CodePush updates that targetted a previous binary version aren't used (since we don't know if they would work), and your end-users always have a working version of your app. +- **`+ (NSURL *)bundleURLForResource:(NSString *)resourceName withExtension:(NSString *)resourceExtension subdirectory:(NSString *)resourceSubdirectory`** - Also looks for the embedded bundle in the specified subdirectory. -4. Repeat #2 and #3 as the CodePush releases and app store releases continue on into infinity (and beyond?) +- **`+ (NSURL *)bundleURLForResource:(NSString *)resourceName withExtension:(NSString *)resourceExtension subdirectory:(NSString *)resourceSubdirectory bundle:(NSBundle *)resourceBundle`** - Also looks for the embedded bundle in the specified resource bundle. -Because of this behavior, you can safely deploy updates to both the app store(s) and CodePush as necesary, and rest assured that your end-users will always get the most recent version. +### Configuration -##### Methods - -- __(NSURL \*)bundleURL__ - Returns the most recent JS bundle `NSURL` as described above. This method assumes that the name of the JS bundle contained within your app binary is `main.jsbundle`. - -- __(NSURL \*)bundleURLForResource:(NSString \*)resourceName__ - Equivalent to the `bundleURL` method, but also allows customizing the name of the JS bundle that is looked for within the app binary. This is useful if you aren't naming this file `main` (which is the default convention). This method assumes that the JS bundle's extension is `*.jsbundle`. - -- __(NSURL \*)bundleURLForResource:(NSString \*)resourceName withExtension:(NSString \*)resourceExtension__: Equivalent to the `bundleURLForResource:` method, but also allows customizing the extension used by the JS bundle that is looked for within the app binary. This is useful if you aren't naming this file `*.jsbundle` (which is the default convention). - -- __(void)overrideAppVersion:(NSString \*)appVersionOverride__ - Sets the version of the application's binary interface, which would otherwise default to the App Store version specified as the `CFBundleShortVersionString` in the `Info.plist`. This should be called a single time, before the bundle URL is loaded. - -- __(void)setDeploymentKey:(NSString \*)deploymentKey__ - Sets the deployment key that the app should use when querying for updates. This is a dynamic alternative to setting the deployment key in your `Info.plist` and/or specifying a deployment key in JS when calling `checkForUpdate` or `sync`. +- **`+ (void)overrideAppVersion:(NSString *)appVersion`** - Overrides the binary version used for update compatibility checks. Call this before resolving the bundle URL. diff --git a/ios/CodePush/CodePush.h b/ios/CodePush/CodePush.h index 06a69ed1..53da8f7a 100644 --- a/ios/CodePush/CodePush.h +++ b/ios/CodePush/CodePush.h @@ -36,6 +36,10 @@ @interface CodePush : RCTEventEmitter #endif +/* + * Returns the bundle embedded in the binary, without resolving an installed update. + * The update pipeline uses this as the base for binary patches and asset diffs. + */ + (NSURL *)binaryBundleURL; /* * This method is used to retrieve the URL for the most recent @@ -64,8 +68,10 @@ subdirectory:(NSString *)resourceSubdirectory bundle:(NSBundle *)resourceBundle; +/* Internal storage root used by CodePushPackage. */ + (NSString *)getApplicationSupportDirectory; +/* Returns the embedded assets path used as the base for asset diffs. */ + (NSString *)bundleAssetsPath; /* @@ -76,9 +82,8 @@ + (void)overrideAppVersion:(NSString *)appVersion; /* - * This method allows dynamically setting the app's - * deployment key, in addition to setting it via - * the Info.plist file's CodePushDeploymentKey setting. + * Retained for compatibility. The current implementation ignores the argument + * and uses the deprecated deployment key placeholder. */ + (void)setDeploymentKey:(NSString *)deploymentKey;