jamielob / reloader

More control over hot code push reloading for your production apps. Designed to replace mdg:reload-on-resume and provide a more production-ready approach.

Reloader

More control over hot code push reloading for your mobile apps. A replacement for mdg:reload-on-resume with more options and better UX.

As of Meteor 1.3, if you prevent instant reloading on updates, the newest version of the code will be used on your app's next cold start - no reload necessary. This can be achieved with Reloader.configure({check: false, refresh: 'start'}). However, you can also:

• Reload on resume, to update to the newest version of the code when the app is returned from the background: see refresh (the launch screen is put back up during such reloads to hide the white screen you get with mdg:reload-on-resume)
• On start or resume, leave the launch screen up and wait to see whether there is an update available: see check, checkTimer, and idleCutoff
• Delay removal of the launch screen, to hide the white screen that appears at the beginning of a reload: see launchScreenDelay

Contents

• Configure
  • check
  • checkTimer
  • refresh
  • idleCutoff
  • launchScreenDelay
• Helpers
  • Reloader.updateAvailable.get()
  • {{updateAvailable}}
  • Reloader.reload()
  • reloader-update
• Development
  • Run tests
  • Credits

Installation

meteor add jamielob:reloader
meteor remove mdg:reload-on-resume

If you have any calls to location.reload() or location.replace(location.href) in your app, replace them with Reloader.reload().

Configure

The default options are shown below. You can override them anywhere in your client/ folder.

Reloader.configure({
  check: 'everyStart', // Check for new code every time the app starts
  checkTimer: 3000,  // Wait 3 seconds to see if new code is available
  refresh: 'startAndResume', // Refresh to already downloaded code on both start and resume
  idleCutoff: 1000 * 60 * 10  // Wait 10 minutes before treating a resume as a start
});

These default options will make sure that your app is up to date every time a user starts your app, or comes back to it after 10 minutes of being idle.

Another popular configuration is:

Reloader.configure({
  check: 'firstStart', // Only make an additonal check the first time the app ever starts
  checkTimer: 5000,  // Wait 5 seconds to see if new code is available on first start
  refresh: 'start' // Only refresh to already downloaded code on a start and not a resume
});

This will make sure the first time your app is run it is up to date, will download new versions of code while the app is being used, and then only update when the app is next started.

You can have a different configuration for development, for instance:

if (Meteor.isDevelopment) {
  Reloader.configure({
    check: false, // don't check on startup
    refresh: 'instantly' // refresh as soon as updates are available
  });
} else {
  Reloader.configure({
    // production configuration
  });
}

check

When to make additional checks for new code bundles. The app splash screen is shown during the check. Possible values are:

• everyStart (default): Check every time the app starts. Does not include resuming the app, unless the idleCutOff has been reached.
• firstStart: Check only the first time the app starts (just after downloading it).
• false: Never make additional checks and rely purely on code bundles being downlaoded in the background while the app is being used.

checkTimer

Default: 3000

How long to wait (in ms) when making additional checks for new file bundles. In future versions of Meteor we will have an API to instantly check if an update is available or not, but until then we need to simply wait to see if a new code bundle is downloaded. Depending on the size of your app bundle and the phone's connection speed, the default three seconds may not be enough - you can increase it if you find that you have new code immediately after starting the app.

refresh

When to refresh to the latest code bundle if one finished downloading after the end of the check period. The app splash screen is shown during the refresh. Possible values are:

• startAndResume (default): Refresh to the latest bundle both when starting and resuming the app.
• start: Refresh only when the app is started (not resumed).
• instantly: Overrides everything else. If set, your app will have similar behaviour to the default in Meteor, with code updates being refreshed immeidately. The only improvement/difference is that the app's splash screen is displayed during the refresh.

idleCutoff

Default: 1000 * 60 * 10 // 10 minutes

How long (in ms) can an app be idle before we consider it a start and not a resume. Applies only when check: 'everyStart'. Set to 0 to never check on resume.

launchScreenDelay

Planned option for future version. Currently not configurable.

Default: 100

How long to wait (in ms) after reload before hiding the launch screen. The goal is to leave it up until your page has finished rendering, so the user does not see a blank white screen. The duration will vary based on your app's render time and the speed of the device. To be more precise, set launchScreenDelay to 0 and release the launch screen yourself when the page has rendered. For example, if the only two pages that might be displayed on reload are index and post, then you would do:

launchScreenHandle = Launchscreen.hold()

Template.index.onRendered(() => {
  launchScreenHandle.release()
});

Template.post.onRendered(() => {
  launchScreenHandle.release()
});

