Repository: cordova-docs Updated Branches: refs/heads/master fc1dbb28a -> a7aeefa34
Making windows guide single page. This closes #512 Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/a7aeefa3 Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/a7aeefa3 Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/a7aeefa3 Branch: refs/heads/master Commit: a7aeefa3451681d1b167fb9eaec7f75e7762a4ad Parents: fc1dbb2 Author: Raghav Katyal <[email protected]> Authored: Mon Feb 22 14:36:37 2016 -0800 Committer: Raghav Katyal <[email protected]> Committed: Mon Feb 22 15:12:59 2016 -0800 ---------------------------------------------------------------------- www/_data/redirects.yml | 2 + www/docs/en/dev/guide/platforms/win8/index.md | 70 ++++++++++ .../en/dev/guide/platforms/win8/packaging.md | 91 ------------- .../dev/guide/platforms/win8/win10-support.md | 127 ------------------- 4 files changed, 72 insertions(+), 218 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a7aeefa3/www/_data/redirects.yml ---------------------------------------------------------------------- diff --git a/www/_data/redirects.yml b/www/_data/redirects.yml index 6a43877..899ddb6 100644 --- a/www/_data/redirects.yml +++ b/www/_data/redirects.yml @@ -11,6 +11,8 @@ docs: - {old: "dev/guide/platforms/android/config.html", new: "dev/config_ref/index.html"} - {old: "dev/guide/platforms/ios/tools.html", new: "dev/guide/platforms/ios/index.html"} - {old: "dev/guide/platforms/ios/config.html", new: "dev/config_ref/index.html"} + - {old: "dev/guide/platforms/win8/packaging.html", new: "dev/guide/platforms/win8/index.html#signing-an-app"} + - {old: "dev/guide/platforms/win8/win10-support.html", new: "dev/guide/platforms/win8/index.html"} # redirects paths relative to /docs/XX/YYY/ docs-global: http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a7aeefa3/www/docs/en/dev/guide/platforms/win8/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/win8/index.md b/www/docs/en/dev/guide/platforms/win8/index.md index 71f3bee..54b6ab4 100644 --- a/www/docs/en/dev/guide/platforms/win8/index.md +++ b/www/docs/en/dev/guide/platforms/win8/index.md @@ -202,6 +202,73 @@ to the CLI. Visual Studio provides powerful tools to debug your application. You can refer to [this](https://msdn.microsoft.com/en-us/library/7seh8d72.aspx) article to get started with it. +## Signing an App + +You can learn more about signing and packaging of Windows Store Apps on [MSDN][1]. + +To be able to correctly package and sign Windows apps there are few things required: + +- A signing certificate +- Identity details matching the provided signing certificate + +In Windows project, identity details are kept in a file named package.appxmanifest. This file is automatically populated every time a Cordova app is built. Identity holds 3 important fields. + +- Name +- Publisher +- Version + +*Name* and *Version* can be set from **config.xml**. *Publisher* can be provided as a build parameter or can be set on **build.json** file. + + + +A signing certificate can be provided from either CLI or through build.json file. The certificate related CLI flags are: + +| Parameter | Flag | Description +|-----------------------|-------------------|----------------------------------- +| Certificate File | `--packageCertificateKeyFile` | Path to the package signing certificate to be associated with the app +| Thumb Print | `--packageThumbprint` | Used to validate the authenticity of package certificate key file. When creating a certificate key file, this value will be provided to the end user + +Example: +``` +cordova build -- --packageCertificateKeyFile="platforms\windows\CordovaApp_TemporaryKey.pfx" --packageThumbprint="ABCABCABCABC123123123123"` +``` + +Alternatively, these values could be specified using a build configuration file (build.json) using CLI (--buildConfig). A sample build configuration file: + + { + "windows": { + "debug": { + "packageCertificateKeyFile": "platforms\\windows\\CordovaApp_TemporaryKey.pfx" + }, + "release": { + "packageCertificateKeyFile": "c:\\path-to-key\\keycert.pfx", + "packageThumbprint": "ABCABCABCABC123123123123", + "publisherId": "CN=FakeCorp.com, L=Redmond, S=Washington, C=US" + } + } + } + +There is also support to mix and match command line arguments and parameters in build.json file. Values from the command line arguments will get precedence. + +### Creating a certificate key +Signing is required for distributing and installing Windows Store apps. This process is normally handled by Visual Studio when you deploy a package for release. To do this without Visual Studio we need to create our own certificates. [This](https://msdn.microsoft.com/en-us/library/windows/desktop/jj835832(v=vs.85).aspx) article has instructions on how to do that. + +Once you have the pfx file created and provided to build.json file, you might get the following error: "The key file may be password protected. To correct this, try to import the certificate manually into the current user's personal certificate store.". In order to import it you have to use [certutil][2] from an admin prompt: + +`certutil -user -p PASSWORD -importPFX FakeCorp.com.pfx` + +Where: + +- user : Specifies "current user" personal store +- p : Password for pfx file +- importPfx : Name of pfx file + +Once installed, next step is to add packageThumbprint and packageCertificateKeyFile to build.json. In order to find the packageThumbprint, search for the CommonName you've associated with the certificate: + +`powershell -Command " & {dir -path cert:\LocalMachine\My | where { $_.Subject -like \"*FakeCorp.com*\" }}"` + +Once these final values are provided. Cordova should successfully package and sign the app. + ## Platform Centered Workflow If you want to use Cordova's Windows-centered shell tools in conjunction with the SDK, you have two basic options: @@ -281,3 +348,6 @@ Each of the library restrictions may be worked around by requesting that the use The network-related restrictions must be worked around by either using an API that doesn't use capability checks or by brokering communication via standard internet communication channels, such as `XMLHttpRequest` or Web Sockets. The Enterprise Authentication and Shared User Certificates capabilities are specifically targeted at Enterprise scenarios. These capabilities are supported for private/enterprise-enabled App Stores, so if you are building apps which are going to be deployed to an internal deployment mechanism, you can still support these. However, they are not supported for Remote Mode apps in the public Windows Store. When you build targeting Windows 10, if one of these capabilities is detected in your app manifest, a warning will be displayed. + +[1]: https://msdn.microsoft.com/en-us/library/hh446593(v=vs.85).aspx +[2]: https://technet.microsoft.com/en-us/library/ee624045(v=ws.10).aspx \ No newline at end of file http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a7aeefa3/www/docs/en/dev/guide/platforms/win8/packaging.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/win8/packaging.md b/www/docs/en/dev/guide/platforms/win8/packaging.md deleted file mode 100644 index 8c8b48c..0000000 --- a/www/docs/en/dev/guide/platforms/win8/packaging.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Windows Packaging ---- - -# Signing an App - -You can learn more about signing and packaging of Windows Store Apps on [MSDN][1]. - -To be able to correctly package and sign Windows apps there are few things required: - -- A signing certificate -- Identity details matching the provided signing certificate - -In Windows project, identity details are kept in a file named package.appxmanifest. This file is automatically populated every time a Cordova app is built. Identity holds 3 important fields. - -- Name -- Publisher -- Version - -*Name* and *Version* can be set from **config.xml**. *Publisher* can be provided as a build parameter or can be set on **build.json** file. - - - -A signing certificate can be provided from either CLI or through build.json file. The certificate related CLI flags are: - -| Parameter | Flag | Description -|-----------------------|-------------------|----------------------------------- -| Certificate File | `--packageCertificateKeyFile` | Path to the package signing certificate to be associated with the app -| Thumb Print | `--packageThumbprint` | Used to validate the authenticity of package certificate key file. When creating a certificate key file, this value will be provided to the end user - -Example: -``` -cordova build -- --packageCertificateKeyFile="platforms\windows\CordovaApp_TemporaryKey.pfx" --packageThumbprint="ABCABCABCABC123123123123"` -``` - -Alternatively, these values could be specified using a build configuration file (build.json) using CLI (--buildConfig). A sample build configuration file: - - { - "windows": { - "debug": { - "packageCertificateKeyFile": "platforms\\windows\\CordovaApp_TemporaryKey.pfx" - }, - "release": { - "packageCertificateKeyFile": "c:\\path-to-key\\keycert.pfx", - "packageThumbprint": "ABCABCABCABC123123123123", - "publisherId": "CN=FakeCorp.com, L=Redmond, S=Washington, C=US" - } - } - } - -There is also support to mix and match command line arguments and parameters in build.json file. Values from the command line arguments will get precedence. - -## Creating a certificate key -Signing is required for distributing and installing Windows Store apps. This process is normally handled by Visual Studio when you deploy a package for release. To do this without Visual Studio we need to create our own certificates. [This](https://msdn.microsoft.com/en-us/library/windows/desktop/jj835832(v=vs.85).aspx) article has instructions on how to do that. - -Once you have the pfx file created and provided to build.json file, you might get the following error: "The key file may be password protected. To correct this, try to import the certificate manually into the current user's personal certificate store.". In order to import it you have to use [certutil][2] from an admin prompt: - -`certutil -user -p PASSWORD -importPFX FakeCorp.com.pfx` - -Where: - -- user : Specifies "current user" personal store -- p : Password for pfx file -- importPfx : Name of pfx file - -Once installed, next step is to add packageThumbprint and packageCertificateKeyFile to build.json. In order to find the packageThumbprint, search for the CommonName you've associated with the certificate: - -`powershell -Command " & {dir -path cert:\LocalMachine\My | where { $_.Subject -like \"*FakeCorp.com*\" }}"` - -Once these final values are provided. Cordova should successfully package and sign the app. - -[1]: https://msdn.microsoft.com/en-us/library/hh446593(v=vs.85).aspx -[2]: https://technet.microsoft.com/en-us/library/ee624045(v=ws.10).aspx http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a7aeefa3/www/docs/en/dev/guide/platforms/win8/win10-support.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/win8/win10-support.md b/www/docs/en/dev/guide/platforms/win8/win10-support.md deleted file mode 100644 index abb5b1b..0000000 --- a/www/docs/en/dev/guide/platforms/win8/win10-support.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Cordova for Windows 10 # ---- - -# Cordova for Windows 10 # -Maybe you could instead call it "Windows 10 for Cordova." Windows 10 has had its HTML and -JavaScript Apps platform re-engineered to bring Cordova support to the web, and to get -platform security restrictions out of your way. - -## Getting Started with Windows 10 ## -Adding Windows 10 support to your app is as easy as setting your Windows target platform -version to 10.0: - - <preference name="windows-target-version" value="10.0" /> - <preference name="windows-phone-target-version" value="10.0" /> - -When you build with these preferences both set, only a single .appx (and .appxupload) will -be built. They will require Windows 10 at a minimum. - -### Understanding Remote Mode vs. Local Mode ### -Remote Mode is a new feature of the HTML Applications for Windows platform in Windows 10. In -Windows 8.1, HTML Applications worked in what is called "Local Mode" in Windows 10. In -Local Mode, HTML Applications have full access to the native Windows API surface and -capabilities. In order to prevent script injection attacks which could result in leaking -personally-identifiable information due to malicious code, Local Mode disallows inline script, -and requires developers who perform DOM manipulation to do so within an explicit context -(`MSApp.execUnsafeLocalFunction`). - -Remote Mode eliminates those requirements, which makes it possible to use unmodified libraries like jQuery or AngularJS directly in your code, without any changes. To do so, it removes your ability to declare certain capabilities when certifying your app in the Windows Store. The removal of these capabilities usually doesn't prevent getting to certain functionality, but it might require to use a different combination of APIs or tactics. - -### Effect of Remote Mode on capabilities ### -The following capabilities are unavailable when deploying your Remote Mode application to the Windows Store: - -- Enterprise Authentication (`enterpriseAuthentication`) -- Shared User Certificates (`sharedUserCertificates`) -- Documents Library (`documentsLibrary`) -- Music Library (`musicLibrary`) -- Pictures Library (`picturesLibrary`) -- Videos Library (`videosLibrary`) -- Removable [Storage](../../../cordova/storage/storage.html) (`removableStorage`) -- Internet client/server (`internetClientServer`) - note that `internetClient` is still permitted -- Private network client/server (`privateNetworkClientServer`) - -Each of the library restrictions may be worked around by requesting that the user interact with the file system via a [File Picker](https://msdn.microsoft.com/en-us/library/windows/apps/windows.storage.pickers.fileopenpicker.aspx). This prevents malicious injected code from arbitrarily accessing the file system. - -The network-related restrictions must be worked around by either using an API that doesn't use capability checks or by brokering communication via standard internet communication channels, such as `XMLHttpRequest` or Web Sockets. - -The Enterprise Authentication and Shared User Certificates capabilities are specifically targeted at Enterprise scenarios. These capabilities are supported for private/enterprise-enabled App Stores, so if you are building apps which are going to be deployed to an internal deployment mechanism, you can still support these. However, they are not supported for Remote Mode apps in the public Windows Store. When you build targeting Windows 10, if one of these capabilities is detected in your app manifest, a warning will be displayed. - -## Reference ## - -### config.xml Preferences ### - -#### windows-target-version, windows-phone-target-version #### - <preference name="windows-target-version" value="10.0" /> - <preference name="windows-phone-target-version" value="10.0" /> - -*At least one is required.* - -These preferences identify the version of Windows or Windows Phone you would like your -app package to target. - -**Valid Values** - -- `10.0`, `UAP`: Builds for Windows 10 Universal App Platform -- `8.1`: Builds for Windows 8.1 or Windows Phone 8.1 - -**Scenarios** - -If you are targeting Windows 10 only, you only need to have a single `windows-target-version` -setting in your config.xml file. - -#### WindowsDefaultUriPrefix #### - <preference name="WindowsDefaultUriPrefix" value="ms-appx://|ms-appx-web://" /> - -This preference identifies whether you want your app to target the **local context** or **remote -context** as its startup URI. When building for Windows 10, the default is the remote -context (`ms-appx-web://`). - -In order to have a local-mode application that is not impacted by Remote Mode capability -restrictions, you must set this preference to `ms-appx://` and not declare any `<access>` -elements with remote URIs. - -**Valid Values** - -- `ms-appx://` (Default for Windows 8.1): The start page runs in the local context -- `ms-appx-web://` (Default for Windows 10): The start page runs in the remote context - -#### {SDK}-MinVersion, {SDK}-MaxVersionTested #### -*Optional* - - <preference name="Windows.Universal-MinVersion" value="10.0.0.0" /> - <preference name="Windows.Mobile-MinVersion" value="10.0.9927.0" /> - <preference name="Windows.Mobile-MaxVersionTested" value="10.0.10031.0" /> - <preference name="Microsoft.Band-MinVersion" value="10.0.11.0" /> - -These preferences identify which ecosystems (including but not limited to Windows Universal, Windows Mobile, or Xbox) and their min/max versions they are compatible with. They still require that the platforms have support for the Universal App Platform (so Windows 10 as the base OS). However, these may indicate that the application is aware of particular functionality that may only be available on certain devices (such as game streaming on Xbox). - -**Valid Values** - -There are three parts to each value: the **SDK**, the **version restriction**, and the **version value**. These preferences are detected by beginning with `Windows` or `Microsoft` and ending in `-MinVersion` or `-MaxVersionTested`: - -- The **SDK** defines what specialized platform you want to target. The default is `Windows.Universal`. Valid values for these are defined in the AppxManifest schema, in the `Package/Depednencies/TargetPlatform` elements. -- The **version restriction** defines application compatibility rules. For example, if the `-MinVersion` is set to 10.1.0.0, then OS versions which don't support at least 10.1.0.0 of the corresponding SDK won't be able to load it. - - `-MinVersion` specifies the minimum version of the SDK required - - `-MaxVersionTested` specifies the highest-tested version of the SDK. If a new version of the corresponding SDK is released, it will run in compatibility mode for the specified version. -- The **version value** is a 4-integer tuple in the form of *major.minor.build.qfe*. - -If no preferences of these types are specified in your config.xml file, then Windows.Universal version 10.0.0.0 will be chosen by default. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
