Skip to content

Commit

Permalink
Merge pull request #12 from vantuan88291/task/git-engine
Browse files Browse the repository at this point in the history 
New feature: git engine
  • Loading branch information
@vantuan88291
vantuan88291 authored Dec 26, 2024
2 parents 88293b8 + 878af93 commit 7e712a5
Show file tree
Hide file tree
Showing 22 changed files with 1,260 additions and 129 deletions.
172 changes: 172 additions & 0 deletions DOC_OTA_GIT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# Hot Update via Git

This feature allows you to use a Git repository to host your bundle files. The mobile application will pull only the changes from the Git repository instead of downloading the entire bundle file from a server. This reduces data usage and improves update speed.


iOS GIF | Android GIF
:-------------------------:|:-------------------------:
<img src="./iosgit.gif" title="iOS GIF" width="250"> | <img src="./androidgithotupdate.gif" title="Android GIF" width="250">

Can see the demo video here:

https://drive.google.com/file/d/1P3usN7cbBlboJ5pH211m9BKZyVusMQw5/view?usp=sharing

## Supported Platforms
Currently, this feature supports the following Git hosting platforms:
- GitHub
- GitLab
- Bitbucket

## Installation
If you want to use git control, you may need install `react-native-fs`

`yarn add react-native-fs`

## Setting Up a Git Repository for Hot Update

### Step 1: Create a Git Repository
1. Log in to your Git hosting service (e.g., GitHub, GitLab, Bitbucket).
2. Create a new repository to host your bundle files. For example, name it `OTA-bundle`.
3. Clone the repository to your local machine:
```bash
git clone https://github.com/<your-username>/OTA-bundle.git
```

### Step 2: Add Bundle Files to the Repository
1. Generate your bundle files using the React Native CLI or Expo.

- For react native CLI:
```bash
"scripts": {
"export-android": "mkdir -p android/output && react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/output/index.android.bundle --assets-dest android/output",
"export-ios": "mkdir -p ios/output && react-native bundle --platform ios --dev false --entry-file index.js --bundle-output ios/output/main.jsbundle --assets-dest ios/output"
}
```
- For expo / expo bare project:

```bash
"scripts": {
"export-android": "mkdir -p android/output && npx expo export:embed --platform android --entry-file node_modules/expo/AppEntry.js --bundle-output android/output/index.android.bundle --dev false --assets-dest android/output",
"export-ios": "mkdir -p ios/output && npx expo export:embed --platform ios --entry-file node_modules/expo/AppEntry.js --bundle-output ios/output/main.jsbundle --dev false --assets-dest ios/output"
}
```
For expo you might need check path of `--entry-file node_modules/expo/AppEntry.js`, get it from package.json / main

2. Copy `android/output` / `ios/output` folder into the cloned repository directory.
3. Commit and push the changes to your Git repository:
```bash
git add .
git commit -m "Initial commit with bundle files"
git push origin main
```

### Step 3: Organize Branches for Platforms
- Create separate branches for iOS and Android updates (optional but recommended):
```bash
git checkout -b iOS
git push origin iOS

git checkout -b android
git push origin android
```
- Maintain platform-specific bundle files in their respective branches.

## Example Implementation

Here is a complete example of how to implement the hot update via Git:

```typescript
const onCheckGitVersion = () => {
hotUpdate.git.checkForGitUpdate({
branch: Platform.OS === 'ios' ? 'iOS' : 'android',
bundlePath:
Platform.OS === 'ios'
? 'output/main.jsbundle'
: 'output/index.android.bundle',
url: 'https://github.com/<your-username>/OTA-bundle.git',
onCloneFailed(msg: string) {
Alert.alert('Clone project failed!', msg, [
{
text: 'Cancel',
onPress: () => {},
style: 'cancel',
},
]);
},
onCloneSuccess() {
Alert.alert('Clone project success!', 'Restart to apply the changes', [
{
text: 'OK',
onPress: () => hotUpdate.resetApp(),
},
{
text: 'Cancel',
onPress: () => {},
style: 'cancel',
},
]);
},
onPullFailed(msg: string) {
Alert.alert('Pull project failed!', msg, [
{
text: 'Cancel',
onPress: () => {},
style: 'cancel',
},
]);
},
onPullSuccess() {
Alert.alert('Pull project success!', 'Restart to apply the changes', [
{
text: 'OK',
onPress: () => hotUpdate.resetApp(),
},
{
text: 'Cancel',
onPress: () => {},
style: 'cancel',
},
]);
},
onProgress(received: number, total: number) {
const percent = (+received / +total) * 100;
LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
setProgress(percent);
},
onFinishProgress() {
setLoading(false);
},
});
};
```

