{"_id":"56d1f33900a2a70b00b365a1","user":"5526ca4cf69851170038b496","__v":0,"parentDoc":null,"project":"5526c95cf69851170038b48f","version":{"_id":"56d1f33700a2a70b00b3658e","project":"5526c95cf69851170038b48f","__v":2,"createdAt":"2016-02-27T19:04:23.946Z","releaseDate":"2016-02-27T19:04:23.946Z","categories":["56d1f33900a2a70b00b3658f","56d1f33900a2a70b00b36590","56d1f33900a2a70b00b36591","56d1f33900a2a70b00b36592","56d1f33900a2a70b00b36593","56d1f33900a2a70b00b36594","56d1f33900a2a70b00b36595","56d1f33900a2a70b00b36596","56d1f33900a2a70b00b36597","56d1f33900a2a70b00b36598","56d1f33900a2a70b00b36599","56d1f33900a2a70b00b3659a","571f9497ada30c34003b7cee"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta","version_clean":"2.0.0-beta","version":"2.0.0-beta"},"category":{"_id":"56d1f33900a2a70b00b36594","pages":["56d1f33900a2a70b00b3659b","56d1f33900a2a70b00b3659c","56d1f33900a2a70b00b3659d","56d1f33900a2a70b00b3659e","56d1f33900a2a70b00b3659f","56d1f33900a2a70b00b365a0","56d1f33900a2a70b00b365a1","56d1f33900a2a70b00b365a2","56d1f33900a2a70b00b365a3","56d1f33900a2a70b00b365a4","56d1f33900a2a70b00b365a5","56d1f33900a2a70b00b365a6","56d1f33900a2a70b00b365a7","56d1f33900a2a70b00b365a8","56d1f33900a2a70b00b365a9"],"__v":1,"project":"5526c95cf69851170038b48f","version":"56d1f33700a2a70b00b3658e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T15:43:37.809Z","from_sync":false,"order":4,"slug":"ionic-deploy","title":"Ionic Deploy"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-24T14:57:50.100Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"At this point, you should already have the necessary [components setup](doc:deploy-install), and now you're ready to start laying down some code to use Ionic Deploy. Let's dive in!\n\n1. [Checking for updates](#section-check-for-updates)\n2. [Updating your app](#section-updating-your-app)\n3. [Manually download updates](#section-manually-download-updates)\n4. [Manually apply updates](#section-manually-apply-updates)\n5. [Reloading the app](#section-reloading-the-app)\n6. [Watching for Updates](#section-watching-for-updates)\n\nFurther reading:\n\n1. [Getting deploy info](#section-getting-deploy-info)\n2. [Choosing a deploy channel](#section-choosing-a-deploy-channel)\n3. [Version Management](#section-version-management)\n4. [Metadata](#section-metadata)\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Check for updates\n\nThe first thing any app is going to want to know when using Ionic Deploy is if there are any updates. This is easily accomplished using the `deploy.check` function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.check().then(function(isDeployAvailable) {\\n  // isDeployAvailable will be true if there is an update\\n  // and false otherwise\\n}, function(deployCheckError) {\\n  // unable to check for deploy updates\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The *check* function returns a promise, so make sure you don't try to just check against the immediate return value, or it will always be true.\",\n  \"title\": \"Notice\"\n}\n[/block]\nBy default, *check* will look for updates in the Production [deploy channel](doc:deploy-channels). You can learn how to change the channel that is used [here](#section-choosing-a-deploy-channel).\n\nIf an update is available, you may wish to look at the [metadata](#section-metadata) for that update.\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Updating your app\n\nSo you've got a new update [deployed](doc:deploy-deploying-updates), and you want to download and install that new version on your device with as little code as possible. Don't worry; we've got your back with the `deploy.update` function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.update().then(function(deployResult) {\\n  // deployResult will be true when successfull and\\n  // false otherwise\\n}, function(deployUpdateError) {\\n  // fired if we're unable to check for updates or if any \\n  // errors have occured.\\n}, function(deployProgress) {\\n  // this is a progress callback, so it will be called a lot\\n  // deployProgress will be an Integer representing the current\\n  // completion percentage.\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThis is definitely a shortcut function, and therefore takes a lot of the decision making out of your hands, but it's incredibly simple to use. \n\nSome things you'll want to be aware of:\n\n1. The *update* function returns a promise and makes use of the other deploy methods under the hood.\n2. A *check* is performed first, so you could potentially skip calling check() yourself and just attempting an update.\n3. Once the update is applied, the app will automatically reload. If you want to control each step of the update, you should look at the other deploy functions.\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Manually download updates\n\nIf you're looking for more control over how updates are applied to your app, this is the first place to start. If you've previously successfully checked that an [update is available](#section-checking-for-updates), you can use `deploy.download` to fetch the latest update, which you can later use to [apply](#section-manually-apply-updates) an update.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.download().then(function() {\\n  // called when the download has completed successfully\\n}, function(deployDownloadError) {\\n  // called when an error occurs\\n}, function(deployDownloadProgress) {\\n  // this is a progress callback, so it will be called a lot\\n  // deployDownloadProgress will be an Integer representing the current\\n  // completion percentage.\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Manually apply updates\n\nOnce you have successfully [downloaded](#section-manually-download-updates) an update, you can then apply that update using `deploy.extract`. As the name implies, this will extract the compressed update, which will, in effect, apply the update as the latest version. The next time the app is reloaded, it will use the latest update.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.extract().then(function() {\\n  // called when the extraction completes succesfully\\n}, function(error) {\\n  // called when an error occurs\\n}, function(deployExtractionProgress) {\\n  // this is a progress callback, so it will be called a lot\\n  // deployExtractionProgress will be an Integer representing the current\\n  // completion percentage.\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Reloading the app\n\nIf you have manually [downloaded](#section-manually-download-updates) and [applied](#section-manually-apply-updates) an update, you may wish to reload the app directly, instead of waiting for the app to be closed and re-opened to load the latest changes to your app.\n\nTo do this, we'll use the `deploy.load` function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = Ionic.Deploy();\\ndeploy.load();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThat's it! Whenever load is called, a reload will be issued. This will interrupt any actions your app is currently performing, so it's a good idea to let the user know that the app is about to reload before calling this.\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Watching for updates\n\nIf you provide frequent enough updates, you may wish to automatically watch for updates. This can be useful for notifying your users that a new update is available while they are using the app. This can be done using the `deploy.watch` function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.watch().then(function() {}, function() {}, function(deployUpdateAvailable) {\\n  // triggered upon each periodic check for updates.\\n  // deployUpdateAvailable will be true if an update is available\\n  // otherwise it will be false\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou'll notice that *watch* returns a promise like most of the `deploy` functions, but the only callback that is fired is the progress callback. This is called any time an update is periodically checked for.\n\n## Stop watching for updates\n\nIf you want to stop looking for updates automatically you can call `deploy.unwatch`. This stops the automatic checks when using `deploy.watch`. You can later resume automatic updates by calling watch again.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// stop watching for deploy updates\\ndeploy.unwatch();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Getting deploy info\n\nYou can find information about the currently deployed version using the `deploy.info` function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.info().then(function(deployInfo) {\\n  // deployInfo will be a JSON object that contains\\n  // information relating to the latest update deployed\\n  // on the device\\n}, function() {}, function() {});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Choosing a deploy channel\n\nIf you'd like to take advantage of different update channels, you'll need to tell your app which channel to pull updates from. You can do that using the `deploy.setChannel` function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\n\\n// \\\"dev\\\" is the channel tag for the Dev channel.\\ndeploy.setChannel(\\\"dev\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n*setChannel* takes a single argument, which is the [channel tag](doc:deploy-channels#channel-tags) you'll want to check against for updates. \n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Important\",\n  \"body\": \"After you use *setChannel*, all deploy activity will reference the channel tag provided, until you set a new channel. However, the channel is tied to the specific instantiation of the deploy service. You'll need to make sure you set the channel anywhere you instantiate the deploy service.\"\n}\n[/block]\n## Version Management\n\nBy default deploy will keep a few deploys on the device so rollbacks will not require re-downloading the update. This can be a problem for larger apps that take up a lot of device space. \n\nYou can get a list of deploy UUIDs (versions) on the device using `deploy.getVersions`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.getVersions().then(function(versions) {\\n  // versions will be an array of deploy uuids -- the order is NOT\\n  // in any specific order, and should not be relied upon to be the\\n  // same as any previous check.\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou can delete unwanted versions using the `deploy.deleteVersion` method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.deleteVersion(\\\"deploy-uuid-string\\\").then(function() {\\n  // success\\n}, function() {\\n\\t// error\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Metadata\n\nYou can get the metadata for a deploy version (if you provided any) for a deploy by using the  `deploy.getMetadata` method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.getMetadata(\\\"deploy-uuid-string\\\").then(function(metadata) {\\n  // metadata will be a JSON object\\n}, function() {}, function() {});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf you want to use metadata to show something like release notes before you have downloaded and applied the update, you'll want to do a two step process. You'll first want to check that an update is available, and if it is, then you can fetch the metadata for that pending update by omitting a uuid from the `getMetadata` call, like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var deploy = new Ionic.Deploy();\\ndeploy.check().then(function(isDeployAvailable) {\\n  if (isDeployAvailable) {\\n    deploy.getMetadata().then(function(metadata) {\\n  \\t\\t// metadata will be a JSON object\\n\\t\\t}, function() {}, function() {});\\n  }\\n}, function(deployCheckError) {\\n  // unable to check for deploy updates\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"Guide to writing code to use Ionic Deploy","slug":"deploy-usage","type":"basic","title":"Usage"}

Usage

Guide to writing code to use Ionic Deploy

At this point, you should already have the necessary [components setup](doc:deploy-install), and now you're ready to start laying down some code to use Ionic Deploy. Let's dive in! 1. [Checking for updates](#section-check-for-updates) 2. [Updating your app](#section-updating-your-app) 3. [Manually download updates](#section-manually-download-updates) 4. [Manually apply updates](#section-manually-apply-updates) 5. [Reloading the app](#section-reloading-the-app) 6. [Watching for Updates](#section-watching-for-updates) Further reading: 1. [Getting deploy info](#section-getting-deploy-info) 2. [Choosing a deploy channel](#section-choosing-a-deploy-channel) 3. [Version Management](#section-version-management) 4. [Metadata](#section-metadata) [block:api-header] { "type": "basic" } [/block] ## Check for updates The first thing any app is going to want to know when using Ionic Deploy is if there are any updates. This is easily accomplished using the `deploy.check` function. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.check().then(function(isDeployAvailable) {\n // isDeployAvailable will be true if there is an update\n // and false otherwise\n}, function(deployCheckError) {\n // unable to check for deploy updates\n});", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "body": "The *check* function returns a promise, so make sure you don't try to just check against the immediate return value, or it will always be true.", "title": "Notice" } [/block] By default, *check* will look for updates in the Production [deploy channel](doc:deploy-channels). You can learn how to change the channel that is used [here](#section-choosing-a-deploy-channel). If an update is available, you may wish to look at the [metadata](#section-metadata) for that update. [block:api-header] { "type": "basic" } [/block] ## Updating your app So you've got a new update [deployed](doc:deploy-deploying-updates), and you want to download and install that new version on your device with as little code as possible. Don't worry; we've got your back with the `deploy.update` function. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.update().then(function(deployResult) {\n // deployResult will be true when successfull and\n // false otherwise\n}, function(deployUpdateError) {\n // fired if we're unable to check for updates or if any \n // errors have occured.\n}, function(deployProgress) {\n // this is a progress callback, so it will be called a lot\n // deployProgress will be an Integer representing the current\n // completion percentage.\n});", "language": "javascript" } ] } [/block] This is definitely a shortcut function, and therefore takes a lot of the decision making out of your hands, but it's incredibly simple to use. Some things you'll want to be aware of: 1. The *update* function returns a promise and makes use of the other deploy methods under the hood. 2. A *check* is performed first, so you could potentially skip calling check() yourself and just attempting an update. 3. Once the update is applied, the app will automatically reload. If you want to control each step of the update, you should look at the other deploy functions. [block:api-header] { "type": "basic" } [/block] ## Manually download updates If you're looking for more control over how updates are applied to your app, this is the first place to start. If you've previously successfully checked that an [update is available](#section-checking-for-updates), you can use `deploy.download` to fetch the latest update, which you can later use to [apply](#section-manually-apply-updates) an update. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.download().then(function() {\n // called when the download has completed successfully\n}, function(deployDownloadError) {\n // called when an error occurs\n}, function(deployDownloadProgress) {\n // this is a progress callback, so it will be called a lot\n // deployDownloadProgress will be an Integer representing the current\n // completion percentage.\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic" } [/block] ## Manually apply updates Once you have successfully [downloaded](#section-manually-download-updates) an update, you can then apply that update using `deploy.extract`. As the name implies, this will extract the compressed update, which will, in effect, apply the update as the latest version. The next time the app is reloaded, it will use the latest update. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.extract().then(function() {\n // called when the extraction completes succesfully\n}, function(error) {\n // called when an error occurs\n}, function(deployExtractionProgress) {\n // this is a progress callback, so it will be called a lot\n // deployExtractionProgress will be an Integer representing the current\n // completion percentage.\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic" } [/block] ## Reloading the app If you have manually [downloaded](#section-manually-download-updates) and [applied](#section-manually-apply-updates) an update, you may wish to reload the app directly, instead of waiting for the app to be closed and re-opened to load the latest changes to your app. To do this, we'll use the `deploy.load` function. [block:code] { "codes": [ { "code": "var deploy = Ionic.Deploy();\ndeploy.load();", "language": "javascript" } ] } [/block] That's it! Whenever load is called, a reload will be issued. This will interrupt any actions your app is currently performing, so it's a good idea to let the user know that the app is about to reload before calling this. [block:api-header] { "type": "basic" } [/block] ## Watching for updates If you provide frequent enough updates, you may wish to automatically watch for updates. This can be useful for notifying your users that a new update is available while they are using the app. This can be done using the `deploy.watch` function. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.watch().then(function() {}, function() {}, function(deployUpdateAvailable) {\n // triggered upon each periodic check for updates.\n // deployUpdateAvailable will be true if an update is available\n // otherwise it will be false\n});", "language": "javascript" } ] } [/block] You'll notice that *watch* returns a promise like most of the `deploy` functions, but the only callback that is fired is the progress callback. This is called any time an update is periodically checked for. ## Stop watching for updates If you want to stop looking for updates automatically you can call `deploy.unwatch`. This stops the automatic checks when using `deploy.watch`. You can later resume automatic updates by calling watch again. [block:code] { "codes": [ { "code": "// stop watching for deploy updates\ndeploy.unwatch();", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic" } [/block] ## Getting deploy info You can find information about the currently deployed version using the `deploy.info` function. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.info().then(function(deployInfo) {\n // deployInfo will be a JSON object that contains\n // information relating to the latest update deployed\n // on the device\n}, function() {}, function() {});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic" } [/block] ## Choosing a deploy channel If you'd like to take advantage of different update channels, you'll need to tell your app which channel to pull updates from. You can do that using the `deploy.setChannel` function. [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\n\n// \"dev\" is the channel tag for the Dev channel.\ndeploy.setChannel(\"dev\");", "language": "javascript" } ] } [/block] *setChannel* takes a single argument, which is the [channel tag](doc:deploy-channels#channel-tags) you'll want to check against for updates. [block:callout] { "type": "danger", "title": "Important", "body": "After you use *setChannel*, all deploy activity will reference the channel tag provided, until you set a new channel. However, the channel is tied to the specific instantiation of the deploy service. You'll need to make sure you set the channel anywhere you instantiate the deploy service." } [/block] ## Version Management By default deploy will keep a few deploys on the device so rollbacks will not require re-downloading the update. This can be a problem for larger apps that take up a lot of device space. You can get a list of deploy UUIDs (versions) on the device using `deploy.getVersions`: [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.getVersions().then(function(versions) {\n // versions will be an array of deploy uuids -- the order is NOT\n // in any specific order, and should not be relied upon to be the\n // same as any previous check.\n});", "language": "javascript" } ] } [/block] You can delete unwanted versions using the `deploy.deleteVersion` method: [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.deleteVersion(\"deploy-uuid-string\").then(function() {\n // success\n}, function() {\n\t// error\n});", "language": "javascript" } ] } [/block] ## Metadata You can get the metadata for a deploy version (if you provided any) for a deploy by using the `deploy.getMetadata` method: [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.getMetadata(\"deploy-uuid-string\").then(function(metadata) {\n // metadata will be a JSON object\n}, function() {}, function() {});", "language": "javascript" } ] } [/block] If you want to use metadata to show something like release notes before you have downloaded and applied the update, you'll want to do a two step process. You'll first want to check that an update is available, and if it is, then you can fetch the metadata for that pending update by omitting a uuid from the `getMetadata` call, like so: [block:code] { "codes": [ { "code": "var deploy = new Ionic.Deploy();\ndeploy.check().then(function(isDeployAvailable) {\n if (isDeployAvailable) {\n deploy.getMetadata().then(function(metadata) {\n \t\t// metadata will be a JSON object\n\t\t}, function() {}, function() {});\n }\n}, function(deployCheckError) {\n // unable to check for deploy updates\n});", "language": "javascript" } ] } [/block]