Skip to content

Commit 3306ede

Browse files
ofalvaiofalvai
committed
Modernize docs
1 parent 0259190 commit 3306ede

1 file changed

Lines changed: 120 additions & 102 deletions

File tree

‎docs/api-js.md‎

Lines changed: 120 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,119 @@
11
## API Reference
22

3-
The CodePush plugin is made up of two components:
3+
The CodePush app SDK is made up of two components:
44

5-
1. A JavaScript module, which can be imported/required, and allows the app to interact with the service during runtime (for example check for updates, inspect the metadata about the currently running app update).
5+
1. A JavaScript module, which can be imported, and allows app code to interact with the service during runtime (for example, force-check for updates, inspect the metadata about the currently running app update).
66

77
2. A native API (Objective-C and Java) which allows the React Native app host to bootstrap itself with the right JS bundle location.
88

99
The following sections describe the shape and behavior of these APIs in detail:
1010

1111
### JavaScript API Reference
1212

13-
When you require `react-native-code-push`, the module object provides the following top-level methods in addition to the root-level [component decorator](#codepush):
14-
15-
* [allowRestart](#codepushallowrestart): Re-allows programmatic restarts to occur as a result of an update being installed, and optionally, immediately restarts the app if a pending update had attempted to restart the app while restarts were disallowed. This is an advanced API and is only necessary if your app explicitly disallowed restarts via the `disallowRestart` method.
16-
17-
* [checkForUpdate](#codepushcheckforupdate): Asks the CodePush service whether the configured app deployment has an update available.
18-
19-
* [disallowRestart](#codepushdisallowrestart): Temporarily disallows any programmatic restarts to occur as a result of a CodePush update being installed. This is an advanced API, and is useful when a component within your app (for example an onboarding process) needs to ensure that no end-user interruptions can occur during its lifetime.
20-
21-
* [getCurrentPackage](#codepushgetcurrentpackage): Retrieves the metadata about the currently installed update (like description, installation time, size). *NOTE: As of `v1.10.3-beta` of the CodePush module, this method is deprecated in favor of [`getUpdateMetadata`](#codepushgetupdatemetadata)*.
22-
23-
* [getUpdateMetadata](#codepushgetupdatemetadata): Retrieves the metadata for an installed update (like description, mandatory).
13+
#### codePush
2414

25-
* [notifyAppReady](#codepushnotifyappready): Notifies the CodePush runtime that an installed update is considered successful. If you are manually checking for and installing updates (i.e. not using the [sync](#codepushsync) method to handle it all for you), then this method **MUST** be called; otherwise CodePush will treat the update as failed and rollback to the previous version when the app next restarts.
15+
Integrate CodePush by calling [`sync`](#codepushsync) from a `useEffect` in your root component. Below are some examples of ways you can set this up (you can pick one or even use a combination):
2616

27-
* [restartApp](#codepushrestartapp): Immediately restarts the app. If there is an update pending, it will be immediately displayed to the end user. Otherwise, calling this method simply has the same behavior as the end user killing and restarting the process.
17+
1. **Silent sync on app start** *(the simplest, default behavior)*. Your app will automatically download available updates, and apply them the next time the app restarts (like the OS or end user killed it, or the device was restarted). This way, the entire update experience is "silent" to the end user, since they don't see any update prompt and/or "synthetic" app restarts.
2818

29-
* [sync](#codepushsync): Allows checking for an update, downloading it and installing it, all with a single call. Unless you need custom UI and/or behavior, we recommend most developers to use this method when integrating CodePush into their apps
19+
```javascript
20+
import { useEffect } from "react";
21+
import codePush from "react-native-code-push";
22+
23+
function App() {
24+
useEffect(() => {
25+
// Fully silent update which keeps the app in
26+
// sync with the server, without ever
27+
// interrupting the end user
28+
codePush.sync();
29+
}, []);
30+
31+
return <YourAppContent />;
32+
}
3033

31-
* [clearUpdates](#clearupdates): Clear all downloaded CodePush updates. This is useful when switching to a different deployment which may have an older release than the current package.
32-
33-
_Note: we don’t recommend to use this method in scenarios other than that (CodePush will call this method automatically when needed in other cases) as it could lead to unpredictable behavior._
34+
export default App;
35+
```
3436

35-
#### codePush
37+
2. **Silent sync every time the app resumes**. Same as 1, except we check for updates, or apply an update if one exists every time the app returns to the foreground after being "backgrounded".
3638

37-
```javascript
38-
// Wrapper function
39-
codePush(rootComponent: React.Component): React.Component;
40-
codePush(options: CodePushOptions)(rootComponent: React.Component): React.Component;
41-
```
42-
```javascript
43-
// Decorator; Requires ES7 support
44-
@codePush
45-
@codePush(options: CodePushOptions)
46-
```
39+
```javascript
40+
import { useEffect } from "react";
41+
import { AppState } from "react-native";
42+
import codePush from "react-native-code-push";
4743
48-
Used to wrap a React component inside a "higher order" React component that knows how to synchronize your app's JavaScript bundle and image assets when it is mounted. Internally, the higher-order component calls [`sync`](#codepushsync) inside its `componentDidMount` lifecycle handle, which in turns performs an update check, downloads the update if it exists and installs the update for you.
44+
const syncOptions = { installMode: codePush.InstallMode.ON_NEXT_RESUME };
4945
50-
This decorator provides support for letting you customize its behaviour to easily enable apps with different requirements. Below are some examples of ways you can use it (you can pick one or even use a combination):
46+
function App() {
47+
useEffect(() => {
48+
codePush.sync(syncOptions);
5149
52-
1. **Silent sync on app start** *(the simplest, default behavior)*. Your app will automatically download available updates, and apply them the next time the app restarts (like the OS or end user killed it, or the device was restarted). This way, the entire update experience is "silent" to the end user, since they don't see any update prompt and/or "synthetic" app restarts.
50+
const subscription = AppState.addEventListener("change", (newState) => {
51+
if (newState === "active") {
52+
codePush.sync(syncOptions);
53+
}
54+
});
5355
54-
```javascript
55-
// Fully silent update which keeps the app in
56-
// sync with the server, without ever
57-
// interrupting the end user
58-
class MyApp extends Component<{}> {}
59-
MyApp = codePush(MyApp);
60-
export default MyApp;
61-
```
56+
return () => subscription.remove();
57+
}, []);
6258
63-
2. **Silent sync every time the app resumes**. Same as 1, except we check for updates, or apply an update if one exists every time the app returns to the foreground after being "backgrounded".
59+
return <YourAppContent />;
60+
}
6461
65-
```javascript
66-
// Sync for updates every time the app resumes.
67-
class MyApp extends Component<{}> {}
68-
MyApp = codePush({ checkFrequency: codePush.CheckFrequency.ON_APP_RESUME, installMode: codePush.InstallMode.ON_NEXT_RESUME })(MyApp);
69-
export default MyApp;
62+
export default App;
7063
```
7164

7265
3. **Interactive**. When an update is available, prompt the end user for permission before downloading it, and then immediately apply the update. If an update was released using the `mandatory` flag, the end user would still be notified about the update, but they wouldn't have the choice to ignore it.
7366
7467
```javascript
75-
// Active update, which lets the end user know
76-
// about each update, and displays it to them
77-
// immediately after downloading it
78-
class MyApp extends Component<{}> {}
79-
MyApp = codePush({ updateDialog: true, installMode: codePush.InstallMode.IMMEDIATE })(MyApp);
80-
export default MyApp;
68+
import { useEffect } from "react";
69+
import codePush from "react-native-code-push";
70+
71+
function App() {
72+
useEffect(() => {
73+
// Active update, which lets the end user know
74+
// about each update, and displays it to them
75+
// immediately after downloading it
76+
codePush.sync({ updateDialog: true, installMode: codePush.InstallMode.IMMEDIATE });
77+
}, []);
78+
79+
return <YourAppContent />;
80+
}
81+
82+
export default App;
8183
```
8284
83-
4. **Log/display progress**. While the app is syncing with the server for updates, make use of the `codePushStatusDidChange` and/or `codePushDownloadDidProgress` event hooks to log down the different stages of this process, or even display a progress bar to the user.
85+
4. **Log/display progress**. Pass the `syncStatusChangedCallback` and/or `downloadProgressCallback` arguments to `sync` to log the different stages of the process, or even display a progress bar to the user.
8486
8587
```javascript
86-
// Make use of the event hooks to keep track of
87-
// the different stages of the sync process.
88-
class MyApp extends Component<{}> {
89-
codePushStatusDidChange(status) {
90-
switch(status) {
91-
case codePush.SyncStatus.CHECKING_FOR_UPDATE:
92-
console.log("Checking for updates.");
93-
break;
94-
case codePush.SyncStatus.DOWNLOADING_PACKAGE:
95-
console.log("Downloading package.");
96-
break;
97-
case codePush.SyncStatus.INSTALLING_UPDATE:
98-
console.log("Installing update.");
99-
break;
100-
case codePush.SyncStatus.UP_TO_DATE:
101-
console.log("Up-to-date.");
102-
break;
103-
case codePush.SyncStatus.UPDATE_INSTALLED:
104-
console.log("Update installed.");
105-
break;
106-
}
107-
}
108-
109-
codePushDownloadDidProgress(progress) {
110-
console.log(progress.receivedBytes + " of " + progress.totalBytes + " received.");
111-
}
88+
import { useEffect, useState } from "react";
89+
import codePush from "react-native-code-push";
90+
91+
function App() {
92+
const [status, setStatus] = useState(null);
93+
94+
useEffect(() => {
95+
codePush.sync(
96+
{},
97+
(syncStatus) => setStatus(syncStatus),
98+
({ receivedBytes, totalBytes }) => {
99+
console.log(`${receivedBytes} of ${totalBytes} received.`);
100+
}
101+
);
102+
}, []);
103+
104+
return <YourAppContent status={status} />;
112105
}
113-
MyApp = codePush(MyApp);
114-
export default MyApp;
106+
107+
export default App;
115108
```
116109
117110
##### CodePushOptions
118111
119-
The `codePush` decorator accepts an "options" object that allows you to customize numerous aspects of the default behavior mentioned above:
112+
The options object passed to `sync` allows you to customize numerous aspects of the default behavior mentioned above:
120113
121114
* __checkFrequency__ *(codePush.CheckFrequency)* - Specifies when you would like to check for updates. Defaults to `codePush.CheckFrequency.ON_APP_START`. Refer to the [`CheckFrequency`](#checkfrequency) enum reference for a description of the available options and what they do.
122115
123-
* __deploymentKey__ *(String)* - Specifies the deployment key you want to query for an update against. By default, this value is derived from the `Info.plist` file (iOS) and `MainActivity.java` file (Android), but this option allows you to override it from the script-side if you need to dynamically use a different deployment.
116+
* __deploymentKey__ *(String)* - Specifies the deployment key you want to query for an update against. By default, this value is derived from the `Info.plist` file (iOS) and `strings.xml` file (Android), but this option allows you to override it from the script-side if you need to dynamically use a different deployment.
124117
125118
* __installMode__ *(codePush.InstallMode)* - Specifies when you would like to install optional updates (i.e. those that aren't marked as mandatory). Defaults to `codePush.InstallMode.ON_NEXT_RESTART`. Refer to the [`InstallMode`](#installmode) enum reference for a description of the available options and what they do.
126119

@@ -156,18 +149,42 @@ The `codePush` decorator accepts an "options" object that allows you to customiz
156149

157150
* __maxRetryAttempts__ *(Number)* - Specifies the maximum number of retry attempts that the app can make before it stops trying. Cannot be less than `1`. Defaults to `1`.
158151

159-
##### codePushStatusDidChange (event hook)
152+
##### syncStatusChangedCallback
160153

161-
Called when the sync process moves from one stage to another in the overall update process. The event hook is called with a status code which represents the current state, and can be any of the [`SyncStatus`](#syncstatus) values.
154+
Called when the sync process moves from one stage to another in the overall update process. Pass this as the `syncStatusChangedCallback` argument to [`sync`](#codepushsync); it's called with a status code which represents the current state, and can be any of the [`SyncStatus`](#syncstatus) values.
162155
163-
##### codePushDownloadDidProgress (event hook)
156+
##### downloadProgressCallback
164157
165-
Called periodically when an available update is being downloaded from the CodePush server. The method is called with a `DownloadProgress` object, which contains the following two properties:
158+
Called periodically when an available update is being downloaded from the CodePush server. Pass this as the `downloadProgressCallback` argument to [`sync`](#codepushsync); it's called with a `DownloadProgress` object, which contains the following two properties:
166159

167160
* __totalBytes__ *(Number)* - The total number of bytes expected to be received for this update (i.e. the size of the set of files which changed from the previous release).
168161

169162
* __receivedBytes__ *(Number)* - The number of bytes downloaded thus far, which can be used to track download progress.
170163

164+
```javascript
165+
import codePush from "react-native-code-push";
166+
```
167+
168+
The default export, `codePush` above, is a single object. Every API described below hangs off it as a property: methods you call like `codePush.sync(...)`, and a handful of constant groups (`codePush.InstallMode`, `codePush.SyncStatus`, `codePush.CheckFrequency`, `codePush.UpdateState`) you read values from, like `codePush.InstallMode.IMMEDIATE`.
169+
170+
It provides the following methods:
171+
172+
* [sync](#codepushsync): Allows checking for an update, downloading it and installing it, all with a single call. Unless you need custom UI and/or behavior, we recommend most developers to call this method from a `useEffect` in their root component when integrating CodePush into their apps. See the [setup examples](#codepush) above.
173+
174+
* [allowRestart](#codepushallowrestart): Re-allows programmatic restarts to occur as a result of an update being installed, and optionally, immediately restarts the app if a pending update had attempted to restart the app while restarts were disallowed. This is an advanced API and is only necessary if your app explicitly disallowed restarts via the `disallowRestart` method.
175+
176+
* [checkForUpdate](#codepushcheckforupdate): Asks the CodePush service whether the configured app deployment has an update available.
177+
178+
* [disallowRestart](#codepushdisallowrestart): Temporarily disallows any programmatic restarts to occur as a result of a CodePush update being installed. This is an advanced API, and is useful when a component within your app (for example an onboarding process) needs to ensure that no end-user interruptions can occur during its lifetime.
179+
180+
* [getUpdateMetadata](#codepushgetupdatemetadata): Retrieves the metadata for an installed update (like description, mandatory).
181+
182+
* [notifyAppReady](#codepushnotifyappready): Notifies the CodePush runtime that an installed update is considered successful. If you are manually checking for and installing updates (i.e. not using the [sync](#codepushsync) method to handle it all for you), then this method **MUST** be called; otherwise CodePush will treat the update as failed and rollback to the previous version when the app next restarts.
183+
184+
* [restartApp](#codepushrestartapp): Immediately restarts the app. If there is an update pending, it will be immediately displayed to the end user. Otherwise, calling this method simply has the same behavior as the end user killing and restarting the process.
185+
186+
* [clearUpdates](#clearupdates): Clear all downloaded CodePush updates. This is useful when switching to a different deployment which may have an older release than the current package.
187+
171188
#### codePush.allowRestart
172189

173190
```javascript
@@ -255,21 +272,22 @@ As an alternative, you could also choose to simply use `InstallMode.ON_NEXT_REST
255272
Example Usage:
256273

257274
```javascript
258-
class OnboardingProcess extends Component {
259-
...
275+
import { useEffect } from "react";
276+
import codePush from "react-native-code-push";
260277
261-
componentWillMount() {
278+
function OnboardingProcess() {
279+
useEffect(() => {
262280
// Ensure that any CodePush updates which are
263281
// synchronized in the background can't trigger
264282
// a restart while this component is mounted.
265283
codePush.disallowRestart();
266-
}
267284
268-
componentWillUnmount() {
269-
// Reallow restarts, and optionally trigger
270-
// a restart if one was currently pending.
271-
codePush.allowRestart();
272-
}
285+
return () => {
286+
// Reallow restarts, and optionally trigger
287+
// a restart if one was currently pending.
288+
codePush.allowRestart();
289+
};
290+
}, []);
273291
274292
...
275293
}
@@ -334,11 +352,11 @@ Example Usage:
334352
335353
```javascript
336354
// Check if there is currently a CodePush update running, and if
337-
// so, register it with the HockeyApp SDK (https://github.com/slowpath/react-native-hockeyapp)
338-
// so that crash reports will correctly display the JS bundle version the user was running.
355+
// so, tag it on your crash reporting service (e.g. Sentry) so that
356+
// crash reports correctly display the JS bundle version the user was running.
339357
codePush.getUpdateMetadata().then((update) => {
340358
if (update) {
341-
hockeyApp.addMetadata({ CodePushRelease: update.label });
359+
Sentry.setTag("codepush_release", update.label);
342360
}
343361
});
344362
@@ -497,7 +515,7 @@ This method returns a `Promise` which is resolved to a `SyncStatus` code that in
497515

498516
* __codePush.SyncStatus.SYNC_IN_PROGRESS__ *(4)* - There is an ongoing `sync` operation running which prevents the current call from being executed.
499517

500-
The `sync` method can be called anywhere you'd like to check for an update. That could be in the `componentWillMount` lifecycle event of your root component, the onPress handler of a `<TouchableHighlight>` component, in the callback of a periodic timer, or whatever else makes sense for your needs. Just like the `checkForUpdate` method, it will perform the network request to check for an update in the background, so it won't impact your UI thread and/or JavaScript thread's responsiveness.
518+
The `sync` method can be called anywhere you'd like to check for an update. That could be in a `useEffect` in your root component, the `onPress` handler of a `<Pressable>` component, in the callback of a periodic timer, or whatever else makes sense for your needs. Just like the `checkForUpdate` method, it will perform the network request to check for an update in the background, so it won't impact your UI thread and/or JavaScript thread's responsiveness.
501519

502520
#### Package objects
503521

@@ -559,7 +577,7 @@ This enum specifies when you would like an installed update to actually be appli
559577
560578
##### CheckFrequency
561579
562-
This enum specifies when you would like your app to sync with the server for updates, and can be passed to the `codePushify` decorator. It includes the following values:
580+
This enum specifies when you would like your app to sync with the server for updates. It includes the following values:
563581
564582
* __codePush.CheckFrequency.ON_APP_START__ *(0)* - Indicates that you want to check for updates whenever the app's process is started.
565583

0 commit comments

Comments
 (0)