Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Readme #3

Merged
merged 2 commits into from
Dec 31, 2023
Merged

Readme #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
686204c
update readme
TheJaredWilcurt Dec 27, 2023
a65c3cb
Merge remote-tracking branch 'refs/remotes/origin/main' into readme
TheJaredWilcurt Dec 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 43 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,12 @@ In the `splash.html` file
* 3. Launches a window pointed to the latest version
*/
nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
// OPTIONAL: defaults to true
// OPTIONAL: defaults to true, will not show console messages if false
verbose: true,
/**
* OPTIONAL: console.error is called by default if verbose: true.
*
* Your own custom logging function called with helpful warning/error
* messages from the internal validators. Only used if verbose: true.
* OPTIONAL: Your own custom logging function called with helpful
* warning/error messages from the internal validators. Only used if
* verbose: true. Defaults to console.error if not supplied.
*
* @param {string} message The human readable warning/error message
* @param {object} error Sometimes an error or options object is passed
Expand All @@ -51,10 +50,14 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
* then pass the response into the confirmNewVersion and downloadPath
* callback functions you provide.
*/
// This is an example, you can put whatever URL you want here
// This is an example, you can put whatever URL you want here, does not need to be JSON.
versionUrl: 'https://example.com/versions.json',
/**
* Check if the latest remote version is newer than the latest local version.
* This function is handed the response from the versionUrl request, and the version number
* of the latest locally installed version of your app. You can then perform whatever logic
* you want (including additional network calls) to determine wether to download a new
* version of your app or to use the local copy.
*
* If a new version is available, return the new version number to begin the
* download/extract. If no new version exists, then return false and the latest
* local version will be opened in a new window and the splash screen closed.
Expand Down Expand Up @@ -85,11 +88,12 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
response = JSON.parse(response);
return response.latest.downloadUrl;
},
// If the download or extract fails, we will retry n times before stopping
// If the download or extract fails, we will retry the following amount of times before stopping
downloadRetries: 3,
extractRetries: 3,
/**
* Called when an update occurs during download/extract.
* Optional event hook.
* Called when an update occurs during download/extract. May be called many times.
*
* @param {object} update Object containing percents
* @param {number} update.downloadProgress The download progress percent
Expand All @@ -107,8 +111,8 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
/**
* Optional function. You can run any code to validate
* that the downloaded zip matches expecations.
* If it does return true. If you return false, then
* nwSplasherAutoUpdate will retry or stop running.
* If it does, return true. If you return false, then
* nwSplasherAutoUpdate will retry the download or stop running.
*
* @param {string} pathToZip File path to the downloaded zip file
* @return {boolean} true = continue, false = retry/stop
Expand All @@ -120,17 +124,18 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
/**
* Optional function. You can run any code to validate
* that the files extracted from the zip match your
* expecations. If they do return true. If you return false,
* then nwSplasherAutoUpdate will retry or stop running.
* expecations. If they do, return true. If you return false,
* then nwSplasherAutoUpdate will retry extraction or stop running.
*
* @param {string} pathToExtract File path to the downloaded zip file
* @param {string} pathToExtract File path to extracted folder
* @return {boolean} true = continue, false = retry/stop
*/
validateExtract: function (pathToExtract) {
// This is just an example, you can put any logic you want here
return true;
},
/**
* Optional event hook.
* When download or extract fails, but we haven't
* exhausted all retries yet, this is called.
*
Expand All @@ -141,6 +146,7 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
console.log(message);
},
/**
* Optional event hook.
* Called when an error is encountered that ended execution
* prematurely. Such as failing to download or extract after
* all retries were exhausted.
Expand All @@ -153,6 +159,7 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
console.log(errorMessage, error);
},
/**
* Optional event hook.
* Called just prior to opening the new window
* and closing the splash screen.
*/
Expand All @@ -172,14 +179,17 @@ nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
});
```

In your main window that is displayed after the auto-update
In your main window that is displayed after the auto-update (probably `index.html`);

```js
```html
<script>
const nwSplasherAutoUpdate = require('nw-splasher-auto-update');
nwSplasherAutoUpdate.setCurrentWorkingDirectory();
nwSplasherAutoUpdate.closeSplashAndShowApp({
// Must match the port number used in the splash.html
port: 4443
});
</script>
```


Expand All @@ -193,6 +203,7 @@ Deleting old cache
*/
nwSplasherAutoUpdate.deletePastVersions({
/**
* Optional event hook.
* Called when any errors are encountered during deletion.
*
* @param {string} errorMessage Human readable error message
Expand All @@ -202,6 +213,7 @@ nwSplasherAutoUpdate.deletePastVersions({
console.log(errorMessage, err);
},
/**
* Optional event hook.
* When deletion attempt finishes, whether successful or not.
*/
onComplete: function () {
Expand Down Expand Up @@ -231,7 +243,7 @@ path.join(nw.App.dataPath, 'nwSplasherExtracts', version);
* Would use `nw-splasher` as a dependency
* Would use `fs-extra` to delete files
* Not sure what to use for network requests (versions.json), downloading zip (including progress updates), or extracting the zip file (including progress updates)
* We have a lot of beginner programmers. So although internally we may use async/await and promises, I'd like the API to be kept as a simple/approachable object with callbacks to be more approachable
* We have a lot of beginner programmers. So although internally we may use async/await and promises, I'd like to keep the API as a simple object with callbacks to be more approachable
* There are a lot of other features we might want to add in the future, like support for `.tar.gz`, `.rar`, `.7z`, etc but let's keep the scope small for now until those features are requested.


Expand All @@ -242,8 +254,12 @@ path.join(nw.App.dataPath, 'nwSplasherExtracts', version);
nwSplasherAutoUpdate.downloadLatestAppAndOpenWindowInBackground({
autoUpdate: {
versionUrl: 'https://example.com/versions.json',
confirmNewVersion: function (response, latestLocal) {},
downloadPath: function (response) {}
confirmNewVersion: function (response, latestLocal) {
return true || false;
},
downloadPath: function (response) {
return 'url to download zip file containing new app version'
}
}
});

Expand Down Expand Up @@ -272,6 +288,14 @@ If they release different auto-update packages for different NW.js versions.
We suggest ALL users of this library code in some UI to convey to users when an auto-update won't work, and they'll need to download the full version from the website again. So if a user is on a 3 year old version of NW.js that you want to drop support for, there is some way of conveying that cleanly in the UI that is compatible with the older version.


## How can I force the user to update to a newer NW.js version?

Two ways:

* **Thinking ahead:** Include some code in the splasher window to look at your end point response, notice a flag, and then display a message with a link "You must manually download and install the latest version", then the link opens in the user's default browser with `nw.Shell.openExternal('https://expample.com/download')`.
* **Not thinking ahead:** If you didn't preemptively include a way of handling this case, you can instead have the latest version of the app just be a window that directs people to download a new version. The new version's splasher could then be better designed to handle this scenario.


### For-profit software

If you are using NW.js to create for-profit software, then this style of auto-update may not work for you. If you require authenticating a license, key, or the user, or the download requires authentication, then this "splash + download a zip" approach is likely too simple for your needs, and you should consider writing your own solution custom to your use case.
Loading