## Key Options

| Key | Required | Type | Description |
| --------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------- |
| `restartAfterInstall` | No | `boolean` | Default is `false`. If `true`, the app will restart automatically after applying the changes. |
| `branch` | Yes | `string` | The Git branch to pull updates from (e.g., `iOS` or `android`). |
| `bundlePath` | Yes | `string` | The relative path to the bundle file within the repository. |
| `url` | Yes | `string` | The URL of the Git repository hosting the bundle files. |
| `onCloneFailed` | No | `Callback` | Triggered if the cloning process fails. Receives an error message as an argument. |
| `onCloneSuccess` | No | `Callback` | Triggered when the cloning process is successful. |
| `onPullFailed` | No | `Callback` | Triggered if the pull process fails. Receives an error message as an argument. |
| `onPullSuccess` | No | `Callback` | Triggered when the pull process is successful. |
| `onProgress` | No | `Callback` | A callback that provides download progress updates (received bytes and total bytes). |
| `onFinishProgress` | No | `Callback` | Triggered when the download progress is complete. |

## Explanation of Workflow

1. **Clone in the first time**: The app will check if repository in local not exist, app will clone repo in the first time, this may take time depend on your project size.
2. **Check for Updates**: Next time you call `checkForGitUpdate` method, it will just pull the latest commit.
3. **Handle Clone/Pull Success**: If the operation is successful, you can notify the user and restart the app to apply the updates.
4. **Handle Failures**: If cloning or pulling fails, the user is notified with an appropriate error message.
5. **Track Progress**: The `onProgress` callback is used to update a progress bar or indicator to inform the user of the download status.

## Notes

- Ensure the Git repository is publicly accessible or configured with the appropriate credentials if private.
- The `bundlePath` should match the location of the bundle file within your Git repository.
- This feature is designed to work seamlessly with both iOS and Android platforms.
- There are noway to check whether have new updating, need pull first and notify user or restart the app to apply the changes, if you want check new version before pull the changes, you should design an api for that.
- Git for client we are using `isomorphic-git`, a lightweight git engine for js
112 changes: 112 additions & 0 deletions DOC_OTA_SERVER.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Hot update via server

A React Native module that allows you to control hot update same as Code Push, less config than Code Push, you can control version manager, hosting bundle js by your self, this library just control install the hot update after bundle js downloaded from your side. As we know, Code push is going to retirement soon, that why i create that library for you can control bundle js from your backend side.


iOS GIF | Android GIF
:-------------------------:|:-------------------------:
<img src="./ioshotupdate.gif" title="iOS GIF" width="250"> | <img src="./androidhotupdate.gif" title="Android GIF" width="250">

Here is the guideline to control bundle js by yourself, in here i am using Firebase storage to store bundlejs file and a json file that announce new version is comming:

#### 1.Add these script into your package.json to export bundlejs file and source map file:

- For react native CLI:
```bash
"scripts": {
"export-android": "mkdir -p android/output && react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/output/index.android.bundle --assets-dest android/output --sourcemap-output android/sourcemap.js && cd android && find output -type f | zip index.android.bundle.zip -@ && zip sourcemap.zip sourcemap.js && cd .. && rm -rf android/output && rm -rf android/sourcemap.js",
"export-ios": "mkdir -p ios/output && react-native bundle --platform ios --dev false --entry-file index.js --bundle-output ios/output/main.jsbundle --assets-dest ios/output --sourcemap-output ios/sourcemap.js && cd ios && find output -type f | zip main.jsbundle.zip -@ && zip sourcemap.zip sourcemap.js && cd .. && rm -rf ios/output && rm -rf ios/sourcemap.js"
}
```
- For expo / expo bare project:

```bash
"scripts": {
"export-android": "mkdir -p android/output && npx expo export:embed --platform android --entry-file node_modules/expo/AppEntry.js --bundle-output android/output/index.android.bundle --dev false --assets-dest android/output --sourcemap-output android/sourcemap.js && cd android && find output -type f | zip index.android.bundle.zip -@ && zip sourcemap.zip sourcemap.js && cd .. && rm -rf android/output && rm -rf android/sourcemap.js",
"export-ios": "mkdir -p ios/output && npx expo export:embed --platform ios --entry-file node_modules/expo/AppEntry.js --bundle-output ios/output/main.jsbundle --dev false --assets-dest ios/output --sourcemap-output ios/sourcemap.js && cd ios && find output -type f | zip main.jsbundle.zip -@ && zip sourcemap.zip sourcemap.js && cd .. && rm -rf ios/output && rm -rf ios/sourcemap.js"
}
```
For expo you might need check path of `--entry-file node_modules/expo/AppEntry.js`, get it from package.json / main

