mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

docs: revise Mac App Store Submission Guide (#28922)

Browse source 
* docs: revise Mac App Store Submission Guide

* chore: update repo URL

Co-authored-by: Mark Lee <malept@users.noreply.github.com>

* chore: apply suggestions from code review

Co-authored-by: Erick Zhao <erick@hotmail.ca>

* chore: update to match style guide

* chore: add cross reference

* chore: fix inaccurate places

* chore: apply reviews

* chore: add link to provisioning profile

Co-authored-by: Mark Lee <malept@users.noreply.github.com>
Co-authored-by: Erick Zhao <erick@hotmail.ca>
This commit is contained in:
Cheng Zhao 2021-05-13 11:01:36 +09:00 • committed by GitHub
commit c0bfef16a0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 184 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

291
docs/tutorial/mac-app-store-submission-guide.md
View file

@ -1,53 +1,111 @@
# Mac App Store Submission Guide # Mac App Store Submission Guide
Since v0.34.0, Electron allows submitting packaged apps to the Mac App Store This guide provides information on:
(MAS). This guide provides information on: how to submit your app and the
limitations of the MAS build.
**Note:** Submitting an app to Mac App Store requires enrolling in the [Apple Developer * How to sign Electron apps on macOS;
Program][developer-program], which costs money. * How to submit Electron apps to Mac App Store (MAS);
* The limitations of the MAS build.
## How to Submit Your App ## Requirements
The following steps introduce a simple way to submit your app to Mac App Store. To sign Electron apps, the following tools must be installed first:
However, these steps do not ensure your app will be approved by Apple; you
still need to read Apple's [Submitting Your App][submitting-your-app] guide on
how to meet the Mac App Store requirements.
### Get Certificate * Xcode 11 or above.
* The [electron-osx-sign][electron-osx-sign] npm module.
To submit your app to the Mac App Store, you first must get a certificate from You also have to register an Apple Developer account and join the
Apple. You can follow these [existing guides][nwjs-guide] on web. [Apple Developer Program][developer-program].
### Get Team ID ## Sign Electron apps
Before signing your app, you need to know the Team ID of your account. To locate Electron apps can be distributed through Mac App Store or outside it. Each way
your Team ID, Sign in to [Apple Developer Center](https://developer.apple.com/account/), requires different ways of signing and testing. This guide focuses on
and click Membership in the sidebar. Your Team ID appears in the Membership distribution via Mac App Store, but will also mention other methods.
Information section under the team name.
### Sign Your App The following steps describe how to get the certificates from Apple, how to sign
Electron apps, and how to test them.
After finishing the preparation work, you can package your app by following ### Get certificates
[Application Distribution](application-distribution.md), and then proceed to
signing your app.
First, you have to add a `ElectronTeamID` key to your app's `Info.plist`, which The simplest way to get signing certificates is to use Xcode:
has your Team ID as its value:
```xml 1. Open Xcode and open "Accounts" preferences;
<plist version="1.0"> 2. Sign in with your Apple account;
<dict> 3. Select a team and click "Manage Certificates";
... 4. In the lower-left corner of the signing certificates sheet, click the Add
<key>ElectronTeamID</key> button (+), and add following certificates:
<string>TEAM_ID</string> * "Apple Development"
</dict> * "Apple Distribution"
</plist>
```
Then, you need to prepare three entitlements files. The "Apple Development" certificate is used to sign apps for development and
testing, on machines that have been registered on Apple Developer website. The
method of registration will be described in
[Prepare provisioning profile](#prepare-provisioning-profile).
`child.plist`: Apps signed with the "Apple Development" certificate cannot be submitted to Mac
App Store. For that purpose, apps must be signed with the "Apple Distribution"
certificate instead. But note that apps signed with the "Apple Distribution"
certificate cannot run directly, they must be re-signed by Apple to be able to
run, which will only be possible after being downloaded from the Mac App Store.
#### Other certificates
You may notice that there are also other kinds of certificates.
The "Developer ID Application" certificate is used to sign apps before
distributing them outside the Mac App Store.
The "Developer ID Installer" and "Mac Installer Distribution" certificates are
used to sign the Mac Installer Package instead of the app itself. Most Electron
apps do not use Mac Installer Package so they are generally not needed.
The full list of certificate types can be found
[here](https://help.apple.com/xcode/mac/current/#/dev80c6204ec).
Apps signed with "Apple Development" and "Apple Distribution" certificates can
only run under [App Sandbox][app-sandboxing], so they must use the MAS build of
Electron. However, the "Developer ID Application" certificate does not have this
restrictions, so apps signed with it can use either the normal build or the MAS
build of Electron.
#### Legacy certificate names
Apple has been changing the names of certificates during past years, you might
encounter them when reading old documentations, and some utilities are still
using one of the old names.
* The "Apple Distribution" certificate was also named as "3rd Party Mac
Developer Application" and "Mac App Distribution".
* The "Apple Development" certificate was also named as "Mac Developer" and
"Development".
### Prepare provisioning profile
If you want to test your app on your local machine before submitting your app to
the Mac App Store, you have to sign the app with the "Apple Development"
certificate with the provisioning profile embedded in the app bundle.
To [create a provisioning profile](https://help.apple.com/developer-account/#/devf2eb157f8),
you can follow the below steps:
1. Open the "Certificates, Identifiers & Profiles" page on the
[Apple Developer](https://developer.apple.com/account) website.
2. Add a new App ID for your app in the "Identifiers" page.
3. Register your local machine in the "Devices" page. You can find your
machine's "Device ID" in the "Hardware" page of the "System Information" app.
4. Register a new Provisioning Profile in the "Profiles" page, and download it
to `/path/to/yourapp.provisionprofile`.
### Enable Apple's App Sandbox
Apps submitted to the Mac App Store must run under Apple's
[App Sandbox][app-sandboxing], and only the MAS build of Electron can run with
the App Sandbox. The standard darwin build of Electron will fail to launch
when run under App Sandbox.
When signing the app with `electron-osx-sign`, it will automatically add the
necessary entitlements to your app's entitlements, but if you are using custom
entitlements, you must ensure App Sandbox capacity is added:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
@ -56,13 +114,14 @@ Then, you need to prepare three entitlements files.
<dict> <dict>
<key>com.apple.security.app-sandbox</key> <key>com.apple.security.app-sandbox</key>
<true/> <true/>
<key>com.apple.security.inherit</key>
<true/>
</dict> </dict>
</plist> </plist>
``` ```
`parent.plist`: #### Extra steps without `electron-osx-sign`
If you are signing your app without using `electron-osx-sign`, you must ensure
the app bundle's entitlements have at least following keys:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
@ -79,7 +138,11 @@ Then, you need to prepare three entitlements files.
</plist> </plist>
``` ```
`loginhelper.plist`: The `TEAM_ID` should be replaced with your Apple Developer account's Team ID,
and the `your.bundle.id` should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in
the app's bundle:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
@ -88,80 +151,97 @@ Then, you need to prepare three entitlements files.
<dict> <dict>
<key>com.apple.security.app-sandbox</key> <key>com.apple.security.app-sandbox</key>
<true/> <true/>
<key>com.apple.security.inherit</key>
<true/>
</dict> </dict>
</plist> </plist>
``` ```
You have to replace `TEAM_ID` with your Team ID, and replace `your.bundle.id` And the app bundle's `Info.plist` must include `ElectronTeamID` key, which has
with the Bundle ID of your app. your Apple Developer account's Team ID as its value:
And then sign your app with the following script: ```xml
<plist version="1.0">
```sh <dict>
#!/bin/bash ...
<key>ElectronTeamID</key>
# Name of your app. <string>TEAM_ID</string>
APP="YourApp" </dict>
# The path of your app to sign. </plist>
APP_PATH="/path/to/YourApp.app"
# The path to the location you want to put the signed package.
RESULT_PATH="~/Desktop/$APP.pkg"
# The name of certificates you requested.
APP_KEY="3rd Party Mac Developer Application: Company Name (APPIDENTITY)"
INSTALLER_KEY="3rd Party Mac Developer Installer: Company Name (APPIDENTITY)"
# The path of your plist files.
CHILD_PLIST="/path/to/child.plist"
PARENT_PLIST="/path/to/parent.plist"
LOGINHELPER_PLIST="/path/to/loginhelper.plist"
FRAMEWORKS_PATH="$APP_PATH/Contents/Frameworks"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework/Versions/A/Electron Framework"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework/Versions/A/Libraries/libffmpeg.dylib"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework/Versions/A/Libraries/libnode.dylib"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/$APP Helper.app/Contents/MacOS/$APP Helper"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/$APP Helper.app/"
codesign -s "$APP_KEY" -f --entitlements "$LOGINHELPER_PLIST" "$APP_PATH/Contents/Library/LoginItems/$APP Login Helper.app/Contents/MacOS/$APP Login Helper"
codesign -s "$APP_KEY" -f --entitlements "$LOGINHELPER_PLIST" "$APP_PATH/Contents/Library/LoginItems/$APP Login Helper.app/"
codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$APP_PATH/Contents/MacOS/$APP"
codesign -s "$APP_KEY" -f --entitlements "$PARENT_PLIST" "$APP_PATH"
productbuild --component "$APP_PATH" /Applications --sign "$INSTALLER_KEY" "$RESULT_PATH"
``` ```
If you are new to app sandboxing under macOS, you should also read through When using `electron-osx-sign` the `ElectronTeamID` key will be added
Apple's [Enabling App Sandbox][enable-app-sandbox] to have a basic idea, then automatically by extracting the Team ID from the certificate's name. You may
add keys for the permissions needed by your app to the entitlements files. need to manually add this key if `electron-osx-sign` could not find the correct
Team ID.
Apart from manually signing your app, you can also choose to use the ### Sign apps for development
[electron-osx-sign][electron-osx-sign] module to do the job.
#### Sign Native Modules To sign an app that can run on your development machine, you must sign it with
the "Apple Development" certificate and pass the provisioning profile to
`electron-osx-sign`.
Native modules used in your app also need to be signed. If using ```bash
electron-osx-sign, be sure to include the path to the built binaries in the electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile
argument list:
```sh
electron-osx-sign YourApp.app YourApp.app/Contents/Resources/app/node_modules/nativemodule/build/release/nativemodule
``` ```
Also note that native modules may have intermediate files produced which should If you are signing without `electron-osx-sign`, you must place the provisioning
not be included (as they would also need to be signed). If you use profile to `YourApp.app/Contents/embedded.provisionprofile`.
[electron-packager][electron-packager] before version 8.1.0, add
`--ignore=.+\.o$` to your build step to ignore these files. Versions 8.1.0 and
later ignore those files by default.
### Upload Your App The signed app can only run on the machines that registered by the provisioning
profile, and this is the only way to test the signed app before submitting to
Mac App Store.
After signing your app, you can use Application Loader to upload it to iTunes ### Sign apps for submitting to the Mac App Store
To sign an app that will be submitted to Mac App Store, you must sign it with
the "Apple Distribution" certificate. Note that apps signed with this
certificate will not run anywhere, unless it is downloaded from Mac App Store.
```bash
electron-osx-sign YourApp.app --identity='Apple Distribution'
```
### Sign apps for distribution outside the Mac App Store
If you don't plan to submit the app to Mac App Store, you can sign it the
"Developer ID Application" certificate. In this way there is no requirement on
App Sandbox, and you should use the normal darwin build of Electron if you don't
use App Sandbox.
```bash
electron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess
```
By passing `--no-gatekeeper-assess`, the `electron-osx-sign` will skip the macOS
GateKeeper check as your app usually has not been notarized yet by this step.
<!-- TODO(zcbenz): Add a chapter about App Notarization -->
This guide does not cover [App Notarization][app-notarization], but you might
want to do it otherwise Apple may prevent users from using your app outside Mac
App Store.
## Submit Apps to the Mac App Store
After signing the app with the "Apple Distribution" certificate, you can
continue to submit it to Mac App Store.
However, this guide do not ensure your app will be approved by Apple; you
still need to read Apple's [Submitting Your App][submitting-your-app] guide on
how to meet the Mac App Store requirements.
### Upload
The Application Loader should be used to upload the signed app to iTunes
Connect for processing, making sure you have [created a record][create-record] Connect for processing, making sure you have [created a record][create-record]
before uploading. before uploading.
### Submit Your App for Review If you are seeing errors like private APIs uses, you should check if the app is
using the MAS build of Electron.
After these steps, you can [submit your app for review][submit-for-review]. ### Submit for review
After uploading, you should [submit your app for review][submit-for-review].
## Limitations of MAS Build ## Limitations of MAS Build
@ -181,13 +261,13 @@ Also, due to the usage of app sandboxing, the resources which can be accessed by
the app are strictly limited; you can read [App Sandboxing][app-sandboxing] for the app are strictly limited; you can read [App Sandboxing][app-sandboxing] for
more information. more information.
### Additional Entitlements ### Additional entitlements
Depending on which Electron APIs your app uses, you may need to add additional Depending on which Electron APIs your app uses, you may need to add additional
entitlements to your `parent.plist` file to be able to use these APIs from your entitlements to your app's entitlements file. Otherwise, the App Sandbox may
app's Mac App Store build. prevent you from using them.
#### Network Access #### Network access
Enable outgoing network connections to allow your app to connect to a server: Enable outgoing network connections to allow your app to connect to a server:
@ -261,15 +341,12 @@ Electron uses following cryptographic algorithms:
* RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004) * RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004)
[developer-program]: https://developer.apple.com/support/compare-memberships/ [developer-program]: https://developer.apple.com/support/compare-memberships/
[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html [electron-osx-sign]: https://github.com/electron/electron-osx-sign
[nwjs-guide]: https://github.com/nwjs/nw.js/wiki/Mac-App-Store-%28MAS%29-Submission-Guideline#first-steps
[enable-app-sandbox]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html
[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html
[electron-osx-sign]: https://github.com/electron-userland/electron-osx-sign
[electron-packager]: https://github.com/electron/electron-packager
[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html
[app-sandboxing]: https://developer.apple.com/app-sandboxing/ [app-sandboxing]: https://developer.apple.com/app-sandboxing/
[app-notarization]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution
[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html
[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html
[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html
[export-compliance]: https://help.apple.com/app-store-connect/#/devc3f64248f [export-compliance]: https://help.apple.com/app-store-connect/#/devc3f64248f
[temporary-exception]: https://developer.apple.com/library/mac/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/AppSandboxTemporaryExceptionEntitlements.html
[user-selected]: https://developer.apple.com/library/mac/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW6 [user-selected]: https://developer.apple.com/library/mac/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW6
[network-access]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW9 [network-access]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW9