A NativeScript app is composed of XML/HTML, CSS and JavaScript files and any accompanying images, which are bundled together by the NativeScript CLI and distributed as part of a platform-specific binary (i.e. an .ipa or .apk file). Once the app is released, updating either the code (e.g. making bug fixes, adding new features) or image assets, requires you to recompile and redistribute the entire binary, which of course, includes any review time associated with the store(s) you are publishing to.

The AppSync plugin helps get product improvements in front of your end users instantly, by keeping your code and images synchronized with updates you release to the AppSync server. This way, your app gets the benefits of an offline mobile experience, as well as the "web-like" agility of side-loading updates as soon as they are available. It's a win-win!

In order to ensure that your end users always have a functioning version of your app, the AppSync plugin maintains a copy of the previous update, so that in the event that you accidentally push an update which includes a crash, it can automatically roll back. This way, you can rest assured that your newfound release agility won't result in users becoming blocked before you have a chance to roll back on the server. It's a win-win-win!

Architectural overview of the solution - you don't need to worry about all of this

1. If a user is running an older binary version, it's possible that there are breaking changes in the AppSync update that wouldn't be compatible with what they're running.

2. If a user is running a newer binary version, then it's presumed that what they are running is newer (and potentially incompatible) with the AppSync update.

If you ever want an update to target multiple versions of the app store binary, we also allow you to specify the parameter as a semver range expression. That way, any client device running a version of the binary that satisfies the range expression (i.e. semver.satisfies(version, range) returns true) will get the update. Examples of valid semver range expressions are as follows:

*NOTE: If your semver expression starts with a special shell character or operator such as >, ^, or ** , the command may not execute correctly if you do not wrap the value in quotes as the shell will not supply the right values to our CLI process. Therefore, it is best to wrap your targetBinaryVersion parameter in double quotes when calling the release command, e.g. app-sync release MyApp-iOS updateContents ">1.2.3".

NOTE: As defined in the semver spec, ranges only work for non pre-release versions: https://github.com/npm/node-semver#prerelease-tags. If you want to update a version with pre-release tags, then you need to write the exact version you want to update (1.2.3-beta for example).

The following table outlines the version value that AppSync expects your update's semver range to satisfy for each respective app type:

NOTE: If the app store version in the metadata files are missing a patch version, e.g. 2.0, it will be treated as having a patch version of 0, i.e. 2.0 -> 2.0.0. The same is true for app store version equal to plain integer number, 1 will be treated as 1.0.0 in this case.

You can update metadata by running the following command:

nativescript-app-sync patch <appName> <deploymentName>
[--label <releaseLabel>]
[--mandatory <isMandatory>]
[--description <description>]
[--targetBinaryVersion <targetBinaryVersion>]

⚠️ This command doesn't allow modifying the actual update contents of a release. If you need to respond to a release that has been identified as being broken, you should use the rollback command to immediately roll it back, and then if necessary, release a new update with the approrpriate fix when it is available.

Aside from the appName and deploymentName, all parameters are optional, and therefore, you can use this command to update just a single attribute or all of them at once. Calling the patch command without specifying any attribute flag will result in a no-op.

# Mark the latest production release as mandatory
nativescript-app-sync patch MyAppiOS Production -m

# Add a "mina and max binary version" to an existing release
nativescript-app-sync patch MyAppiOS Staging -t "1.0.0 - 1.0.5"

Once you've tested an update against a specific deployment (e.g. Staging), and you want to promote it (e.g. dev->staging, staging->production), you can simply use the following command to copy the release from one deployment to another:

nativescript-app-sync promote <appName> <sourceDeploymentName> <destDeploymentName>
[--description <description>]
[--label <label>]
[--mandatory]
[--targetBinaryVersion <targetBinaryVersion]

# example
nativescript-app-sync promote AppSyncDemoIOS Staging Production --description 'Promoted from Staging to Production'

The promote command will create a new release for the destination deployment, which includes the exact code and metadata (description, mandatory and target binary version) from the latest release of the source deployment. While you could use the release command to "manually" migrate an update from one environment to another, the promote command has the following benefits:

1. It's quicker, since you don't need to reassemble the release assets you want to publish or remember the description/app store version that are associated with the source deployment's release.

2. It's less error-prone, since the promote operation ensures that the exact thing that you already tested in the source deployment (e.g. Staging) will become active in the destination deployment (e.g. Production).

💁‍♂️ Unless you need to make changes to your code, the recommended workflow is taking advantage of the automatically created Staging and Production environments, and do all releases directly to Staging, and then perform a promote from Staging to Production after performing the appropriate testing.

A deployment's release history is immutable, so you cannot delete or remove individual updates once they have been released without deleting all of the deployment's release history. However, if you release an update that is broken or contains unintended features, it is easy to roll it back using the rollback command:

nativescript-app-sync rollback <appName> <deploymentName>

#example
nativescript-app-sync rollback MyAppiOS Production

This has the effect of creating a new release for the deployment that includes the exact same code and metadata as the version prior to the latest one. For example, imagine that you released the following updates to your app:

If you ran the rollback command on that deployment, a new release (v4) would be created that included the contents of the v2 release.

End-users that had already acquired v3 would now be "moved back" to v2 when the app performs an update check. Additionally, any users that were still running v2, and therefore, had never acquired v3, wouldn't receive an update since they are already running the latest release (this is why our update check uses the package hash in addition to the release label).

If you would like to rollback a deployment to a release other than the previous (e.g. v3 -> v2), you can specify the optional --targetRelease parameter:

nativescript-app-sync rollback MyAppiOS Production --targetRelease v34

⚠️ This rolls back the release to the previous AppSync version, NOT the AppStore version (if there was one in between).

💁‍♂️ The release produced by a rollback will be annotated in the output of the deployment history command to help identify them more easily.

If you will be working with other developers on the same AppSync app, you can add them as collaborators using the following command:

nativescript-app-sync collaborator add <appName> <collaboratorEmail>

NOTE: This expects the developer to have already registered with AppSync using the specified e-mail address, so ensure that they have done that before attempting to share the app with them.

Once added, all collaborators will immediately have the following permissions with regards to the newly shared app:

1. View the app, its collaborators, deployments and release history.
2. Release updates to any of the app's deployments.
3. Rollback any of the app's deployments

Inversely, that means that an app collaborator cannot do any of the following:

1. Rename or delete the app
2. Create, rename or delete new deployments within the app
3. Clear a deployment's release history
4. Add or remove collaborators from the app (although a developer can remove themself as a collaborator from an app that was shared with them).

Over time, if someone is no longer working on an app with you, you can remove them as a collaborator using the following command:

nativescript-app-sync collaborator rm <appName> <collaboratorEmail>

If at any time you want to list all collaborators that have been added to an app, you can simply run the following command:

nativescript-app-sync collaborator ls <appName>

nativescript-app-sync login --noProxy

I'd you like to explicitly specify a proxy server that the CLI should use, without relying on system-wide settings, you can instead pass the --proxy parameter when logging in:

nativescript-app-sync login --proxy https://foo.com:3454

Once you've logged in, any inferred and/or specified proxy settings are persisted along with your user session. This allows you to continue using the CLI without needing to re-authenticate or re-specify your preferred proxy. If at any time you want to start or stop using a proxy, simply logout, and then log back in with the newly desired settings.