These commands are export bundle file and source map file then compress it as a zip file, one for android and one for ios. You can create your own script that export and auto upload to your server. For source map file you can ignore or use that with your purpose to debug in release mode.

Then create an json file: `update.json` like that:
```bash
{
"version": 1,
"downloadAndroidUrl": "https://firebasestorage.googleapis.com/v0/b/ota-demo-68f38.appspot.com/o/index.android.bundle.zip?alt=media",
"downloadIosUrl": "https://firebasestorage.googleapis.com/v0/b/ota-demo-68f38.appspot.com/o/main.jsbundle.zip?alt=media"
}
```

Then upload your bundlejs files to firebase storage, totally will look like that:

![](https://github.com/vantuan88291/react-native-ota-hot-update/raw/main/scr1.png)

After you have done everything related to version manager, you just handle the way to update new version like fetch update.json as api to get download url and call this function:

```bash
import hotUpdate from 'react-native-ota-hot-update';
import ReactNativeBlobUtil from 'react-native-blob-util';


hotUpdate.downloadBundleUri(ReactNativeBlobUtil, url, version, {
updateSuccess: () => {
console.log('update success!');
},
updateFail(message?: string) {
Alert.alert('Update failed!', message, [
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel',
},
]);
},
restartAfterInstall: true,
});
```

The important thing: this library will control `version` by it self, need always pass version as parameter in `downloadBundleUri`, it will storage as a cache and use this to check whether need update version in the next time. Default of `version` is **0**

## Tips for manage bundles

In this demo project i have used firebase storage to control the bundles and version, but that is not useful. I would like to suggest you to use some CMS to control the bundles.
For CMS, it has a lot open sources, now i am using strapi CMS to control the version, i also create auto release script like code push and can integrate with CI/CD. Here is some screenshot of strapi CMS:

![](https://github.com/vantuan88291/react-native-ota-hot-update/raw/main/scr2.png)

![](https://github.com/vantuan88291/react-native-ota-hot-update/raw/main/scr3.png)

Beside strapi you can also try craftcms, payloadcms...
You can refer folder sampleComponent, it has the logic of update with CMS and also include script auto upload the bundle to CMS.
Contact me via email if you want to implement hot update via CMS (need service fee)

## Functions

| key | Return | Action | Parameters |
| ------------ |--------|------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| downloadBundleUri | void | Download bundle and install it | (downloadManager: **DownloadManager**, uri: string, version: number, option?: **UpdateOption**) |
| setupBundlePath | boolean | Install your bundle path if you control the downloading by your self, ignore that if you use `downloadBundleUri` | path: string, the path of zip bundlejs file that you downloaded before |
| setupExactBundlePath | boolean | Install your bundle path if you extract the zip file by yourself | path: string, the path of bundlejs file that you downloaded before |
| removeUpdate | void | Remove you update and use the previos version | restartAfterRemoved?: boolean, restart to apply your changing |
| resetApp | void | Restart the app to apply the changing | empty |
| getCurrentVersion | number | Get the current version that let you use to compare and control the logic updating | empty |
| setCurrentVersion | boolean | Set the current version that let you use to compare and control the logic updating | version: number |


## UpdateOption

| Option | Required | Type | Description |
|-------------------------|----------|----------|--------------------------------------------------------------------------------------------------|
| headers | No | Object | The header to down load your uri bundle file if need token/authentication... |
| updateSuccess | No | Callback | Will trigger when install update success |
| updateFail(message: string) | No | Callback | Will trigger when install update failed |
| restartAfterInstall | No | boolean | default is `false`, if `true` will restart the app after install success to apply the new change |
| progress | No | void | A callback to show progress when downloading bundle |
| extensionBundle | No | string | extension of bundle js file, default is .bundle for android, ios is .jsbundle |

## DownloadManager

The same method as `react-native-blob-util` or `rn-fetch-blob`

Loading

0 comments on commit 7e712a5

Please sign in to comment.