Or if you have a layout template, you could put a single .release() in that template's onRendered.

Helpers

These helpers can help you to have an "Update Now" button.

A note about using these helpers

Some people have reported having their app rejected during the Apple review process for having an "Update Now" button or similar as opposed to using the refresh on resume behavior that this package provides by default. If you really want to have an update button when new code is available, make sure you don't push any new code to the server until after your app has been approved. But it's probably safer/better to simply not have an update button at all!

How to use them anyway

Reloader.updateAvailable.get()

Reloader.updateAvailable is a reactive variable that returns true when an update has been downloaded.

Reloader.updateAvailable.get(); // Reactively returns true if an update is ready

{{updateAvailable}}

This package provides a Blaze template helper that retrieves the value of the reactiveVar easily.

{{#if updateAvailable}}
  	<p>Update available!</p>
{{/if}}

Reloader.reload()

Call Reloader.reload() to refresh the page.

reloader-update

This package also provides an easy reload event that you can attach to a button that will briefly show the splash screen and update to the latest version. Simply add the reloader-update attribute to a button.

{{#if updateAvailable}}
	<a class="button" reloader-update>Tap here to update!</a>
{{/if}}

Development

Run tests

git clone [email protected]:jamielob/reloader.git
cd reloader
# uncomment the noted line in package.js
meteor test-packages ./ --driver-package practicalmeteor:mocha
open localhost:3000

Credits

Contributors

And thanks to @martijnwalraven for his help with this packages and superb work on Meteor Cordova! 👏

reloader's Issues

Move to later version of Cordova Splashscreen?

Any reason this is locked to 4.0.0 https://github.com/jamielob/reloader/blob/master/package.js#L10

I think that means it's dependent, right... won't work with later versions?

Newer versions here https://github.com/apache/cordova-plugin-splashscreen/blob/master/RELEASENOTES.md

Possible configurations

Working blueprint

When to do additional checks:

• Do an additional check on first start (default)
• Do additional checks on every start
• Never do an additional check

When to reload the code already downloaded:

• Only on starts (default)
• Starts plus resume
• Instantly

How to differentiate between a start and a resume:

• System resume event and an idle timer (default)
• Just the system resume event
• Just an idle timer

Reload doesn't work on "START"

Hi everyone! I just tried to use this package for our app and I want to configure => "Update app on Start" but it doesn't work for some reason.
my code is just from example.

Reloader.configure({
check: 'everyStart', // Check for new code every time the app starts
checkTimer: 3000, // Wait 3 seconds to see if new code is available
refresh: 'startAndResume', // Refresh to already downloaded code on both start and resume
idleCutoff: 1000 * 60 * 10 // Wait 10 minutes before treating a resume as a start
});

So it works on "Resume" but after app was started I still see the message "Please update" which I implemented, and old version on the phone.
What to do with that?

Reload on Resume doesn't work

Hi guys, I was trying to use this package for a production ready app I've been working and I can get this package to work. I debugged it and I realize that it looks like there is an error, for e.g when you do use this within the Tracker or a SetTimeout, beacuse this is a reference to the thread running inside the Tracker. Am I missing something here? Because this.updateAvailable() its always undefinded

Tracker.autorun((computation) => {
        if (this.updateAvailable()) {
          this.reload();
        }

        this._waitForUpdate(computation);
      });

Thank you!

Cannot read property 'configure' of undefined

Hello!

I tried to use your package, but seems like Reloader has no methods. What have I done wrong?

I just used basic configuration on client inside main.js file:

Reloader.configure({
    check: false,
    refresh: 'start'
})

Also i tried to do:

• import {Reloader} from "meteor/jamielob:reloader";,
• place code inside Meteor.startup().

Have not positive result.

Question about Setup / can our requirements be solved with this package?

Hello,

we're developing a cool modern meteor-cordova-app (of course, why would we be here otherwise? :) ) and we're fine-tuning the startup experience at the moment.

What we'd like to have the app behave like in the end is this:

• First launch and any launch after more than 10 minutes of being in the background or not running: Show the splashscreen (so far, so good!) and do the update while the splashscreen is still showing - don't let the user start with a stale version if possible.
• After launch: don't restart the app if the user switched away from the app for less than eg. 10 minutes.

Note: All this is mainly tested on an LG G2 Android Device using the crosswalk package at the moment.

An example for the issue we're running into at the moment:

• The user starts the app and sees a login screen
• a release is detected / being loaded in the background
• The user enters his username
• The user might switch to another app to go read his password or something similar
• The user comes back - and the app reloads. He needs to re-enter his username too.

We could mitigate the missing username in this case by storing the content in a more permanent spot, but this is just an example. At any point in the app the user could switch to another app and switch back a few seconds later.

I thought that this would actually be solved by the default Reloader config: I interpreted (wished? it to be:) ) it as follows:

Reloader.configure({
    check: 'everyStart', // Yes, that's cool, but only on "real" starts or after idleCutoff seconds?
    checkTimer: 3000,  //3 seconds  // don't know what this is?
    idleCutoff: 1000 * 60 * 10  //10 minutes  // only restart the app after more than 10 minutes have passed since the user navigated away from it
});

The behaviour we're observing at the moment (using the default options at the moment):

• The app starts the first time. If an update is available, it won't be loaded immediately, the splashscreen will be hidden and the app will start running, but not with the latest version (Reloader.updateAvailable.get() will return true )
• Going to the homescreen for a few seconds and returning will trigger a reload (splashscreen, reload of app)

Is there a way to get it to work as we'd like it to using the configuration options provided?

Also, maybe some more explanation of what "checkTimer" and "idleCutoff" are doing (or should be doing? It doesn't really seem to wait for 10 minutes for me for the refresh when not in the app) would be helpful. If you can guide me to a better understanding, I'll gladly update the docs for you.

Mostly only cordova

My refactor broke web reloading :) We can use this method of making the api callable from outside cordova:

https://github.com/meteor/mobile-packages/blob/master/packages/mdg:reload-on-resume/browser.js
https://github.com/meteor/mobile-packages/blob/master/packages/mdg:reload-on-resume/package.js

Would this work with 1.8.2

Hi, would this package work with 1.8.2?

The instruction are:

meteor add jamielob:reloader
meteor remove mdg:reload-on-resume

mdg:reload-on-resume package no longer exists, and I believe is replaced with:

reload

Should reload be removed then?

Namespace the blaze helper

{{#if Reloader.updateAvailable}} or something

Need to call WebAppLocalServer.switchToPendingVersion when reloading?

I came across issues with Android not updating to the HCP after calling Reloader.reload() (working fine with iOS).
I found out later, having updated cordova-plugin-meteor-webapp (to 1.6.5) since 1.6.1, WebAppLocalServer.switchToPendingVersion has been introduced. The changelog for Meteor 1.8.1 also mentioned to use this if using a third party package to handle HCP. Refer to this comment which summarises.

I've currently got a workaround for this when we want to call Reloader.reload():
WebAppLocalServer.switchToPendingVersion(() => { Reloader.reload() })

What I want to raise is should there be a fix to address this?

Version 2

I need to unify the language between the words "Refresh" and "Reload" as they are both used interchangeably at the moment.

I think that Reload is the better term so I propose that I change any references to refresh to reload.

cc: @lorensr for comments.

Short-circuit downloadDelay

https://github.com/jamielob/reloader/blob/master/packages/reloader/reloader.js#L42-L63

Timer should be worst-case – can also have an autorun that does it immediately on updateAvailable true

reload not working in android, works in ios. what am i doing wrong?

this is my configuration

Reloader.configure({
check: 'firstStart', // Only make an additional check the first time the app ever starts
checkTimer: 3000, // Wait 3 seconds to see if new code is available on first start
refresh: 'startAndResume', // Refresh to already downloaded code on both start and resume
});

[FIXED] Only first code push is recognized

This is not specific to this package and I've submitted a PR to the Meteor Autoupdate package that will fix this:

meteor/meteor#6819

Question compatibility Meteor 1.6.1

Hi,

is this package still ok with the changes in Meteor 1.6.1 ? I knwo there have been important changes in cordova-plugin-meteor-webapp

Tx

Seems to get hung up on load screen occasionally

Thanks for the package

Having some intermittent issues when I restarting, that app seems to get hung on the load screen. I have only seen this a few times.

As it's happening on mobile I don't really have much in the way of debug screens and have not managed to replicate when hooked up to XCode.

I was using this config:

Reloader.configure({
    check: 'everyStart', // Check for new code every time the app starts
    checkTimer: 3000,  // Wait 3 seconds to see if new code is available
    refresh: 'startAndResume', // Refresh to already downloaded code on both start and resume
    idleCutoff: 1000 * 60 * 10  // Wait 10 minutes before treating a resume as a start
}); 

Any thoughts pls?

Do we have to put Reloader.reload() in isCordova

Hi, do we have to put Reloader.reload() calls in a if (Meteor.isCordova) ?

I get the error Reloader.reload is not a function(…) when trying to run on the browser instead of location.reload() or location.replace(location.href