Hello everyone! :smiley:

What do you want here, Daniel, you ask? Thank you for asking, to put it simply:


If we find some good answers / hints, I’ll gladly reformat this later on or try to piece it together to one helpful FAQ (or maybe an article for the guide / a readme somewhere or somesuch).

I am but a humble developer from Germany. For many summers I am developing for / with Meteor now.

Most of the systems and mechanisms I know well enough to be dangerous (and sometimes even helpful) or, if not, know that I can find all the documentation and/or forum posts, Git-Issue-Tickets, Stack-Overflow-Pages or what have you.

The one thing which seems to elude me almost completely is - the “Hot Code Push” (aka “HCP”), especially in as used in Cordova™ - Apps.

The docs I can find so far all seem to tell me “It just works™” (Meteor Guide - Hot Code Push), but there doesn’t seem to be anything about how the underlying mechanism actually works, fully, from end to end.

Every time I read it I get a bit confused, anxious and feel bad because it feels like it’s something I should already know:

Controlling compatibility version:
The compatibility version can be found in the cordovaCompatibilityVersions attribute of the JSON file served at ROOT_URL/__cordova/manifest.json during meteor run [ios/android] .

You may want to override the compatibility version if you want hot code push to reach older apps that don’t have the latest version of your native code from the app store. Let’s say you’re developing an iOS app, you have the plugin cordova-plugin-camera@2.4.0 , and your app has the compatibility version pictured above, 3ed5b9318b2916b595f7721759ead4d708dfbd46 . If you were to update to version 2.4.1 of cordova-plugin-camera , your server would generate a new compatibility version and your users’ apps would stop receiving hot code pushes. However, you can tell your server to use the old compatilibity version:

METEOR_CORDOVA_COMPAT_VERSION_IOS=3ed5b9318b2916b595f7721759ead4d708dfbd46 meteor run ios-device
# or
METEOR_CORDOVA_COMPAT_VERSION_IOS=3ed5b9318b2916b595f7721759ead4d708dfbd46 meteor build ../build --server=

… one moment please, I should what the what now? :smiley:

How do I know my old compatibility version when I’m building the new version of my app at the moment? Should I keep tabs after building each released version about the compatibility versions for ios + android? What if I didn’t do it? And the version created locally with meteor run ios/android is the same as the one on my live server? What if I upload a new Build of my server? Is the compatibility version the same? Aah, I guess I pass in the previous’ versions version string to the new build using the (undocumented) environment variable?

-> There just doesn’t seem to be enough information about the whole process around / documented.

Q: What are all the other asset information (hashes) in __cordova/manifest.json in my App used for? Is it possible that the HCP would fail if any of those resources would change too? -> Because that is the impression that I get, I have the feeling the HCP doesn’t work more often than it does… (see eg. Git Issues: “Cordova iOS HCP fails if you add a png to your project”)

There is also something about the “blacklisting” of versions. Mmh, i’d rather not…? I have the feeling this mostly serves to break the upgrade process because the webapp - / HCP - plugin things we have an incompatible update for some reason - are you sure this isn’t connected to the asset manifest above, dear Guide? (It says a new Versions gets blacklistet if it fails to start multiple times).

Q: How do I control the process / fix my app after the fact (after a new version has shipped / I don’t know all my hashes?) so my clients get the newest version when I want them to?

In another Github Issue (Hot Code Push broken on iOS) we get a hint of an interesting possible solution:

meteor build / deploy (...)
  • setting this before both the mobile clients + the server build. (Where is this documented please?!)

Sounds great! :slight_smile: This way we could control the updates ourselves… or could we?

Q: Is this really all there is to it? Can we be 100% sure that the HCP will always run if we build a new version of the server whilst keeping the METEOR_CORDOVA_COMPAT_VERSION_* the same? Because I have the feeling there might be more issues / things lurking underneath the surface?

Next question: In the client I can see some information about autoupdate versions:

… but what does it all mean? What is a versionNotRefreshable? What’s versionRefreshable? And what is version? And why are they all different? How can I use this? Where is my SET METEOR_CORDOVA_COMPAT_VERSION_ANDROID=v0001 I so painstakingly tried to set? :smiley:

On the client:

There is this cool plugin that lets me hold back / control the update process a bit:


-> But there isn’t anything about “Is my HCP foobar’d” or “Fxxx it do it anyway / try again from the start of the process” or anything which might help me salvage an app once it crossed the no-HCP-Rubicon. Which kind of sucks, because then I can start building + deploying a new app, upload it, fix some issue with a new deprecated this-or-that apple figured out, build once more, wait for Testflight to gimme a green light, create a new release & wait about 2 1/2 days until my clients get the much-needed hotfix…

  • what’s with Meteors’ own reload package? -> I think it mostly takes care of keeping Session variables around and doesn’t seem to be too related to the discussion I think.

Q: Can I recover somewhere from the client if anything goes wrong here?

So, this was a lot of rambling. This is my knowledge to this point. I think it’s not enough and it feels bad. I want to be able to tell my clients when the update will go live & be reasonably sure that it’ll actually work this time.

I want to know what’s happening under the hood and be able to fix simple issues using either the server or the client by either pushing a new version with some additional data or let the client retry the HCP reload now and then.

PLEASE add all you knowledge to get me on the road to HCP nirvana. I’m happy if it turns out I’m the only one not knowing where this is all written up in the docs… :slight_smile:

I think this is a great and valuable feature to have, if used responsibly, but for that to work we need to be able to rely on it.

If there isn’t a lot of progress here I’ll start source diving, but I hope to get some initial pointers here at least. I think this is a topic of broader interest.

Thanks & bye! :slight_smile:

:apple: :pear: :grapes::tangerine::banana::pineapple::cherries::kiwi_fruit: <- Some healthy snacks for you if you read this far! :slight_smile:


Hi, any takers?

-> Basically I am looking for all links, Blog-Posts, Docs, Snippets & other Pointers regarding the hot code push… do you have some resources connected to Meteor and the HCP? Then please post it here, even if it’s rough or maybe a bit outdated…

1 Like

What kind of links, blog and docs are you looking? Can you please tell us in details. I really want to help you.

Hello Adam! :slight_smile:

Nice to read you! :slight_smile:

Basically everything pertaining to the HCP mechanics, how to use them and how to prevent errors.

I have a hard time controlling the population of App versions in the wild basically…

nice FAQ!


on server this env var has to be around at build time, not at run time, so if you need to change that value, you have to rebuild the server. Most other environment-variables just need a restart of the server, because they are read via process.env, but the cordova-manifest is generated on build time, its just a file in the server-bundle.

Great work @DanielDornhardt, what do you think about you starting a PR against docs.meteor.com?

We could add an entry in the main menu under packages for https://github.com/meteor/cordova-plugin-meteor-webapp with all these details. I for sure can review and help you with that too.

Does that sound good?