1 | [![appcenterbanner](https://user-images.githubusercontent.com/31293287/32969262-3cc5d48a-cb99-11e7-91bf-fa57c67a371c.png)](http://microsoft.github.io/code-push/)
|
2 |
|
3 | #### [Sign up With App Center](https://appcenter.ms/signup?utm_source=CodePush&utm_medium=Azure) to use CodePush
|
4 |
|
5 | # CodePush
|
6 |
|
7 | [CodePush](https://microsoft.github.io/code-push) is a cloud service that enables Cordova and React Native developers to deploy mobile app updates directly to their users' devices. It works by acting as a central repository that developers can publish updates to (JS, HTML, CSS and images), and that apps can query for updates from (using provided client SDK for [Cordova](https://github.com/Microsoft/cordova-plugin-code-push) and [React Native](https://github.com/Microsoft/react-native-code-push)). This allows you to have a more deterministic and direct engagement model with your userbase, when addressing bugs and/or adding small features that don't require you to re-build a binary and re-distribute it through the respective app stores.
|
8 |
|
9 | To get started using CodePush, refer to our [documentation](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/), otherwise, read the following steps if you'd like to build/contribute to the project from source.
|
10 |
|
11 | *NOTE: If you need information about [code-push management CLI](https://github.com/microsoft/code-push/tree/v3.0.1/cli), you can find it in v3.0.1.*
|
12 |
|
13 | ## Dev Setup
|
14 |
|
15 | * Install [Node.js](https://nodejs.org/)
|
16 | * Install [Git](http://www.git-scm.com/)
|
17 | * Clone the Repository: `git clone https://github.com/Microsoft/code-push.git`
|
18 |
|
19 | ### Building
|
20 |
|
21 | * Run `npm run setup` to install the NPM dependencies of management SDK.
|
22 | * Run `npm run build` to build the management SDK for testing.
|
23 | * Run `npm run build:release` to build the release version of management SDK.
|
24 |
|
25 | ### Running Tests
|
26 |
|
27 | * To run tests, run `npm run test` from the root of the project.
|
28 | * You can use debug mode for tests with `.vscode/launch.json` file.
|
29 |
|
30 | ### Coding Conventions
|
31 |
|
32 | * Use double quotes for strings
|
33 | * Use four space tabs
|
34 | * Use `camelCase` for local variables and imported modules, `PascalCase` for types, and `dash-case` for file names
|
35 |
|
36 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
37 |
|
38 | # CodePush Management SDK (Node.js)
|
39 |
|
40 | A JavaScript library for programmatically managing your CodePush account (e.g. creating apps, promoting releases), which allows authoring Node.js-based build and/or deployment scripts, without needing to shell out to the [App Center CLI](https://github.com/microsoft/appcenter-cli).
|
41 |
|
42 | ## Getting Started
|
43 |
|
44 | 1. Create a token to authenticate with the CodePush server using the following [App Center CLI](https://github.com/microsoft/appcenter-cli) command:
|
45 |
|
46 | ```shell
|
47 | appcenter tokens create -d "DESCRIPTION_OF_THE_TOKEN"
|
48 | ```
|
49 |
|
50 | Please copy your `API Token` and keep it secret. You won't be able to see it again.
|
51 |
|
52 | 2. Install the management SDK by running `npm install code-push --save`
|
53 |
|
54 | 3. Import it using one of the following statement: (using ES6 syntax as applicable):
|
55 | * On commonjs environments:
|
56 |
|
57 | ```javascript
|
58 | const CodePush = require("code-push");
|
59 | ```
|
60 |
|
61 | * Using ES6 syntax with tsconfig.json:
|
62 |
|
63 | ```javascript
|
64 | import CodePush from "code-push";
|
65 | ```
|
66 |
|
67 | 4. Create an instance of the `CodePush` class, passing it the `API Token` you created or retrieved in step #1:
|
68 |
|
69 | ```javascript
|
70 | const codePush = new CodePush("YOUR_API_TOKEN");
|
71 | ```
|
72 |
|
73 | 5. Begin automating the management of your account! For more details on what you can do with this `codePush` object, refer to the API reference section below.
|
74 |
|
75 | ## API Reference
|
76 |
|
77 | The `code-push` module exports a single class (typically referred to as `CodePush`), which represents a proxy to the CodePush account management REST API. This class has a single constructor for authenticating with the CodePush service, and a collection of instance methods that correspond to the commands in the [App Center CLI](https://github.com/microsoft/appcenter-cli), which allow you to programmatically control every aspect of your CodePush account.
|
78 |
|
79 | ### Constructors
|
80 |
|
81 | * __CodePush(accessKey: string)__ - Creates a new instance of the CodePush management SDK, using the specified access key to authenticated with the server.
|
82 |
|
83 | ### Methods
|
84 |
|
85 | *Note: `access key` here refers to an AppCenter API Token.*
|
86 |
|
87 | * __addAccessKey(description: string): Promise<AccessKey>__ - Creates a new access key with the specified description (e.g. "VSTS CI").
|
88 |
|
89 | * __addApp(name: string, os: string, platform: string, manuallyProvisionDeployments: boolean = false): Promise<App>__ - Creates a new CodePush app with the specified name, os, and platform. If the default deployments of "Staging" and "Production" are not desired, pass a value of true for the manuallyProvisionDeployments parameter.
|
90 |
|
91 | * __addCollaborator(appName: string, email: string): Promise<void>__ - Adds the specified CodePush user as a collaborator to the specified CodePush app.
|
92 |
|
93 | * __addDeployment(appName: string, deploymentName: string): Promise<Deployment>__ - Creates a new deployment with the specified name, and associated with the specified app.
|
94 |
|
95 | * __clearDeploymentHistory(appName: string, deploymentName: string): Promise<void>__ - Clears the release history associated with the specified app deployment.
|
96 |
|
97 | * __getAccessKey(accessKey: string): Promise<AccessKey>__ - Retrieves the metadata about the specific access key.
|
98 |
|
99 | * __getAccessKeys(): Promise<AccessKey[]>__ - Retrieves the list of access keys associated with your CodePush account.
|
100 |
|
101 | * __getApp(appName: string): Promise<App>__ - Retrieves the metadata about the specified app.
|
102 |
|
103 | * __getApps(): Promise<App[]>__ - Retrieves the list of apps associated with your CodePush account.
|
104 |
|
105 | * __getCollaborators(appName: string): Promise<CollaboratorMap>__ - Retrieves the list of collaborators associated with the specified app.
|
106 |
|
107 | * __getDeployment(appName: string, deploymentName: string): Promise<Deployment>__ - Retrieves the metadata for the specified app deployment.
|
108 |
|
109 | * __getDeploymentHistory(appName: string, deploymentName: string): Promise<Package[]>__ - Retrieves the list of releases that have been made to the specified app deployment.
|
110 |
|
111 | * __getDeploymentMetrics(appName: string, deploymentName: string): Promise<DeploymentMetrics>__ - Retrieves the installation metrics for the specified app deployment.
|
112 |
|
113 | * __getDeployments(appName: string): Promise<Deployment[]>__ - Retrieves the list of deployments associated with the specified app.
|
114 |
|
115 | * __patchRelease(appName: string, deploymentName: string, label: string, updateMetadata: PackageInfo): Promise<void>__ - Updates the specified release's metadata with the given information.
|
116 |
|
117 | * __promote(appName: string, sourceDeploymentName: string, destinationDeploymentName: string, updateMetadata: PackageInfo): Promise<Package>__ - Promotes the latest release from one deployment to another for the specified app and updates the release with the given metadata.
|
118 |
|
119 | * __release(appName: string, deploymentName: string, updateContentsPath: string, targetBinaryVersion: string, updateMetadata: PackageInfo): Promise<Package>__ - Releases a new update to the specified deployment with the given metadata.
|
120 |
|
121 | * __removeAccessKey(accessKey: string): Promise<void>__ - Removes the specified access key from your CodePush account.
|
122 |
|
123 | * __removeApp(appName: string): Promise<void>__ - Deletes the specified CodePush app from your account.
|
124 |
|
125 | * __removeCollaborator(appName: string, email: string): Promise<void>__ - Removes the specified account as a collaborator from the specified app.
|
126 |
|
127 | * __removeDeployment(appName: string, deploymentName: string): Promise<void>__ - Removes the specified deployment from the specified app.
|
128 |
|
129 | * __renameApp(oldAppName: string, newAppName: string): Promise<void>__ - Renames an existing app.
|
130 |
|
131 | * __renameDeployment(appName: string, oldDeploymentName: string, newDeploymentName: string): Promise<void>__ - Renames an existing deployment within the specified app.
|
132 |
|
133 | * __rollback(appName: string, deploymentName: string, targetRelease?: string): Promise<void>__ - Rolls back the latest release within the specified deployment. Optionally allows you to target a specific release in the deployment's history, as opposed to rolling to the previous release.
|
134 |
|
135 | * __transferApp(appName: string, email: string): Promise<void>__ - Transfers the ownership of the specified app to the specified account.
|
136 |
|
137 | ### Error Handling
|
138 |
|
139 | When an error occurs in any of the methods, the promise will be rejected with a CodePushError object with the following properties:
|
140 |
|
141 | * __message__: A user-friendly message that describes the error.
|
142 | * __statusCode__: An HTTP response code that identifies the category of error:
|
143 | * __CodePush.ERROR_GATEWAY_TIMEOUT__: A network error prevented you from connecting to the CodePush server.
|
144 | * __CodePush.ERROR_INTERNAL_SERVER__: An error occurred internally on the CodePush server.
|
145 | * __CodePush.ERROR_NOT_FOUND__: The resource you are attempting to retrieve does not exist.
|
146 | * __CodePush.ERROR_CONFLICT__: The resource you are attempting to create already exists.
|
147 | * __CodePush.ERROR_UNAUTHORIZED__: The access key you configured is invalid or expired.
|