Skip to content

Instantly share code, notes, and snippets.

@Mozartted

Mozartted/How-to-Release-an-Electron-App-on-the-Mac-App-Store.md

Forked from steve981cr/How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
Created September 4, 2024 16:08
Show Gist options
  • Save Mozartted/05b96d3373f5f3f559ef4f1e17a42c50 to your computer and use it in GitHub Desktop.
Save Mozartted/05b96d3373f5f3f559ef4f1e17a42c50 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 6 additions and 6 deletions.
    12 changes: 6 additions & 6 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -508,13 +508,13 @@ You won't be able to launch the production version of the app on your computer (

    ## Step 5: Submit the app to App Store Connect for review and release

    - Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps and click on your app.<br>
    - Click the **+** sign in the left panel to add a new version.<br>
    - Enter the new version number that matches the version in the package.json file.<br>
    - Fill out: What's New in This Version.<br>
    - There may be warning notices saying you need to update an agreement before your app can be released.<br>
    - Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps and click on your app.
    - Click the **+** sign in the left panel to add a new version.
    - Enter the new version number that matches the version in the package.json file.
    - Fill out: What's New in This Version.
    - There may be warning notices saying you need to update an agreement before your app can be released.

    - On your computer open the Transporter app. Then upload or drag and drop the .pkg file into the Transporter. It will check for errors. If there are no errors press the submit button.

    - Go back to appstore connect. In the **Build** section select the build you just submitted (refresh the page if it's not listed) and click Submit for Review.
    - In the **App Store Version Release** section select when you want the version released. If you select "Manually", wait for the app to be reviewed and accepted, then release it.<br>
    - In the **App Store Version Release** section select when you want the version released. If you select "Manually", wait for the app to be reviewed and accepted, then release it.
  2. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 2 additions and 1 deletion.
    3 changes: 2 additions & 1 deletion How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -512,8 +512,9 @@ You won't be able to launch the production version of the app on your computer (
    - Click the **+** sign in the left panel to add a new version.<br>
    - Enter the new version number that matches the version in the package.json file.<br>
    - Fill out: What's New in This Version.<br>
    - There may be warning notices saying you need to update an agreement before your app can be released.<br>

    - On your computer open the Transporter app. Then upload or drag and drop the .pkg file into the Transporter. It will check for errors. If there are no errors press the submit button.

    - Go back to appstore connect. In the **Build** section select the build you just submitted (refresh the page if it's not listed) and click Submit for Review.
    - Go back to appstore connect. In the **Build** section select the build you just submitted (refresh the page if it's not listed) and click Submit for Review.
    - In the **App Store Version Release** section select when you want the version released. If you select "Manually", wait for the app to be reviewed and accepted, then release it.<br>
  3. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 4 additions and 4 deletions.
    8 changes: 4 additions & 4 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -509,11 +509,11 @@ You won't be able to launch the production version of the app on your computer (
    ## Step 5: Submit the app to App Store Connect for review and release

    - Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps and click on your app.<br>
    - Click the + sign in the left panel to add a new version.<br>
    - Click the **+** sign in the left panel to add a new version.<br>
    - Enter the new version number that matches the version in the package.json file.<br>
    - Fill out: What's New in This Version.<br>

    - On your computer open the Transporter app. Then upload or drag and drop the .pkg file into the Transporter. It will check for error. If there are no errors press the submit button.
    - On your computer open the Transporter app. Then upload or drag and drop the .pkg file into the Transporter. It will check for errors. If there are no errors press the submit button.

    - Go back to appstore connect. In the Build section select the build you just submitted (refresh the page if it's not listed) and click Submit for Review.
    - In the App Store Version Release section either select when you want the version released. If you select Manually, wait for the app to be reviewed and accepted, then release it.<br>
    - Go back to appstore connect. In the **Build** section select the build you just submitted (refresh the page if it's not listed) and click Submit for Review.
    - In the **App Store Version Release** section select when you want the version released. If you select "Manually", wait for the app to be reviewed and accepted, then release it.<br>
  4. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -496,13 +496,13 @@ Confirm that the app is signed:<br>

    ## Step 4: build the production version of the app:

    If that works change the package.json to the mas setup for the build mac property, then build the production version of the app and installer. Run the script `npm run dist`
    If that works change the package.json to the mas setup for the build mac property. To build the production version of the app and installer run the script: `npm run dist`

    Confirm that the app and pkg installer are signed:<br>
    `codesign --display --verbose=2 dist/mas/<AppName>.app`<br>
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    You won't be able to launch the production version of the app.
    You won't be able to launch the production version of the app on your computer (it must be signed by the MAS).

    ---

  5. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -456,8 +456,8 @@ Open XCode > Click the XCode menu > Select Preferences > Click Accounts > Click
    ### Provisioning Profiles
    File | Use | Expires
    ---- | --- | -------
    AppleDevelopment.provisionprofile | MAS dev | Expires in one year
    MacAppStore.provisionprofile | MAS | Expires in one year
    AppleDevelopment.provisionprofile | MAS dev | Expires after one year
    MacAppStore.provisionprofile | MAS | Expires after one year

    To read the files enter:
    `security cms -D -i build/AppleDevelopment.provisionprofile`
  6. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 4 additions and 4 deletions.
    8 changes: 4 additions & 4 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -431,16 +431,16 @@ _________________________________________________
    _________________________________________________

    # Steps to Release an Update
    After completing and tested your updates take the following steps to put the updated app in the Mac App Store.
    After completing and testing your updates take the following steps to put the updated app in the Mac App Store.

    ## Step 1: Check the expiration status of the following Apple certificates and update any that are expired:

    ### Apple Certificates:
    Certificate | Use | Expires
    ----------- | --- | -------
    Apple Development | MAS dev | Expires in one year
    Apple Distribution | MAS | Expires in one year
    Mac Installer Distribution | MAS installer | Expires in one year
    Apple Development | MAS dev | Expires after one year
    Apple Distribution | MAS | Expires after one year
    Mac Installer Distribution | MAS installer | Expires after one year

    View your certificates: https://developer.apple.com/account/resources/certificates/list<br>
    Or from the command line: `security find-identity -v`
  7. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -19,7 +19,7 @@ To Do List app example (contains native node modules): <a href="https://github.c
    [Step 11) Test the app](#step-11-test-the-app)<br>
    [Step 12) Upload the pkg file](#step-12-upload-the-pkg-file)<br>
    [Native Node NPM packages](#native-node-npm-packages)<br>
    [Release an update](#steps-to-release-an-update)
    [Steps to Release an Update](#steps-to-release-an-update)
    _______________________________________________________________

    ## Introduction
  8. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -19,7 +19,7 @@ To Do List app example (contains native node modules): <a href="https://github.c
    [Step 11) Test the app](#step-11-test-the-app)<br>
    [Step 12) Upload the pkg file](#step-12-upload-the-pkg-file)<br>
    [Native Node NPM packages](#native-node-npm-packages)<br>
    [Release an update](#release-an-update)
    [Release an update](#steps-to-release-an-update)
    _______________________________________________________________

    ## Introduction
    @@ -430,7 +430,7 @@ Its binary file will be pulled out of your app's asar binary file. You can confi
    _________________________________________________
    _________________________________________________

    # Steps to Release an update
    # Steps to Release an Update
    After completing and tested your updates take the following steps to put the updated app in the Mac App Store.

    ## Step 1: Check the expiration status of the following Apple certificates and update any that are expired:
  9. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 38 additions and 25 deletions.
    63 changes: 38 additions & 25 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -430,8 +430,10 @@ Its binary file will be pulled out of your app's asar binary file. You can confi
    _________________________________________________
    _________________________________________________

    # Release an update
    To submit an updated version of your app to the Mac App Store, make sure you have unexpired versions of the following:
    # Steps to Release an update
    After completing and tested your updates take the following steps to put the updated app in the Mac App Store.

    ## Step 1: Check the expiration status of the following Apple certificates and update any that are expired:

    ### Apple Certificates:
    Certificate | Use | Expires
    @@ -449,58 +451,69 @@ Open XCode > Click the XCode menu > Select Preferences > Click Accounts > Click

    ---

    ## Step 2: Check the expiration status of the following Provisioning Profiles and update any that are expired:

    ### Provisioning Profiles
    File | Use | Expires
    ---- | --- | -------
    AppleDevelopment.provisionprofile | MAS dev | Expires in one year
    MacAppStore.provisionprofile | MAS | Expires in one year

    View/Add: https://developer.apple.com/account/resources/profiles/list
    To read the files enter:
    `security cms -D -i build/AppleDevelopment.provisionprofile`

    `security cms -D -i build/MacAppStore.provisionprofile`

    Put the provisioning profile files in the build/mac directory.
    Or view them at: https://developer.apple.com/account/resources/profiles/list

    To read the files enter:
    `security cms -D -i build/mac/AppleDevelopment.provisionprofile`
    Delete expired profiles and create and download updated ones.

    `security cms -D -i build/mac/MacAppStore.provisionprofile`
    Put the provisioning profile files in the app's build directory.

    ---

    ## Entitlements
    Entitlements don't expire so as long as there are no changes to entitlements you can leave these as is.

    ### Entitlements:
    Entitlements | Use | Expires
    ------------ | --- | -------
    entitlements.mas.plist | MAS | no expiration
    entitlements.mas.inherit.plist | MAS | no expiration

    View/Add: https://developer.apple.com/account/resources/profiles/list
    Delete expired profiles, create and download new ones.
    Put the provisioning profile files in the app's build directory.

    ---

    ### Modify, package and sign the App
    ## Step 3: build and test the development version of the app:

    In your updated Electron App:
    - Change the version and buildVersion numbers in the package.json file. Use semantic versioning (e.g., 1.0.1).
    - Change the version number in the package.json file. Use semantic versioning (e.g., 1.0.1). If you make multiple submissions for this version you'll have to add a buildVersion number as well.
    - Ideally, upgrade to the latest versions of all your npm packages including electron and electron-builder.

    Package and code sign the app and installer by running the script `npm run dist`
    - Package and code sign a development version of the app to make sure it works correctly. Use the mas-dev setup for the build mac property, then run the script `npm run dist`

    Confirm that the app and pkg installer are signed:<br>
    Development version:<br>
    Confirm that the app is signed:<br>
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`<br>
    Distribution version:<br>

    ## Step 4: build the production version of the app:

    If that works change the package.json to the mas setup for the build mac property, then build the production version of the app and installer. Run the script `npm run dist`

    Confirm that the app and pkg installer are signed:<br>
    `codesign --display --verbose=2 dist/mas/<AppName>.app`<br>
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    You won't be able to launch the production version of the app.

    ---

    ### Submit the app to App Store Connect
    ## Step 5: Submit the app to App Store Connect for review and release

    - Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps and click on your app.<br>
    - Click the + sign in the left panel to add a new version.<br>
    - Enter the new version number that matches the version in the package.json file.<br>
    - Fill out: What's New in This Version.<br>

    - On your computer open the Transporter app. Then upload or drag and drop the .pkg file into the Transporter. It will check for error. If there are no errors press the submit button.

    Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps
    Click on your app.<br>
    Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version to App Store Connect with the Transporter app.<br>
    Click Submit for Review.<br>
    - Go back to appstore connect. In the Build section select the build you just submitted (refresh the page if it's not listed) and click Submit for Review.
    - In the App Store Version Release section either select when you want the version released. If you select Manually, wait for the app to be reviewed and accepted, then release it.<br>
  10. @steve981cr steve981cr revised this gist May 15, 2024. 1 changed file with 11 additions and 6 deletions.
    17 changes: 11 additions & 6 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,5 @@
    # How to Release an Electron App on the Mac App Store
    By Steve Carey - Last updated September 6, 2023. Originally published Feb 4, 2020.
    By Steve Carey - Last updated May 15, 2024. Originally published Feb 4, 2020.

    Super basic app example: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a><br>
    To Do List app example (contains native node modules): <a href="https://github.com/steve981cr/electron-todo-example">github.com/steve981cr/electron-todo-example</a>
    @@ -50,7 +50,6 @@ ________________________________________________________________________________
    <a ref="https://developer.apple.com/app-store/small-business-program/">developer.apple.com/app-store/small-business-program</a><br>
    If approved, Apple's commission drops from 30% to 15%.


    2c) Add your device to your Developer account [developer.apple.com/account/resources/devices/list](https://developer.apple.com/account/resources/devices/list)
    - Click the + to add a device.
    - To get the Device ID from your Mac: open the System Information app > Copy the Hardware UUID.
    @@ -411,7 +410,7 @@ Ref: https://www.electronjs.org/docs/latest/glossary#asar

    Native modules must be pulled out of your built binary app and code signed separately.

    In the build script add an asarUnpack property. The value is an array where uou list all files that need to be pulled out. The files we need to pull out are binary files that have a .node extension. Use wildcards for the directory and filename:
    In the build script add an asarUnpack property. The value is an array where you list all files that need to be pulled out. The files we need to pull out are binary files that have a .node extension. Use wildcards for the directory and filename:
    ```json
    "build": {
    ...
    @@ -423,10 +422,10 @@ In the build script add an asarUnpack property. The value is an array where uou
    ```
    The file will be placed in your app file in Contents/Resources/app.asar.unpacked/node_modules/<module name>

    Electron-builder will automatically sign this binary when you run the dist command.
    Electron-builder will automatically sign this binary when you run the `dist` command.

    Its binary file will be pulled out of your app's asar binary file. You can confirm that it is code signed with the below command. Replace <AppName> with the name of your app, and use the correct path to the .node file:
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app/Contents/Resources/app.asar.unpacked/node_modules/path/to/filename.node`
    `codesign --display --verbose=2 dist/mas/<AppName>.app/Contents/Resources/app.asar.unpacked/node_modules/path/to/filename.node`

    _________________________________________________
    _________________________________________________
    @@ -444,6 +443,10 @@ Mac Installer Distribution | MAS installer | Expires in one year
    View your certificates: https://developer.apple.com/account/resources/certificates/list<br>
    Or from the command line: `security find-identity -v`

    **To update one or more certifications using XCode:**

    Open XCode > Click the XCode menu > Select Preferences > Click Accounts > Click the Manage Certificates button > Click the + button in the lower left corner > Select the certificate type to create (Apple Development, Apple Distribution, Mac Installer Distribution).

    ---

    ### Provisioning Profiles
    @@ -469,7 +472,9 @@ Entitlements | Use | Expires
    entitlements.mas.plist | MAS | no expiration
    entitlements.mas.inherit.plist | MAS | no expiration

    Put your entitlement files in the build directory.
    View/Add: https://developer.apple.com/account/resources/profiles/list
    Delete expired profiles, create and download new ones.
    Put the provisioning profile files in the app's build directory.

    ---

  11. @steve981cr steve981cr revised this gist Sep 10, 2023. 1 changed file with 5 additions and 3 deletions.
    8 changes: 5 additions & 3 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,7 +1,8 @@
    # How to Release an Electron App on the Mac App Store
    By Steve Carey - Last updated September 6, 2023. Originally published Feb 4, 2020.

    Example Code: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a>
    Super basic app example: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a><br>
    To Do List app example (contains native node modules): <a href="https://github.com/steve981cr/electron-todo-example">github.com/steve981cr/electron-todo-example</a>

    ## Table of Contents
    [Introduction](#introduction)<br>
    @@ -379,7 +380,8 @@ ________________________________________________________________________________
    ________________________________________________________________________________
    ## Native Node NPM packages
    <p>Reference: <a href="https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules">electronjs.org/docs/latest/tutorial/using-native-node-modules</a>
    Reference: <a href="https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules">electronjs.org/docs/latest/tutorial/using-native-node-modules</a><br>
    To Do List app example (contains native node module): <a href="https://github.com/steve981cr/electron-todo-example">github.com/steve981cr/electron-todo-example</a>
    Native node modules are npm packages that include C or C++ code.
    @@ -496,4 +498,4 @@ Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version to App Store Connect with the Transporter app.<br>
    Click Submit for Review.<br>
    Click Submit for Review.<br>
  12. @steve981cr steve981cr revised this gist Sep 7, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -18,7 +18,7 @@ Example Code: <a href="https://github.com/steve981cr/electron-app-store-example"
    [Step 11) Test the app](#step-11-test-the-app)<br>
    [Step 12) Upload the pkg file](#step-12-upload-the-pkg-file)<br>
    [Native Node NPM packages](#native-node-npm-packages)<br>
    [# Release an update](#release-an-update)
    [Release an update](#release-an-update)
    _______________________________________________________________

    ## Introduction
  13. @steve981cr steve981cr revised this gist Sep 7, 2023. 1 changed file with 59 additions and 40 deletions.
    99 changes: 59 additions & 40 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -3,6 +3,24 @@ By Steve Carey - Last updated September 6, 2023. Originally published Feb 4, 202

    Example Code: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a>

    ## Table of Contents
    [Introduction](#introduction)<br>
    [Step 1) Start with your completed Electron Application](#step-1-start-with-your-completed-electron-application)<br>
    [Step 2) Apple Developer Account](#step-2-apple-developer-account)<br>
    [Step 3) Create Three Signing Certificates](#step-3-create-three-signing-certificates)<br>
    [Step 4) Create an App ID](#step-4-create-an-app-id)<br>
    [Step 5) Add the App to your developer account](#step-5-add-the-app-to-your-developer-account)<br>
    [Step 6) Generate two Provisioning Profiles (AppleDevelopment and MacAppStore)](#step-6-generate-two-provisioning-profiles-appledevelopment-and-macappstore)<br>
    [Step 7) Entitlements](#step-7-entitlements)<br>
    [Step 8) Create an icon set ](#step-8-create-an-icon-set)<br>
    [Step 9) package.json file](#step-9-packagejson-file)<br>
    [Step 10) Build a development and distribution versions of the App with electron-builder](#step-10-build-a-development-and-distribution-versions-of-the-app-with-electron-builder)<br>
    [Step 11) Test the app](#step-11-test-the-app)<br>
    [Step 12) Upload the pkg file](#step-12-upload-the-pkg-file)<br>
    [Native Node NPM packages](#native-node-npm-packages)<br>
    [# Release an update](#release-an-update)
    _______________________________________________________________

    ## Introduction
    You have three options for distributing an Electron App for MacOS. Through the Mac App Store (MAS), through a third party platform like GitHub Marketplace, or directly (e.g, download from your website). Apple prefers you distribute through the Mac App Store. Partly because they review all apps before they can be put on the Mac App Store so end users can feel confident that the app is safe. And partly because they take a cut of app revenue purchased through the MAS. This tutorial focuses on the steps required to put your app on the MAS.

    @@ -19,12 +37,12 @@ Electron-builder Reference: <a href="https://www.electron.build/configuration/ma
    &emsp; and <a href="https://www.electron.build/configuration/mas">electron.build/configuration/mas</a>
    ________________________________________________________________________________

    ## Step 1) Start with your completed Electron Application.
    ## Step 1) Start with your completed Electron Application
    Electron should be a development dependency:
    `npm install -D electron`
    ________________________________________________________________________________

    ## Step 2) Apple Developer Account
    ## Step 2) Apple Developer Account
    2a) You need an Apple Developer Account. Costs ~$100/year. Sign up at <a href="https://developer.apple.com">developer.apple.com</a>.

    2b) And sign up for the App Store's Small Business Program (for developers with revenue under $1 million/year):
    @@ -37,7 +55,7 @@ If approved, Apple's commission drops from 30% to 15%.
    - To get the Device ID from your Mac: open the System Information app > Copy the Hardware UUID.
    ________________________________________________________________________________

    ## Step 3) Create Three Signing Certificates:
    ## Step 3) Create Three Signing Certificates
    Ref: Apple certificate types: https://help.apple.com/xcode/mac/current/#/dev80c6204ec

    - <b>Apple Development:</b> used to sign apps for development and testing on machines that have been registered on the Apple Developer website.
    @@ -78,7 +96,7 @@ Alternatively, you can create and install these three certificates with the Keyc

    ________________________________________________________________________________

    ## Step 4) Create an App ID
    ## Step 4) Create an App ID
    - Go to your developer account - developer.apple.com > Certificates, IDs & Profiles > Identifiers > + (to add a new id) > select App IDs > continue button.
    - On the Register App ID page:
    - Platform: MacOS
    @@ -112,7 +130,31 @@ Official instructions for adding an app: <a href="https://developer.apple.com/he
    - You can add attachments that may be useful to the reviewer such as a video of how to use the app (can be any dimensions).
    ________________________________________________________________________________

    ## Step 6) Entitlements
    ## Step 6) Generate two Provisioning Profiles (AppleDevelopment and MacAppStore)
    - Go to your apple developer account profiles page <a href="https://developer.apple.com/account/resources/profiles/list">developer.apple.com/account/resources/profiles/list</a>
    - These expire after one year, so if you are updating your app, run the command at the bottom of 9a and 9b to see the expiration date. If they are expired you need to recreate them.

    ### 6a) Generate the AppleDevelopment Provisioning Profile
    - Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.
    - Select "macOS App Development". Then click Continue.
    - Select your appID, then click continue.
    - Give it a recognizable name like "AppleDevelopment", then download it to your computer.
    - Double click the file to install it, then place it in the project's build directory. The file name would be AppleDevelopment.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.
    - This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command:
    `security cms -D -i build/AppleDevelopment.provisionprofile`

    ### 6b) Generate the MacAppStore Provisioning Profile
    - Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.
    - Select Mac App Store. Then click Continue.
    - Select your appID, then click continue.
    - Select your Mac App Distribution certificate, then click continue.
    - Give it a recognizable name like "MacAppStore", then download it to your computer.
    - Double click the file to install it, then place it in the project's build directory. The file name would be MacAppStore.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.
    - This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command:
    `security cms -D -i build/MacAppStore.provisionprofile`
    ________________________________________________________________________________

    ## Step 7) Entitlements
    Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a>
    - Make parent and child entitlement property list files using XML. Put them in the build folder.
    - These files correspond to the entitlements and entitlementsInherit keys in the package.json file.
    @@ -153,30 +195,6 @@ __/build/entitlements.mas.inherit.plist__
    - The application-groups key is an array containing your app identifier (TeamID and appId).
    ________________________________________________________________________________
    ## Step 7) Generate two Provisioning Profiles (AppleDevelopment and MacAppStore)
    - Go to your apple developer account profiles page <a href="https://developer.apple.com/account/resources/profiles/list">developer.apple.com/account/resources/profiles/list</a>
    - These expire after one year, so if you are updating your app, run the command at the bottom of 9a and 9b to see the expiration date. If they are expired you need to recreate them.
    ### 7a) Generate the AppleDevelopment Provisioning Profile
    - Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.
    - Select "macOS App Development". Then click Continue.
    - Select your appID, then click continue.
    - Give it a recognizable name like "AppleDevelopment", then download it to your computer.
    - Double click the file to install it, then place it in the project's build directory. The file name would be AppleDevelopment.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.
    - This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command:
    `security cms -D -i build/AppleDevelopment.provisionprofile`
    ### 7b) Generate the MacAppStore Provisioning Profile
    - Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.
    - Select Mac App Store. Then click Continue.
    - Select your appID, then click continue.
    - Select your Mac App Distribution certificate, then click continue.
    - Give it a recognizable name like "MacAppStore", then download it to your computer.
    - Double click the file to install it, then place it in the project's build directory. The file name would be MacAppStore.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.
    - This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command:
    `security cms -D -i build/MacAppStore.provisionprofile`
    ________________________________________________________________________________
    ## Step 8) Create an icon set
    Reference: <a href="https://www.electron.build/icons">electron.build/icons</a> | <a href="https://developer.apple.com/design/human-interface-guidelines/app-icons">developer.apple.com/design/human-interface-guidelines/app-icons</a>
    - You need to create your icon in at least two different sizes: 512x512 px and 1024x1024 px saved as png files. But ideally use all the Apple recommended sizes which additionally include 16x16, 32x32, 64x64, 128x128 and 256x256.
    @@ -410,6 +428,7 @@ Its binary file will be pulled out of your app's asar binary file. You can confi

    _________________________________________________
    _________________________________________________

    # Release an update
    To submit an updated version of your app to the Mac App Store, make sure you have unexpired versions of the following:

    @@ -425,16 +444,6 @@ Or from the command line: `security find-identity -v`

    ---

    ### Entitlements:
    Entitlements | Use | Expires
    ------------ | --- | -------
    entitlements.mas.plist | MAS | no expiration
    entitlements.mas.inherit.plist | MAS | no expiration

    Put your entitlement files in the build directory.

    ---

    ### Provisioning Profiles
    File | Use | Expires
    ---- | --- | -------
    @@ -452,6 +461,16 @@ To read the files enter:

    ---

    ### Entitlements:
    Entitlements | Use | Expires
    ------------ | --- | -------
    entitlements.mas.plist | MAS | no expiration
    entitlements.mas.inherit.plist | MAS | no expiration

    Put your entitlement files in the build directory.

    ---

    ### Modify, package and sign the App

    In your updated Electron App:
    @@ -477,4 +496,4 @@ Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version to App Store Connect with the Transporter app.<br>
    Click Submit for Review.<br>
    Click Submit for Review.<br>
  14. @steve981cr steve981cr revised this gist Sep 7, 2023. 1 changed file with 13 additions and 30 deletions.
    43 changes: 13 additions & 30 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -410,7 +410,6 @@ Its binary file will be pulled out of your app's asar binary file. You can confi

    _________________________________________________
    _________________________________________________

    # Release an update
    To submit an updated version of your app to the Mac App Store, make sure you have unexpired versions of the following:

    @@ -421,7 +420,6 @@ Apple Development | MAS dev | Expires in one year
    Apple Distribution | MAS | Expires in one year
    Mac Installer Distribution | MAS installer | Expires in one year


    View your certificates: https://developer.apple.com/account/resources/certificates/list<br>
    Or from the command line: `security find-identity -v`

    @@ -437,61 +435,46 @@ Put your entitlement files in the build directory.

    ---

    #### Provisioning Profiles
    ### Provisioning Profiles
    File | Use | Expires
    ---- | --- | -------
    AppleDevelopment.provisionprofile | MAS dev | Expires in one year
    MacAppStore.provisionprofile | MAS | Expires in one year

    View/Add: https://developer.apple.com/account/resources/profiles/list

    Put files in the build directory.
    Put the provisioning profile files in the build/mac directory.

    To read the files enter:
    `security cms -D -i build/AppleDevelopment.provisionprofile`
    `security cms -D -i build/mac/AppleDevelopment.provisionprofile`

    `security cms -D -i build/MacAppStore.provisionprofile`
    `security cms -D -i build/mac/MacAppStore.provisionprofile`

    ---
    In your Electron App:
    - Change the version number (and build number) in the package.json file. Use semantic versioning (e.g., 1.0.1).
    - Ideally, upgrade to the latest versions of all your npm packages including electron and electron-builder.

    Build it with `npm run dist`
    ### Modify, package and sign the App

    Confirm that the app and pkg installer are signed:<br>
    Dev version:<br>
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`<br>
    Distribution version:<br>
    `codesign --display --verbose=2 dist/mas/<AppName>.app`<br>
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    ---

    Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps
    Click on your app.<br>
    Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version with the Transporter app.<br>
    Submit it for review.<br>
    In your updated Electron App:
    - Change the version and buildVersion numbers in the package.json file. Use semantic versioning (e.g., 1.0.1).
    - Ideally, upgrade to the latest versions of all your npm packages including electron and electron-builder.

    Build it with `npm run dist`
    Package and code sign the app and installer by running the script `npm run dist`

    Confirm that the app and pkg installer are signed:<br>
    Dev version:<br>
    Development version:<br>
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`<br>
    Distribution version:<br>
    `codesign --display --verbose=2 dist/mas/<AppName>.app`<br>
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    ---

    ### Submit the app to App Store Connect

    Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps
    Click on your app.<br>
    Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version with the Transporter app.<br>
    Submit it for review.<br>
    Submit the new app version to App Store Connect with the Transporter app.<br>
    Click Submit for Review.<br>
  15. @steve981cr steve981cr revised this gist Sep 7, 2023. 1 changed file with 32 additions and 6 deletions.
    38 changes: 32 additions & 6 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -445,27 +445,53 @@ MacAppStore.provisionprofile | MAS | Expires in one year

    View/Add: https://developer.apple.com/account/resources/profiles/list

    Put files in the build directory.

    To read the files enter:
    `security cms -D -i build/AppleDevelopment.provisionprofile`

    `security cms -D -i build/MacAppStore.provisionprofile`

    Put files in the build directory.
    ---
    In your Electron App:
    - Change the version number (and build number) in the package.json file. Use semantic versioning (e.g., 1.0.1).
    - Ideally, upgrade to the latest versions of all your npm packages including electron and electron-builder.

    Build it with `npm run dist`

    Confirm that the app and pkg installer are signed:<br>
    Dev version:<br>
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`<br>
    Distribution version:<br>
    `codesign --display --verbose=2 dist/mas/<AppName>.app`<br>
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    ---

    - Change the version number in the package.json file.
    Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps
    Click on your app.<br>
    Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version with the Transporter app.<br>
    Submit it for review.<br>
    - Ideally, upgrade to the latest versions of all your npm packages including electron and electron-builder.

    Build it with `npm run dist`

    Confirm that the app and pkg installer are signed:
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`
    Confirm that the app and pkg installer are signed:<br>
    Dev version:<br>
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`<br>
    Distribution version:<br>
    `codesign --display --verbose=2 dist/mas/<AppName>.app`<br>
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    ---

    Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps
    Click on your app.<br>
    Click the + sign in the lleft panel to add a new version.<br>
    Enter the new version number using semantic versioning (e.g., 1.0.1).<br>
    Click the + sign in the left panel to add a new version.<br>
    Enter the new version number that matches the version in the package.json file.<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version with the Transporter app.<br>
    Submit it for review.<br>
  16. @steve981cr steve981cr revised this gist Sep 7, 2023. 1 changed file with 392 additions and 301 deletions.
    693 changes: 392 additions & 301 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,180 +1,250 @@
    <div class="page-header">
    <h1>How to Release an Electron App on the Mac App Store</h1>
    <p>By Steve Carey - Last updated June 20, 2023. Originally published Feb 4, 2020.</p>
    <p>Example Code: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a></p>
    </div>
    # How to Release an Electron App on the Mac App Store
    By Steve Carey - Last updated September 6, 2023. Originally published Feb 4, 2020.

    <div class="slightly-shrink-font">
    <h2>Introduction</h2>
    <p>You have three options for distributing an Electron App for MacOS. Through the Mac App Store (MAS), through a third party platform like GitHub Marketplace, or directly (e.g, download from your website). Apple prefers you distribute through the Mac App Store. Partly because they review all apps before they can be put on the Mac App Store so end users can feel confident that the app is safe. And partly because they take a cut of app revenue purchased through the MAS. This tutorial focuses on the steps required to put your app on the MAS.</p>
    Example Code: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a>

    <p>All apps distributed though the MAS must be sandboxed, meaning they are completely self contained except for any approved entitlements.</p>
    ## Introduction
    You have three options for distributing an Electron App for MacOS. Through the Mac App Store (MAS), through a third party platform like GitHub Marketplace, or directly (e.g, download from your website). Apple prefers you distribute through the Mac App Store. Partly because they review all apps before they can be put on the Mac App Store so end users can feel confident that the app is safe. And partly because they take a cut of app revenue purchased through the MAS. This tutorial focuses on the steps required to put your app on the MAS.

    <p>There are a few options for packaging the app. We will use Electron-Builder.</li>
    All apps distributed though the MAS must be sandboxed, meaning they are completely self contained except for any approved entitlements.

    <p>You will need to package two versions of your app. A development version for testing, and a distribution version for submission to Apple.</p>
    There are a few options for packaging the app. We will use Electron-Builder.

    <p>Apple Reference: <a href="https://developer.apple.com/app-store/review/">developer.apple.com/app-store/review</a><br>
    <a href="https://developer.apple.com/app-store/review/guidelines/">developer.apple.com/app-store/review/guidelines</a></p>
    <p>Electron Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a></p>
    <p>Electron-builder Reference: <a href="https://www.electron.build/configuration/mac">electron.build/configuration/mac</a><br>
    You will need to package two versions of your app. A development version for testing, and a distribution version for submission to Apple.

    Apple Reference: <a href="https://developer.apple.com/app-store/review/">developer.apple.com/app-store/review</a><br>
    <a href="https://developer.apple.com/app-store/review/guidelines/">developer.apple.com/app-store/review/guidelines</a><br>
    Electron Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a><br>
    Electron-builder Reference: <a href="https://www.electron.build/configuration/mac">electron.build/configuration/mac</a><br>
    &emsp; and <a href="https://www.electron.build/configuration/mas">electron.build/configuration/mas</a>
    </p>
    <hr>
    <h3>Step 1) Start with your completed Electron Application.</h3>
    <p class='mb-1'>Electron should be a development dependency.</p>
    <li class="dlr"><code>npm install -D electron</code></li>

    <hr>
    <h3>Step 2) Apple Developer Account </h3>
    <p>You need an Apple Developer Account. Costs ~$100/year. Sign up at <a href="https://developer.apple.com">developer.apple.com</a>.</p>
    <p>And sign up for the App Store's Small Business Program (for developers with revenue under $1 million/year):
    ________________________________________________________________________________

    ## Step 1) Start with your completed Electron Application.
    Electron should be a development dependency:
    `npm install -D electron`
    ________________________________________________________________________________

    ## Step 2) Apple Developer Account
    2a) You need an Apple Developer Account. Costs ~$100/year. Sign up at <a href="https://developer.apple.com">developer.apple.com</a>.

    2b) And sign up for the App Store's Small Business Program (for developers with revenue under $1 million/year):
    <a ref="https://developer.apple.com/app-store/small-business-program/">developer.apple.com/app-store/small-business-program</a><br>
    If approved, Apple's commission drops from 30% to 15%.
    </p>

    <hr>
    <h3>Step 3) Create Three Signing Certificates:</h3>
    <ul>
    <li><b>Apple Development:</b> used to sign apps for development and testing on machines that have been registered on the Apple Developer website.</li>
    <li><b>Apple Distribution:</b> used to sign apps submitted to the Mac App Store.</li>
    <li><b>Mac Installer Distribution:</b> used to sign the Mac Installer Package in addition to the app itself.</li>
    </ul>

    <p>You can create the signing certificates with either XCode or using the Keychain Access app.</p>

    <h4>Using XCode (preferred):</h4>
    <p>Create and install these three certificates with XCode. Repeat the below process for each certificate.</p>
    <p>Open XCode > Click the XCode menu > Select Preferences > Click Accounts > Click the Manage Certificates button > Click the + button in the lower left corner > Select the certificate type to create (Apple Development, Apple Distribution, Mac Installer Distribution).</p>

    <h4>Using the Keychain Access app:</h4>
    <p>Alternatively, you can create and install these three certificates with the Keychain Access app. Repeat the below two-step process for each certificate.</p>
    <h5>Keychain Access App - Step 1) Request a certificate:</h5>
    <li>Launch Keychain Access located in /Applications/Utilities.</li>
    <li>Click the Keychain Access menu > Certificate Assistant > Request a Certificate from a Certificate Authority.</li>
    <li>In the Certificate Assistant dialog, enter an email address in the User Email Address field.</li>
    <li>In the Common Name field use the value provided. </li>
    <li>Leave the CA Email Address field empty. </li>
    <li>Choose "Saved to disk" saving it to the desktop, and click Continue. Filename is CertificateSigningRequest.certSigningRequest </li>

    <br>
    <h5>Keychain Access App - Step 2) Import the new certificate from your developer account to your Keychain:</h5>
    <li>go to https://developer.apple.com/account > Certificates > + (to add a new certificate) > Select the certificate type (Apple Development, Apple Distribution, Mac Installer Distribution) > click the continue button > Choose File > Double-click the certificate file you downloaded above > Download the new certificate file > Double click the downloaded file and it will be automatically loaded to your keychain.</li>
    <li>Delete the CertificateSigningRequest.certSigningRequest and the certificate download files from the desktop.</li>


    2c) Add your device to your Developer account [developer.apple.com/account/resources/devices/list](https://developer.apple.com/account/resources/devices/list)
    - Click the + to add a device.
    - To get the Device ID from your Mac: open the System Information app > Copy the Hardware UUID.
    ________________________________________________________________________________

    ## Step 3) Create Three Signing Certificates:
    Ref: Apple certificate types: https://help.apple.com/xcode/mac/current/#/dev80c6204ec

    - <b>Apple Development:</b> used to sign apps for development and testing on machines that have been registered on the Apple Developer website.
    - <b>Apple Distribution:</b> used to sign apps submitted to the Mac App Store.
    - <b>Mac Installer Distribution:</b> used to sign the Mac Installer Package in addition to the app itself.

    You can create the signing certificates with either XCode or using the Keychain Access app.

    ### Using XCode (preferred):
    Create and install these three certificates with XCode. Repeat the below process for each certificate.

    Open XCode > Click the XCode menu > Select Preferences > Click Accounts > Click the Manage Certificates button > Click the + button in the lower left corner > Select the certificate type to create (Apple Development, Apple Distribution, Mac Installer Distribution).

    ### Using the Keychain Access app:
    Alternatively, you can create and install these three certificates with the Keychain Access app. Repeat the below two-step process for each certificate.

    #### Keychain Access App - Step 1) Request a certificate:
    - Launch Keychain Access located in /Applications/Utilities.
    - Click the Keychain Access menu > Certificate Assistant > Request a Certificate from a Certificate Authority.
    - In the Certificate Assistant dialog, enter an email address in the User Email Address field.
    - In the Common Name field use the value provided.
    - Leave the CA Email Address field empty.
    - Choose "Saved to disk" saving it to the desktop, and click Continue. Filename is CertificateSigningRequest.certSigningRequest


    #### Keychain Access App - Step 2) Import the new certificate from your developer account to your Keychain:

    - go to https://developer.apple.com/account > Certificates > + (to add a new certificate) > Select the certificate type (Apple Development, Apple Distribution, Mac Installer Distribution) > click the continue button > Choose File > Double-click the certificate file you downloaded above > Download the new certificate file > Double click the downloaded file and it will be automatically loaded to your keychain.
    - Delete the CertificateSigningRequest.certSigningRequest and the certificate download files from the desktop.

    <br>
    <h4>View the certificates: </h4>
    <li>To view the certificates in XCode: Open XCode > Click the XCode menu > Select Preferences > Click Accounts > If you have multiple apps select the relevant appleID and Team > Click the Manage Certificates button - This will show your list of certificates.</li>
    <li>To view the certificates in your keychain: Open the Keychain Access app in the Application Utilities folder > Click on the Login Keychain (should be selected by default) > Select Category: MyCertificates - this should display your certificates along with your Team Name and ID number. For a solo developer your team name is just your name.</li>
    <li>To view the certificates in you developer account go to developer.apple.com > Certificates, IDs, & Profiles menu > Certificates menu > Development, Distribution and Mac Installer Distribution type certificates should be listed there. Or go directly to https://developer.apple.com/account/resources/certificates/list</li>

    <hr>
    <h3>Step 4) Create an App ID</h3>
    <li>Go to your developer account - developer.apple.com > Certificates, IDs & Profiles > Identifiers > + (to add a new id) > select App IDs > continue button.</li>
    <li>On the Register App ID page:</li>
    <ul>
    <li>Platform: MacOS </li>
    <li>Bundle ID: Explicit. Apple recommends using a reverse-domain name style string (i.e., com.domainname.appname). This does not need to correspond with an actual website. This will need to match the appId property in the package.json file.</li>
    <li>When done click continue, review it, then click register.</li>
    </ul>

    <hr>
    <h3>Step 5) Add the App to your developer account</h3>
    ### View the certificates:
    - To view the certificates in XCode: Open XCode > Click the XCode menu > Select Preferences > Click Accounts > If you have multiple apps select the relevant appleID and Team > Click the Manage Certificates button - This will show your list of certificates.
    - To view the certificates in your keychain: Open the Keychain Access app in the Application Utilities folder > Click on the Login Keychain (should be selected by default) > Select Category: MyCertificates - this should display your certificates along with your Team Name and ID number. For a solo developer your team name is just your name.
    - To view the certificates in you developer account go to [developer.apple.com](https://developer.apple.com) > Certificates, IDs, & Profiles menu > Certificates menu > Development, Distribution and Mac Installer Distribution type certificates should be listed there. Or go directly to https://developer.apple.com/account/resources/certificates/list

    - To view the certificates from the command line run the below. The -v option is for valid identities only:
    `security find-identity -v`

    ________________________________________________________________________________

    ## Step 4) Create an App ID
    - Go to your developer account - developer.apple.com > Certificates, IDs & Profiles > Identifiers > + (to add a new id) > select App IDs > continue button.
    - On the Register App ID page:
    - Platform: MacOS
    - Bundle ID: Explicit. Apple recommends using a reverse-domain name style string (i.e., com.domainname.appname). This does not need to correspond with an actual website. This will need to match the appId property in the package.json file.
    - When done click continue, review it, then click register.

    ________________________________________________________________________________

    ## Step 5) Add the App to your developer account
    Reference: <a href="https://developer.apple.com/help/app-store-connect/">developer.apple.com/help/app-store-connect</a> <br>
    Official instructions for adding an app: <a href="https://developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app">developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app</a>
    <li>Go to <a href="https://appstoreconnect.apple.com">appstore connect</a> </li>
    <li>Click on My Apps > + (to create a new app) > select New MacOS App > Select the appId you registered previously.</li>
    <li>Fill out the App Info section:</li>
    <ul>
    <li>Enter the name you want your app to appear on the Mac App Store as. Two apps can't have the same name so your preferred app name may be taken.</li>
    <li>Your app needs a privacy policy URL and (in another section) a support URL. </li>
    <li>Select the appropriate category for your app. See <a href="https://developer.apple.com/app-store/categories/">Category list</a>.</li>
    <li>Add a license agreement. You can use Apple's Standard License Agreement <a href="https://www.apple.com/legal/internet-services/itunes/dev/stdeula/">apple.com/legal/internet-services/itunes/dev/stdeula</a></li>
    </ul>
    <li>Fill out the Pricing and Availability section:</li>
    <ul>
    <li>Select the price you want to charge for your app. Be aware that Apple keeps 30%, or 15% if you enroll in the Small Business Program.</li>
    <li>You can also select specific countries to make your app available in. Default is the whole world. </li>
    </ul>
    <li>Fill out the MacOS section: </li>
    <ul>
    <li>For marketing you can add up to 10 screenshots and up to 3 15-30 second videos. Be aware that these must be in specific dimensions. </li>
    <li>The App Store Icon is taken from your app's icon.icns file so you don't need to upload them separately. </li>
    <li>Enter the version number using semantic versioning (e.g., starting with 1.0.0).</li>
    <li>If your app requires any entitlements enter them here along with the explanation as to why you need that entitlement. The app will be rejected if you request entitlements you don't need. See the Entitlements section below for details. </li>
    <li>Enter the support URL (required) and a marketing URL (optional).</li>
    <li>When you upload your app (using the Transporter App - discussed below) you need to select it here. </li>
    <li>You can add attachments that may be useful to the reviewer such as a video of how to use the app (can be any dimensions). </li>
    </ul>

    <hr>
    <h3>Step 6) Create an icon set </h3>
    - Go to <a href="https://appstoreconnect.apple.com">appstore connect</a>
    - Click on My Apps > + (to create a new app) > select New MacOS App > Select the appId you registered previously.
    - Fill out the App Info section:
    - Enter the name you want your app to appear on the Mac App Store as. Two apps can't have the same name so your preferred app name may be taken.
    - Your app needs a privacy policy URL and (in another section) a support URL.
    - Select the appropriate category for your app. See <a href="https://developer.apple.com/app-store/categories/">Category list</a>.
    - Add a license agreement. You can use Apple's Standard License Agreement <a href="https://www.apple.com/legal/internet-services/itunes/dev/stdeula/">apple.com/legal/internet-services/itunes/dev/stdeula</a>

    - Fill out the Pricing and Availability section:
    - Select the price you want to charge for your app. Be aware that Apple keeps 30%, or 15% if you enroll in the Small Business Program.
    - You can also select specific countries to make your app available in. Default is the whole world.

    - Fill out the MacOS section:
    - For marketing you can add up to 10 screenshots and up to 3 15-30 second videos. Be aware that these must be in specific dimensions.
    - The App Store Icon is taken from your app's icon.icns file so you don't need to upload them separately.
    - Enter the version number using semantic versioning (e.g., starting with 1.0.0).
    - If your app requires any entitlements enter them here along with the explanation as to why you need that entitlement. The app will be rejected if you request entitlements you don't need. See the Entitlements section below for details.
    - Enter the support URL (required) and a marketing URL (optional).
    - When you upload your app (using the Transporter App - discussed below) you need to select it here.
    - You can add attachments that may be useful to the reviewer such as a video of how to use the app (can be any dimensions).
    ________________________________________________________________________________

    ## Step 6) Entitlements
    Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a>
    - Make parent and child entitlement property list files using XML. Put them in the build folder.
    - These files correspond to the entitlements and entitlementsInherit keys in the package.json file.
    ### The parent entitlement file:
    <b>/build/entitlements.mas.plist </b>
    ```js
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    <key>com.apple.security.app-sandbox</key><true/>
    <key>com.apple.security.application-groups</key>
    <array>
    <string><TEAM_ID.com.companyname.appname></string>
    </array>
    <!-- Put any entitlements your app requires here. Below is an example -->
    <key>com.apple.security.files.user-selected.read-write</key><true/>
    </dict>
    </plist>
    ```

    ### Child entitlement file (inherits from the parent):
    __/build/entitlements.mas.inherit.plist__
    ```js
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    <key>com.apple.security.app-sandbox</key><true/>
    <key>com.apple.security.inherit</key><true/>
    </dict>
    </plist>
    ```
    - First thing to notice is app-sandbox is set to true. All apps in the MAS must be sandboxed. That means they don't have access to resources outside the app, unless you specifically request an exception (an entitlement) and it is approved. For example to be able to read and write to files in the user's computer (outside the app) you need to request user-selected files read-write access. If approved your app can read/write files that users have specifically opened or saved using the mac Open or Save dialog box.
    - These entitlements must correspond to the entitlements you request for your app in Appstoreconnect.apple.com
    - Read about entitlements <a href="https://developer.apple.com/documentation/bundleresources/entitlements">here</a>.
    - The list of available app sandbox entitlement keys are <a href="https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html">here</a>.
    - The application-groups key is an array containing your app identifier (TeamID and appId).
    ________________________________________________________________________________
    ## Step 7) Generate two Provisioning Profiles (AppleDevelopment and MacAppStore)
    - Go to your apple developer account profiles page <a href="https://developer.apple.com/account/resources/profiles/list">developer.apple.com/account/resources/profiles/list</a>
    - These expire after one year, so if you are updating your app, run the command at the bottom of 9a and 9b to see the expiration date. If they are expired you need to recreate them.
    ### 7a) Generate the AppleDevelopment Provisioning Profile
    - Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.
    - Select "macOS App Development". Then click Continue.
    - Select your appID, then click continue.
    - Give it a recognizable name like "AppleDevelopment", then download it to your computer.
    - Double click the file to install it, then place it in the project's build directory. The file name would be AppleDevelopment.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.
    - This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command:
    `security cms -D -i build/AppleDevelopment.provisionprofile`
    ### 7b) Generate the MacAppStore Provisioning Profile
    - Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.
    - Select Mac App Store. Then click Continue.
    - Select your appID, then click continue.
    - Select your Mac App Distribution certificate, then click continue.
    - Give it a recognizable name like "MacAppStore", then download it to your computer.
    - Double click the file to install it, then place it in the project's build directory. The file name would be MacAppStore.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.
    - This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command:
    `security cms -D -i build/MacAppStore.provisionprofile`
    ________________________________________________________________________________
    ## Step 8) Create an icon set
    Reference: <a href="https://www.electron.build/icons">electron.build/icons</a> | <a href="https://developer.apple.com/design/human-interface-guidelines/app-icons">developer.apple.com/design/human-interface-guidelines/app-icons</a>
    <li>You need to create your icon in at least two different sizes: 512x512 px and 1024x1024 px saved as png files. But ideally use all the Apple recommended sizes which additionally include 16x16, 32x32, 64x64, 128x128 and 256x256.</li>
    <li>This is a useful guide: <a href="https://elliotekj.com/posts/2014/05/27/how-to-create-high-resolution-icns-files/">How to create high resolution icns files</a>. A few things to highlight:</li>
    <ul>
    <li>Make a folder called icon.iconset (or any name that has .iconset as the extension) to hold the images.</li>
    <li>Use Apple's naming convention for the image files (e.g., icon_512x512.png, [email protected], etc.).</li>
    <li>The @2x files are double the size stated in terms of pixels. However in terms of display, Apple just doubles the density of the pixels instead of doubling the width and height. As such, some of the files will be the same image dimensions but two different files (e.g., [email protected] and icon_512x512.png are two separate files but are the same image size). If you are simplifying the images at smaller sizes, make sure the @2x image is the same as the 1x, just at double the size.</li>
    <li>When you get down to the small sizes such as icon_16x16.png you'll likely need to simplify the image, otherwise it will just look blurry.</li>
    <li>Convert the iconset into an icns file in the Terminal from the directory holding the icon.iconset folder with the png images. Enter the iconutil command:</li>
    <li class="dlr"><code>iconutil -c icns icon.iconset</code></li>
    <li>Put the resulting icon.icns file into the build folder of your electron project.</li>
    </ul>

    <hr>
    <h3>Step 7) package.json file </h3>
    <h4>7a) Local version</h4>
    <p>You can build a local version of your app not for distribution, by excluding the "mac" key from the package.json file. This will build a packaged version of your app, a zipped version, and a dmg installer. All are unsigned so they are cannot be distributed to other users that way.</p>
    <p>The values in italics need to be changed to your info.</p>
    <pre>
    - You need to create your icon in at least two different sizes: 512x512 px and 1024x1024 px saved as png files. But ideally use all the Apple recommended sizes which additionally include 16x16, 32x32, 64x64, 128x128 and 256x256.
    - This is a useful guide: <a href="https://elliotekj.com/posts/2014/05/27/how-to-create-high-resolution-icns-files/">How to create high resolution icns files</a>. A few things to highlight:
    - Make a folder called icon.iconset (or any name that has .iconset as the extension) to hold the images.
    - Use Apple's naming convention for the image files (e.g., icon_512x512.png, [email protected], etc.).
    - The @2x files are double the size stated in terms of pixels. However in terms of display, Apple just doubles the density of the pixels instead of doubling the width and height. As such, some of the files will be the same image dimensions but two different files (e.g., [email protected] and icon_512x512.png are two separate files but are the same image size). If you are simplifying the images at smaller sizes, make sure the @2x image is the same as the 1x, just at double the size.
    - When you get down to the small sizes such as icon_16x16.png you'll likely need to simplify the image, otherwise it will just look blurry.
    - Convert the iconset into an icns file in the Terminal from the directory holding the icon.iconset folder with the png images. Enter the iconutil command:
    `iconutil -c icns icon.iconset`
    - Put the resulting icon.icns file into the build folder of your electron project.
    ________________________________________________________________________________
    ## Step 9) package.json file
    Electron-builder API lists the build properties: https://www.electron.build/configuration/mac.html
    ### 9a) Local version
    You can build a local version of your app not for distribution, by excluding the "mac" key from the package.json file. This will build a packaged version of your app, a zipped version, and a dmg installer.
    The values in angled brackets need to be changed to your info then remove the brackets.
    The postinstall script is only needed if your app uses native node dependencies (see Native Node NPM packages at the end).
    ```js
    {
    "name": "<i>AppName</i>",
    "version": "<i>1.0.0</i>",
    "name": "<AppName>",
    "version": "<1.0.0>",
    "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
    },
    ...
    "author": "<i>AuthorName</i>",
    "author": "<AuthorName>",
    "build": {
    "appId": "<i>com.companyname.appname</i>",
    "productName": "<i>App Name (can include spaces & special characters)</i>",
    "buildVersion": "<i>1.0.0</i>",
    "copyright": "Copyright © 2023 <i>Developer or Company Name</i>",
    "appId": "<com.companyname.appname>",
    "productName": "<App Name (can include spaces & special characters)>",
    "buildVersion": "<1.0.0>",
    "copyright": "Copyright © 202X <Developer or Company Name>",
    "files": [
    "!<i>file-or-directory-name-to-exclude"</i>
    "!<file-or-directory-name-to-exclude>"
    ]
    }
    ...
    }
    </pre>
    ```
    <h4>7b) MAS Development version (for testing)</h4>
    <p>This is a test version of the MAS build, which you can run on your development computer.</p>
    <p>The values in italics need to be changed to your info.</p>
    <pre>
    ### 9b) MAS Development version (for testing)
    This is a test version of the MAS build, which you can run on your development computer.
    ```js
    {
    "name": "<i>AppName</i>",
    "version": "<i>1.0.0</i>",
    "name": "<AppName>",
    "version": "<1.0.0>",
    "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
    },
    ...
    "author": "<i>AuthorName</i>",
    "author": "<AuthorName>",
    "build": {
    "appId": "<i>com.companyname.appname</i>",
    "productName": "<i>App Name (can include spaces & special characters)</i>",
    "buildVersion": "<i>1.0.0</i>",
    "copyright": "Copyright © 2023 <i>Developer or Company Name</i>",
    "appId": "<com.companyname.appname>",
    "productName": "<App Name (can include spaces & special characters)>",
    "buildVersion": "<1.0.0>",
    "copyright": "Copyright © 202X <Developer or Company Name>",
    "files": [
    "!<i>file-or-directory-name-to-exclude"</i>
    "!<file-or-directory-name-to-exclude>"
    ],
    "mac": {
    "category": "public.app-category.<i>categoryName</i>",
    "category": "public.app-category.<categoryName>",
    "icon": "build/icon.icns",
    "target": "mas-dev",
    "type": "development",
    @@ -186,195 +256,216 @@ Reference: <a href="https://www.electron.build/icons">electron.build/icons</a> |
    }
    ...
    }
    </pre>
    ```
    <h4>7c) MAS Distribution version (for submission to the Mac App Store)</h4>
    <p>This builds a pkg installer for submission to the MAS. It changes the target, type, and provisioningProfile from 7b above.
    <p>The values in italics need to be changed to your info.</p>
    <pre>
    ### 9c) MAS Distribution version (for submission to the Mac App Store)
    This builds a pkg installer for submission to the MAS. It changes the target, type, and provisioningProfile from 7b above.
    ```js
    {
    "name": "<i>AppName</i>",
    "version": "<i>1.0.0</i>",
    "name": "<AppName>",
    "version": "<1.0.0>",
    "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
    },
    ...
    "author": "<i>AuthorName</i>",
    "build": {
    "appId": "<i>com.companyname.appname</i>",
    "productName": "<i>App Name (can include spaces & special characters)</i>",
    "buildVersion": "<i>1.0.0</i>",
    "copyright": "Copyright © 2023 <i>Developer or Company Name</i>",
    "author": "<AuthorName>",
    "build": {
    "appId": "<com.companyname.appname>",
    "productName": "<App Name (can include spaces & special characters)>",
    "buildVersion": "<1.0.0>",
    "copyright": "Copyright © 202X <Developer or Company Name>",
    "files": [
    "!<i>file-or-directory-name-to-exclude"</i>
    "!<file-or-directory-name-to-exclude>"
    ],
    "mac": {
    "category": "public.app-category.<i>categoryName</i>",
    "icon": "build/icon.icns",
    "target": "mas",
    "type": "distribution",
    "hardenedRuntime": false,
    "hardenedRuntime": false,
    "category": "public.app-category.<categoryName>",
    "icon": "build/icon.icns",
    "provisioningProfile": "build/MacAppStore.provisionprofile",
    "entitlements": "build/entitlements.mas.plist",
    "entitlementsInherit": "build/entitlements.mas.inherit.plist"
    }
    }
    ...
    }
    </pre>
    <p>Only include the postinstall script above if you have native dependencies that need to be recompiled by Electron (see Native Node NPM packages at the bottom).</p>
    <b>Reference:</b>
    <li>General configuration including metadata: <a href="https://www.electron.build/configuration/configuration">electron.build/configuration/configuration</a></li>
    <li>Mac-general configuration: <a href="https://www.electron.build/configuration/mac">electron.build/configuration/mac</a></li>
    <li>MAS-specific configuration: <a href="https://www.electron.build/configuration/mas">electron.build/configuration/mas</a></li>

    <br>
    <b>package.json keys:</b>
    <li>Name and productName: The name key will be used as the display name for your app on the user's computer. It cannot contain spaces or special characters. If you want to use spaces or special characters in the name then add a productName key within the build key. You set the name of your app as it appears in the Mac App Store at appstoreconnect.apple.com. </li>
    <li>Version number and build number: The version number in package.json should correspond with the version number of your app at appstoreconnect.apple.com. If you upload your app to appstoreconnect but decide to make changes before submitting it for review, you can't delete what you uploaded. Rather you submit a revised app with a different build number. The build number defaults to the version number. To set a different build number, use the buildVersion property.</li>
    <li>Use the same appId as you created for your app at developer.apple.com.</li>
    <li>files: You can add an array of file and directory names to exclude from the build. Preface each name with a "!" to indicate that the file/directory should be excluded. Ref: <a href="https://www.electron.build/file-patterns.html">electron.build/file-patterns</a></li>
    <li>The category key should align with the category you set for your app in appstoreconnect.apple.com. Mac uses this key in the Finder via View > Arrange by Application Category when viewing the Applications directory. <a href="https://developer.apple.com/documentation/bundleresources/information_property_list/lsapplicationcategorytype">List of possible categories</a>.</li>
    <li>Set your target to "mas-dev" if building the development version (for testing) and "mas" if building the distribution version (to submit to the MAS).</li>
    <li>Set Hardened Runtime to false. You would set it to true if you want to distribute the app outside the MAS. For more on hardened runtime see <a href="https://developer.apple.com/documentation/security/hardened_runtime">developer.apple.com/documentation/security/hardened_runtime</a></li>
    <li>Set type to "development" for the development version, "distribution" for the MAS version.</li>

    <br>
    ```
    Only include the postinstall script above if you have native dependencies that need to be recompiled by Electron (see Native Node NPM packages below).
    #### Reference:
    - General configuration including metadata: <a href="https://www.electron.build/configuration/configuration">electron.build/configuration/configuration</a>
    - Mac-general configuration: <a href="https://www.electron.build/configuration/mac">electron.build/configuration/mac</a>
    - MAS-specific configuration: <a href="https://www.electron.build/configuration/mas">electron.build/configuration/mas</a>
    #### package.json keys:
    - Name and productName: The name key will be used as the display name for your app on the user's computer. It cannot contain spaces or special characters. If you want to use spaces or special characters in the name then add a productName key within the build key. You set the name of your app as it appears in the Mac App Store at appstoreconnect.apple.com.
    - Version number and build number: The version number in package.json should correspond with the version number of your app at appstoreconnect.apple.com. If you upload your app to appstoreconnect but decide to make changes before submitting it for review, you can't delete what you uploaded. Rather you submit a revised app with a different build number. The build number defaults to the version number. To set a different build number, use the buildVersion property.
    - Use the same appId as you created for your app at developer.apple.com.
    - files: You can add an array of file and directory names to exclude from the build. Preface each name with a "!" to indicate that the file/directory should be excluded. Ref: <a href="https://www.electron.build/file-patterns.html">electron.build/file-patterns</a>.
    - The category key should align with the category you set for your app in appstoreconnect.apple.com. Mac uses this key in the Finder via View > Arrange by Application Category when viewing the Applications directory. <a href="https://developer.apple.com/documentation/bundleresources/information_property_list/lsapplicationcategorytype">List of possible categories</a>.
    - Set your target to "mas-dev" if building the development version (for testing) and "mas" if building the distribution version (to submit to the MAS).
    - Set Hardened Runtime to false. You would set it to true if you want to distribute the app outside the MAS. For more on hardened runtime see <a href="https://developer.apple.com/documentation/security/hardened_runtime">developer.apple.com/documentation/security/hardened_runtime</a>
    - Set type to "development" for the development version, "distribution" for the MAS version.
    <b>Keys you don't need to set because the default is already correct:</b>
    <li>The icon key points to where your icon.icns file is. The default folder and filename is build/icon.icns so you can leave it out if it is located there.</li>
    <li>The type key can be distribution or development. Distribution is the default so you can leave this key out. </li>
    <li>The identity key sets the name of the certificate to use when signing. However, for the MAS build, the signing certificate will be taken from the provisioning profile (covered below). And Electron-builder will automatically use the 3rd Party Mac Developer Installer certificate in your Keychain to sign the pkg file.</li>
    <li>GatekeeperAssess key is set to false by default. Mac's Gatekeeper ensures that apps distributed outside the app store are signed and notarized. Since this build is for the MAS you can leave this at false.</li>
    - The icon key points to where your icon.icns file is. The default folder and filename is build/icon.icns so you can leave it out if it is located there.
    - The type key can be distribution or development. Distribution is the default so you can leave this key out.
    - The identity key sets the name of the certificate to use when signing. However, for the MAS build, the signing certificate will be taken from the provisioning profile (covered below). And Electron-builder will automatically use the 3rd Party Mac Developer Installer certificate in your Keychain to sign the pkg file.
    - GatekeeperAssess key is set to false by default. Mac's Gatekeeper ensures that apps distributed outside the app store are signed and notarized. Since this build is for the MAS you can leave this at false.
    ________________________________________________________________________________
    ## Step 10) Build a development and distribution versions of the App with electron-builder
    - Install electron-builder as a development dependency:
    `npm install -D electron-builder`
    - Optionally, you can build an unsigned local version of your app that is not packaged for the Mac App Store. Use the 9a version of the package.json file.
    - Build the MAS-development version of the app using the 9b version of package.json above, which uses the AppleDevelopment.provisionprofile, and the Development signing certificate. Use this to test the MAS version on your computer.
    `npm run dist`
    - After testing the Development version of the app, build the MAS distribution version and .pkg installer. Use the 9c version of package.json, the MacAppStore.provisionprofile, and the Distribution and Mac Installer Distribution signing certificates.
    `npm run dist`
    If you get a "command not found" error, then include the relative path. Here are the direct commands with the path:
    Mac: `./node_modules/.bin/electron-builder`
    Windows: `.\node_modules\.bin\electron-builder.cmd`
    ________________________________________________________________________________
    ## Step 11) Test the app
    Test the Development version of the app before building the distribution version. Make sure it works as expected.
    Then build the distribution version. This version will crash and give you a signing error if you try to open it on your computer. It must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store. However, there are some checks you can make before submitting it to Apple.
    - You can test the signature if you have X-Code's CLI utilities installed. To check that your app is signed, go to the directory holding your app (e.g., MyApp/dist/mas) and enter the below command. If the app is signed it will display the details in the Terminal.
    `codesign --display --verbose=2 <AppName>.app`
    - To check that the .pkg file is signed, enter the below command from the .pkg file's directory. If it is signed it will display the details in the Terminal.
    `pkgutil --check-signature <AppName>-1.0.0.pkg`
    - The Transporter app (see next section) has built-in checks on your app that will let you know about some (but not all) problems with your app. Simply load the app in the Transporter and it will do several checks. If everything is okay, you can click the deliver button to send it to appstore connect. Then you can submit it for review.
    - If you are getting errors you could start by making sure all the basics are working by using this process on a simple Electron app like the <a href="https://github.com/steve981cr/electron-app-store-example">Electron App Store Example</a> app on Github. Just add in your developer and app datails and provisioning profile.
    ________________________________________________________________________________
    ## Step 12) Upload the pkg file
    - There are three different tools you can use to upload the pkg file: <a href="https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds">developer.apple.com/help/app-store-connect/manage-builds/upload-builds</a>.
    - The preferred tool is the <a href="https://apps.apple.com/us/app/transporter/id1450874784">Transporter app</a> which can be downloaded free from the Mac App Store.
    - Open the Transporter app > Drag and drop your Electron app's pkg file into the Transporter app.
    - It will check for errors. If no errors found click the Deliver button to send the app to your developer account.
    - Go to <a href="https://appstoreconnect.apple.com">appstoreconnect.apple.com</a> and click MyApps > Prepare for Submission > Build + icon > Select the uploaded file - Done
    - Note: the build may have a "Missing Compliance" warning next to it. If so, when you submit the app you will be asked about any encryption in your app, so just answer the questions given. See <a href="https://www.electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#cryptographic-algorithms-used-by-electron">electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#cryptographic-algorithms-used-by-electron</a>
    - If you are ready to submit the app for review then click "Submit for review".
    - If you decide to make additional changes before submitting for review, you have to load another .pkg file through the Transporter app with a higher build number (e.g., 1.0.1).
    ________________________________________________________________________________
    ## Native Node NPM packages
    <p>Reference: <a href="https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules">electronjs.org/docs/latest/tutorial/using-native-node-modules</a>
    Native node modules are npm packages that include C or C++ code.
    ### Recompile native Node dependencies for Electron
    C/C++ code must be compiled into executable binaries. Even if the modules are precompiled when installed, they must be recompiled for Electron.
    <hr>
    <h3>Step 8) Entitlements</h3>
    Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a>
    <li>Make parent and child entitlement property list files using XML. Put them in the build folder. </li>
    <li>These files correspond to the entitlements and entitlementsInherit keys in the package.json file. </li>
    <h4>The parent entitlement file: </h4>
    <b>/build/entitlements.mas.plist </b>
    <pre>
    &lt;?xml version="1.0" encoding="UTF-8"?>
    &lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    &lt;plist version="1.0">
    &lt;dict>
    &lt;key>com.apple.security.app-sandbox&lt;/key>&lt;true/>
    &lt;key>com.apple.security.application-groups&lt;/key>
    &lt;array>
    &lt;string><i>TEAM_ID.com.companyname.appname</i>&lt;/string>
    &lt;/array>
    &lt;!-- Put any entitlements your app requires here. Below is an example -->
    &lt;key>com.apple.security.files.user-selected.read-write&lt;/key>&lt;true/>
    &lt;/dict>
    &lt;/plist>
    </pre>

    <h4>Child entitlement file (inherits from the parent): </h4>
    <b>/build/entitlements.mas.inherit.plist </b>
    <pre>
    &lt;?xml version="1.0" encoding="UTF-8"?>
    &lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    &lt;plist version="1.0">
    &lt;dict>
    &lt;key>com.apple.security.app-sandbox&lt;/key>&lt;true/>
    &lt;key>com.apple.security.inherit&lt;/key>&lt;true/>
    &lt;/dict>
    &lt;/plist>
    </pre>

    <li>First thing to notice is app-sandbox is set to true. All apps in the MAS must be sandboxed. That means they don't have access to resources outside the app, unless you specifically request an exception (an entitlement) and it is approved. For example to be able to read and write to files in the user's computer (outside the app) you need to request user-selected files read-write access. If approved your app can read/write files that users have specifically opened or saved using the mac Open or Save dialog box. </li>
    <li>These entitlements must correspond to the entitlements you request for your app in Appstoreconnect.apple.com </li>
    <li>Read about entitlements <a href="https://developer.apple.com/documentation/bundleresources/entitlements">here</a>.</li>
    <li>The list of available app sandbox entitlement keys are <a href="https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html">here</a>.</li>
    <li>The application-groups key is an array containing your app identifier (TeamID and appId). </li>


    <hr>
    <h3>Step 9) Generate two Provisioning Profiles (AppleDevelopment and MacAppStore)</h3>
    <li>Go to your apple developer account profiles page <a href="https://developer.apple.com/account/resources/profiles/list">developer.apple.com/account/resources/profiles/list</a></li>
    <li>These expire after one year, so if you are updating your app, run the command at the bottom of 9a and 9b to see the expiration date. If they are expired you need to recreate them.</li>

    <h4>9a) Generate the AppleDevelopment Provisioning Profile</h4>
    <li>Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.</li>
    <li>Select "macOS App Development". Then click Continue.</li>
    <li>Select your appID, then click continue.</li>
    <li>Give it a recognizable name like "AppleDevelopment", then download it to your computer.</li>
    <li>Double click the file to install it, then place it in the project's build directory. The file name would be AppleDevelopment.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.</li>
    <li>This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command: </li>
    <li class="dlr"><code>security cms -D -i build/AppleDevelopment.provisionprofile</code></li>

    <h4>9b) Generate the MacAppStore Provisioning Profile</h4>
    <li>Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.</li>
    <li>Select Mac App Store. Then click Continue.</li>
    <li>Select your appID, then click continue.</li>
    <li>Select your Mac App Distribution certificate, then click continue.</li>
    <li>Give it a recognizable name like "MacAppStore", then download it to your computer.</li>
    <li>Double click the file to install it, then place it in the project's build directory. The file name would be MacAppStore.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.</li>
    <li>This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command: </li>
    <li class="dlr"><code>security cms -D -i build/MacAppStore.provisionprofile</code></li>

    <hr>
    <h3>Step 10) Build a development and distribution versions of the App with electron-builder</h3>
    <li>Install electron-builder as a development dependency: </li>
    <span class="dlr"><code>npm install -D electron-builder</code></span>
    <li>Optionally, you can build an unsigned local version of your app that is not packaged for the Mac App Store. Use the 7a version of the package.json file.</li>
    <li>Build the MAS-development version of the app using the 7b version of package.json above, which uses the AppleDevelopment.provisionprofile, and the Development signing certificate. Use this to test the MAS version on your computer.</li>
    <span class="dlr"><code>npm run dist</code></span>
    <li>After testing the Development version of the app, build the MAS distribution version and .pkg installer. Use the 7c version of package.json, the MacAppStore.provisionprofile, and the Distribution and Mac Installer Distribution signing certificates.</li>
    <span class="dlr"><code>npm run dist</code></span>

    <p>If you get a "command not found" error, then include the relative path. Here are the direct commands with the path:<br>
    Mac: <code>./node_modules/.bin/electron-builder</code><br>
    Windows: <code>.\node_modules\.bin\electron-builder.cmd</code>
    </p>

    <hr>
    <h3>Step 11) Test the app</h3>
    <p>Test the Development version of the app before building the distribution version. Make sure it works as expected.</p>
    <p>Then build the distribution version. This version will crash and give you a signing error if you try to open it on your computer. It must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store. However, there are some checks you can make before submitting it to Apple.</p>

    <li>You can test the signature if you have X-Code's CLI utilities installed. To check that your app is signed, go to the directory holding your app (e.g., MyApp/dist/mas) and enter the below command. If the app is signed it will display the details in the Terminal.</li>
    <li class="dlr"><code>codesign --display --verbose=2 <i>MyApp</i>.app</code></li>
    <li>To check that the .pkg file is signed, enter the below command from the .pkg file's directory. If it is signed it will display the details in the Terminal.</li>
    <li class="dlr"><code>pkgutil --check-signature <i>MyApp</i>-1.0.0.pkg</code></li>
    <li>The Transporter app (see next section) has built-in checks on your app that will let you know about some (but not all) problems with your app. Simply load the app in the Transporter and it will do several checks. If everything is okay, you can click the deliver button to send it to appstore connect. Then you can submit it for review.</li>
    <li>If you are getting errors you could start by making sure all the basics are working by using this process on a simple Electron app like the <a href="https://github.com/steve981cr/electron-app-store-example">Electron App Store Example</a> app on Github. Just add in your developer and app datails and provisioning profile.</li>


    <hr>
    <h3>Step 12) Upload the pkg file</h3>
    <li>There are three different tools you can use to upload the pkg file: <a href="https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds">developer.apple.com/help/app-store-connect/manage-builds/upload-builds</a>.</li>
    <li>The preferred tool is the <a href="https://apps.apple.com/us/app/transporter/id1450874784">Transporter app</a> which can be downloaded free from the Mac App Store.</li>
    <li>Open the Transporter app > Drag and drop your Electron app's pkg file into the Transporter app.</li>
    <li>It will check for errors. If no errors found click the Deliver button to send the app to your developer account.</li>
    <li>Go to <a href="https://appstoreconnect.apple.com">appstoreconnect.apple.com</a> and click MyApps > Prepare for Submission > Build + icon > Select the uploaded file - Done</li>
    <li>Note: the build may have a "Missing Compliance" warning next to it. If so, when you submit the app you will be asked about any encryption in your app, so just answer the questions given. See <a href="https://www.electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#cryptographic-algorithms-used-by-electron">electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#cryptographic-algorithms-used-by-electron</a>
    <li>If you are ready to submit the app for review then click "Submit for review".</li>
    <li>If you decide to make additional changes before submitting for review, you have to load another .pkg file through the Transporter app with a higher build number (e.g., 1.0.1).</li>

    <hr>
    <h3>Native Node NPM packages</h3>
    <p>Reference: <a href="https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules">electronjs.org/docs/latest/tutorial/using-native-node-modules</a></p>

    <p>
    Native node modules are npm packages that include C or C++ code.<br>
    C/C++ code must be compiled into executable binaries. Even if the modules are precompiled when installed, they must be recompiled for Electron. Electron-builder will do that automatically when you run the electron-builder script <code>npm run dist</code>.<br>
    To recompile native modules in development, you can add the below script to your package.json file:
    <pre>
    ```js
    "postinstall": "electron-builder install-app-deps"
    </pre>
    ```
    After installing native modules, run the script: `npm run postinstall`
    Then after installing native modules, run the script: <code>npm run postinstall</code>
    </p>
    <p>If you don't recompile native modules, and try to run the app, you will get an error that says something like:
    <pre>
    If you don't recompile native modules, and try to run the app, you will get an error that says something like:
    ```
    Error: The module '/path/to/native/module.node'
    was compiled against a different Node.js version using
    NODE_MODULE_VERSION $XYZ. This version of Node.js requires
    NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
    the module (for instance, using `npm rebuild` or `npm install`).
    </pre>
    ```

    ### Code Sign native Node dependencies
    Electron builder compiles the app into a format called ASAR (stands for Atom Shell Archive Format)
    Ref: https://www.electronjs.org/docs/latest/glossary#asar

    Native modules must be pulled out of your built binary app and code signed separately.

    In the build script add an asarUnpack property. The value is an array where uou list all files that need to be pulled out. The files we need to pull out are binary files that have a .node extension. Use wildcards for the directory and filename:
    ```json
    "build": {
    ...
    "mac":
    ...
    "asarUnpack": ["**/*.node"]
    }
    }
    ```
    The file will be placed in your app file in Contents/Resources/app.asar.unpacked/node_modules/<module name>

    Electron-builder will automatically sign this binary when you run the dist command.

    Its binary file will be pulled out of your app's asar binary file. You can confirm that it is code signed with the below command. Replace <AppName> with the name of your app, and use the correct path to the .node file:
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app/Contents/Resources/app.asar.unpacked/node_modules/path/to/filename.node`

    _________________________________________________
    _________________________________________________

    # Release an update
    To submit an updated version of your app to the Mac App Store, make sure you have unexpired versions of the following:

    ### Apple Certificates:
    Certificate | Use | Expires
    ----------- | --- | -------
    Apple Development | MAS dev | Expires in one year
    Apple Distribution | MAS | Expires in one year
    Mac Installer Distribution | MAS installer | Expires in one year


    View your certificates: https://developer.apple.com/account/resources/certificates/list<br>
    Or from the command line: `security find-identity -v`

    ---

    ### Entitlements:
    Entitlements | Use | Expires
    ------------ | --- | -------
    entitlements.mas.plist | MAS | no expiration
    entitlements.mas.inherit.plist | MAS | no expiration

    Put your entitlement files in the build directory.

    ---

    #### Provisioning Profiles
    File | Use | Expires
    ---- | --- | -------
    AppleDevelopment.provisionprofile | MAS dev | Expires in one year
    MacAppStore.provisionprofile | MAS | Expires in one year

    View/Add: https://developer.apple.com/account/resources/profiles/list

    To read the files enter:
    `security cms -D -i build/AppleDevelopment.provisionprofile`

    `security cms -D -i build/MacAppStore.provisionprofile`

    Put files in the build directory.


    - Change the version number in the package.json file.
    - Ideally, upgrade to the latest versions of all your npm packages including electron and electron-builder.

    Build it with `npm run dist`

    Confirm that the app and pkg installer are signed:
    `codesign --display --verbose=2 dist/mas-dev/<AppName>.app`
    `pkgutil --check-signature dist/mas/<AppName>-1.0.0.pkg`

    <p>Native modules must be pulled out of your built binary app and code signed separately. This is done automatically by electron-builder.</p>
    Go to the app in your Apple Developer account: https://appstoreconnect.apple.com/apps
    Click on your app.<br>
    Click the + sign in the lleft panel to add a new version.<br>
    Enter the new version number using semantic versioning (e.g., 1.0.1).<br>
    Fill out: What's New in This Version.<br>
    Submit the new app version with the Transporter app.<br>
    Submit it for review.<br>
  17. @steve981cr steve981cr revised this gist Jun 25, 2023. 1 changed file with 6 additions and 2 deletions.
    8 changes: 6 additions & 2 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -28,7 +28,11 @@
    <hr>
    <h3>Step 2) Apple Developer Account </h3>
    <p>You need an Apple Developer Account. Costs ~$100/year. Sign up at <a href="https://developer.apple.com">developer.apple.com</a>.</p>

    <p>And sign up for the App Store's Small Business Program (for developers with revenue under $1 million/year):
    <a ref="https://developer.apple.com/app-store/small-business-program/">developer.apple.com/app-store/small-business-program</a><br>
    If approved, Apple's commission drops from 30% to 15%.
    </p>

    <hr>
    <h3>Step 3) Create Three Signing Certificates:</h3>
    <ul>
    @@ -89,7 +93,7 @@ Official instructions for adding an app: <a href="https://developer.apple.com/he
    </ul>
    <li>Fill out the Pricing and Availability section:</li>
    <ul>
    <li>Select the price you want to charge for your app. Be aware that Apple keeps 30%.</li>
    <li>Select the price you want to charge for your app. Be aware that Apple keeps 30%, or 15% if you enroll in the Small Business Program.</li>
    <li>You can also select specific countries to make your app available in. Default is the whole world. </li>
    </ul>
    <li>Fill out the MacOS section: </li>
  18. @steve981cr steve981cr created this gist Jun 23, 2023.
    376 changes: 376 additions & 0 deletions How-to-Release-an-Electron-App-on-the-Mac-App-Store.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,376 @@
    <div class="page-header">
    <h1>How to Release an Electron App on the Mac App Store</h1>
    <p>By Steve Carey - Last updated June 20, 2023. Originally published Feb 4, 2020.</p>
    <p>Example Code: <a href="https://github.com/steve981cr/electron-app-store-example">Github electron-app-store-example</a></p>
    </div>

    <div class="slightly-shrink-font">
    <h2>Introduction</h2>
    <p>You have three options for distributing an Electron App for MacOS. Through the Mac App Store (MAS), through a third party platform like GitHub Marketplace, or directly (e.g, download from your website). Apple prefers you distribute through the Mac App Store. Partly because they review all apps before they can be put on the Mac App Store so end users can feel confident that the app is safe. And partly because they take a cut of app revenue purchased through the MAS. This tutorial focuses on the steps required to put your app on the MAS.</p>

    <p>All apps distributed though the MAS must be sandboxed, meaning they are completely self contained except for any approved entitlements.</p>

    <p>There are a few options for packaging the app. We will use Electron-Builder.</li>

    <p>You will need to package two versions of your app. A development version for testing, and a distribution version for submission to Apple.</p>

    <p>Apple Reference: <a href="https://developer.apple.com/app-store/review/">developer.apple.com/app-store/review</a><br>
    <a href="https://developer.apple.com/app-store/review/guidelines/">developer.apple.com/app-store/review/guidelines</a></p>
    <p>Electron Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a></p>
    <p>Electron-builder Reference: <a href="https://www.electron.build/configuration/mac">electron.build/configuration/mac</a><br>
    &emsp; and <a href="https://www.electron.build/configuration/mas">electron.build/configuration/mas</a>
    </p>
    <hr>
    <h3>Step 1) Start with your completed Electron Application.</h3>
    <p class='mb-1'>Electron should be a development dependency.</p>
    <li class="dlr"><code>npm install -D electron</code></li>

    <hr>
    <h3>Step 2) Apple Developer Account </h3>
    <p>You need an Apple Developer Account. Costs ~$100/year. Sign up at <a href="https://developer.apple.com">developer.apple.com</a>.</p>

    <hr>
    <h3>Step 3) Create Three Signing Certificates:</h3>
    <ul>
    <li><b>Apple Development:</b> used to sign apps for development and testing on machines that have been registered on the Apple Developer website.</li>
    <li><b>Apple Distribution:</b> used to sign apps submitted to the Mac App Store.</li>
    <li><b>Mac Installer Distribution:</b> used to sign the Mac Installer Package in addition to the app itself.</li>
    </ul>

    <p>You can create the signing certificates with either XCode or using the Keychain Access app.</p>

    <h4>Using XCode (preferred):</h4>
    <p>Create and install these three certificates with XCode. Repeat the below process for each certificate.</p>
    <p>Open XCode > Click the XCode menu > Select Preferences > Click Accounts > Click the Manage Certificates button > Click the + button in the lower left corner > Select the certificate type to create (Apple Development, Apple Distribution, Mac Installer Distribution).</p>

    <h4>Using the Keychain Access app:</h4>
    <p>Alternatively, you can create and install these three certificates with the Keychain Access app. Repeat the below two-step process for each certificate.</p>
    <h5>Keychain Access App - Step 1) Request a certificate:</h5>
    <li>Launch Keychain Access located in /Applications/Utilities.</li>
    <li>Click the Keychain Access menu > Certificate Assistant > Request a Certificate from a Certificate Authority.</li>
    <li>In the Certificate Assistant dialog, enter an email address in the User Email Address field.</li>
    <li>In the Common Name field use the value provided. </li>
    <li>Leave the CA Email Address field empty. </li>
    <li>Choose "Saved to disk" saving it to the desktop, and click Continue. Filename is CertificateSigningRequest.certSigningRequest </li>

    <br>
    <h5>Keychain Access App - Step 2) Import the new certificate from your developer account to your Keychain:</h5>
    <li>go to https://developer.apple.com/account > Certificates > + (to add a new certificate) > Select the certificate type (Apple Development, Apple Distribution, Mac Installer Distribution) > click the continue button > Choose File > Double-click the certificate file you downloaded above > Download the new certificate file > Double click the downloaded file and it will be automatically loaded to your keychain.</li>
    <li>Delete the CertificateSigningRequest.certSigningRequest and the certificate download files from the desktop.</li>

    <br>
    <h4>View the certificates: </h4>
    <li>To view the certificates in XCode: Open XCode > Click the XCode menu > Select Preferences > Click Accounts > If you have multiple apps select the relevant appleID and Team > Click the Manage Certificates button - This will show your list of certificates.</li>
    <li>To view the certificates in your keychain: Open the Keychain Access app in the Application Utilities folder > Click on the Login Keychain (should be selected by default) > Select Category: MyCertificates - this should display your certificates along with your Team Name and ID number. For a solo developer your team name is just your name.</li>
    <li>To view the certificates in you developer account go to developer.apple.com > Certificates, IDs, & Profiles menu > Certificates menu > Development, Distribution and Mac Installer Distribution type certificates should be listed there. Or go directly to https://developer.apple.com/account/resources/certificates/list</li>

    <hr>
    <h3>Step 4) Create an App ID</h3>
    <li>Go to your developer account - developer.apple.com > Certificates, IDs & Profiles > Identifiers > + (to add a new id) > select App IDs > continue button.</li>
    <li>On the Register App ID page:</li>
    <ul>
    <li>Platform: MacOS </li>
    <li>Bundle ID: Explicit. Apple recommends using a reverse-domain name style string (i.e., com.domainname.appname). This does not need to correspond with an actual website. This will need to match the appId property in the package.json file.</li>
    <li>When done click continue, review it, then click register.</li>
    </ul>

    <hr>
    <h3>Step 5) Add the App to your developer account</h3>
    Reference: <a href="https://developer.apple.com/help/app-store-connect/">developer.apple.com/help/app-store-connect</a> <br>
    Official instructions for adding an app: <a href="https://developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app">developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app</a>
    <li>Go to <a href="https://appstoreconnect.apple.com">appstore connect</a> </li>
    <li>Click on My Apps > + (to create a new app) > select New MacOS App > Select the appId you registered previously.</li>
    <li>Fill out the App Info section:</li>
    <ul>
    <li>Enter the name you want your app to appear on the Mac App Store as. Two apps can't have the same name so your preferred app name may be taken.</li>
    <li>Your app needs a privacy policy URL and (in another section) a support URL. </li>
    <li>Select the appropriate category for your app. See <a href="https://developer.apple.com/app-store/categories/">Category list</a>.</li>
    <li>Add a license agreement. You can use Apple's Standard License Agreement <a href="https://www.apple.com/legal/internet-services/itunes/dev/stdeula/">apple.com/legal/internet-services/itunes/dev/stdeula</a></li>
    </ul>
    <li>Fill out the Pricing and Availability section:</li>
    <ul>
    <li>Select the price you want to charge for your app. Be aware that Apple keeps 30%.</li>
    <li>You can also select specific countries to make your app available in. Default is the whole world. </li>
    </ul>
    <li>Fill out the MacOS section: </li>
    <ul>
    <li>For marketing you can add up to 10 screenshots and up to 3 15-30 second videos. Be aware that these must be in specific dimensions. </li>
    <li>The App Store Icon is taken from your app's icon.icns file so you don't need to upload them separately. </li>
    <li>Enter the version number using semantic versioning (e.g., starting with 1.0.0).</li>
    <li>If your app requires any entitlements enter them here along with the explanation as to why you need that entitlement. The app will be rejected if you request entitlements you don't need. See the Entitlements section below for details. </li>
    <li>Enter the support URL (required) and a marketing URL (optional).</li>
    <li>When you upload your app (using the Transporter App - discussed below) you need to select it here. </li>
    <li>You can add attachments that may be useful to the reviewer such as a video of how to use the app (can be any dimensions). </li>
    </ul>

    <hr>
    <h3>Step 6) Create an icon set </h3>
    Reference: <a href="https://www.electron.build/icons">electron.build/icons</a> | <a href="https://developer.apple.com/design/human-interface-guidelines/app-icons">developer.apple.com/design/human-interface-guidelines/app-icons</a>
    <li>You need to create your icon in at least two different sizes: 512x512 px and 1024x1024 px saved as png files. But ideally use all the Apple recommended sizes which additionally include 16x16, 32x32, 64x64, 128x128 and 256x256.</li>
    <li>This is a useful guide: <a href="https://elliotekj.com/posts/2014/05/27/how-to-create-high-resolution-icns-files/">How to create high resolution icns files</a>. A few things to highlight:</li>
    <ul>
    <li>Make a folder called icon.iconset (or any name that has .iconset as the extension) to hold the images.</li>
    <li>Use Apple's naming convention for the image files (e.g., icon_512x512.png, [email protected], etc.).</li>
    <li>The @2x files are double the size stated in terms of pixels. However in terms of display, Apple just doubles the density of the pixels instead of doubling the width and height. As such, some of the files will be the same image dimensions but two different files (e.g., [email protected] and icon_512x512.png are two separate files but are the same image size). If you are simplifying the images at smaller sizes, make sure the @2x image is the same as the 1x, just at double the size.</li>
    <li>When you get down to the small sizes such as icon_16x16.png you'll likely need to simplify the image, otherwise it will just look blurry.</li>
    <li>Convert the iconset into an icns file in the Terminal from the directory holding the icon.iconset folder with the png images. Enter the iconutil command:</li>
    <li class="dlr"><code>iconutil -c icns icon.iconset</code></li>
    <li>Put the resulting icon.icns file into the build folder of your electron project.</li>
    </ul>

    <hr>
    <h3>Step 7) package.json file </h3>
    <h4>7a) Local version</h4>
    <p>You can build a local version of your app not for distribution, by excluding the "mac" key from the package.json file. This will build a packaged version of your app, a zipped version, and a dmg installer. All are unsigned so they are cannot be distributed to other users that way.</p>
    <p>The values in italics need to be changed to your info.</p>
    <pre>
    {
    "name": "<i>AppName</i>",
    "version": "<i>1.0.0</i>",
    "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
    },
    ...
    "author": "<i>AuthorName</i>",
    "build": {
    "appId": "<i>com.companyname.appname</i>",
    "productName": "<i>App Name (can include spaces & special characters)</i>",
    "buildVersion": "<i>1.0.0</i>",
    "copyright": "Copyright © 2023 <i>Developer or Company Name</i>",
    "files": [
    "!<i>file-or-directory-name-to-exclude"</i>
    ]
    }
    ...
    }
    </pre>

    <h4>7b) MAS Development version (for testing)</h4>
    <p>This is a test version of the MAS build, which you can run on your development computer.</p>
    <p>The values in italics need to be changed to your info.</p>
    <pre>
    {
    "name": "<i>AppName</i>",
    "version": "<i>1.0.0</i>",
    "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
    },
    ...
    "author": "<i>AuthorName</i>",
    "build": {
    "appId": "<i>com.companyname.appname</i>",
    "productName": "<i>App Name (can include spaces & special characters)</i>",
    "buildVersion": "<i>1.0.0</i>",
    "copyright": "Copyright © 2023 <i>Developer or Company Name</i>",
    "files": [
    "!<i>file-or-directory-name-to-exclude"</i>
    ],
    "mac": {
    "category": "public.app-category.<i>categoryName</i>",
    "icon": "build/icon.icns",
    "target": "mas-dev",
    "type": "development",
    "hardenedRuntime": false,
    "provisioningProfile": "build/AppleDevelopment.provisionprofile",
    "entitlements": "build/entitlements.mas.plist",
    "entitlementsInherit": "build/entitlements.mas.inherit.plist"
    }
    }
    ...
    }
    </pre>

    <h4>7c) MAS Distribution version (for submission to the Mac App Store)</h4>
    <p>This builds a pkg installer for submission to the MAS. It changes the target, type, and provisioningProfile from 7b above.
    <p>The values in italics need to be changed to your info.</p>
    <pre>
    {
    "name": "<i>AppName</i>",
    "version": "<i>1.0.0</i>",
    "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
    },
    ...
    "author": "<i>AuthorName</i>",
    "build": {
    "appId": "<i>com.companyname.appname</i>",
    "productName": "<i>App Name (can include spaces & special characters)</i>",
    "buildVersion": "<i>1.0.0</i>",
    "copyright": "Copyright © 2023 <i>Developer or Company Name</i>",
    "files": [
    "!<i>file-or-directory-name-to-exclude"</i>
    ],
    "mac": {
    "category": "public.app-category.<i>categoryName</i>",
    "icon": "build/icon.icns",
    "target": "mas",
    "type": "distribution",
    "hardenedRuntime": false,
    "provisioningProfile": "build/MacAppStore.provisionprofile",
    "entitlements": "build/entitlements.mas.plist",
    "entitlementsInherit": "build/entitlements.mas.inherit.plist"
    }
    }
    ...
    }
    </pre>
    <p>Only include the postinstall script above if you have native dependencies that need to be recompiled by Electron (see Native Node NPM packages at the bottom).</p>
    <b>Reference:</b>
    <li>General configuration including metadata: <a href="https://www.electron.build/configuration/configuration">electron.build/configuration/configuration</a></li>
    <li>Mac-general configuration: <a href="https://www.electron.build/configuration/mac">electron.build/configuration/mac</a></li>
    <li>MAS-specific configuration: <a href="https://www.electron.build/configuration/mas">electron.build/configuration/mas</a></li>

    <br>
    <b>package.json keys:</b>
    <li>Name and productName: The name key will be used as the display name for your app on the user's computer. It cannot contain spaces or special characters. If you want to use spaces or special characters in the name then add a productName key within the build key. You set the name of your app as it appears in the Mac App Store at appstoreconnect.apple.com. </li>
    <li>Version number and build number: The version number in package.json should correspond with the version number of your app at appstoreconnect.apple.com. If you upload your app to appstoreconnect but decide to make changes before submitting it for review, you can't delete what you uploaded. Rather you submit a revised app with a different build number. The build number defaults to the version number. To set a different build number, use the buildVersion property.</li>
    <li>Use the same appId as you created for your app at developer.apple.com.</li>
    <li>files: You can add an array of file and directory names to exclude from the build. Preface each name with a "!" to indicate that the file/directory should be excluded. Ref: <a href="https://www.electron.build/file-patterns.html">electron.build/file-patterns</a></li>
    <li>The category key should align with the category you set for your app in appstoreconnect.apple.com. Mac uses this key in the Finder via View > Arrange by Application Category when viewing the Applications directory. <a href="https://developer.apple.com/documentation/bundleresources/information_property_list/lsapplicationcategorytype">List of possible categories</a>.</li>
    <li>Set your target to "mas-dev" if building the development version (for testing) and "mas" if building the distribution version (to submit to the MAS).</li>
    <li>Set Hardened Runtime to false. You would set it to true if you want to distribute the app outside the MAS. For more on hardened runtime see <a href="https://developer.apple.com/documentation/security/hardened_runtime">developer.apple.com/documentation/security/hardened_runtime</a></li>
    <li>Set type to "development" for the development version, "distribution" for the MAS version.</li>

    <br>
    <b>Keys you don't need to set because the default is already correct:</b>
    <li>The icon key points to where your icon.icns file is. The default folder and filename is build/icon.icns so you can leave it out if it is located there.</li>
    <li>The type key can be distribution or development. Distribution is the default so you can leave this key out. </li>
    <li>The identity key sets the name of the certificate to use when signing. However, for the MAS build, the signing certificate will be taken from the provisioning profile (covered below). And Electron-builder will automatically use the 3rd Party Mac Developer Installer certificate in your Keychain to sign the pkg file.</li>
    <li>GatekeeperAssess key is set to false by default. Mac's Gatekeeper ensures that apps distributed outside the app store are signed and notarized. Since this build is for the MAS you can leave this at false.</li>

    <hr>
    <h3>Step 8) Entitlements</h3>
    Reference: <a href="https://electronjs.org/docs/tutorial/mac-app-store-submission-guide">electronjs.org/docs/tutorial/mac-app-store-submission-guide</a>
    <li>Make parent and child entitlement property list files using XML. Put them in the build folder. </li>
    <li>These files correspond to the entitlements and entitlementsInherit keys in the package.json file. </li>
    <h4>The parent entitlement file: </h4>
    <b>/build/entitlements.mas.plist </b>
    <pre>
    &lt;?xml version="1.0" encoding="UTF-8"?>
    &lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    &lt;plist version="1.0">
    &lt;dict>
    &lt;key>com.apple.security.app-sandbox&lt;/key>&lt;true/>
    &lt;key>com.apple.security.application-groups&lt;/key>
    &lt;array>
    &lt;string><i>TEAM_ID.com.companyname.appname</i>&lt;/string>
    &lt;/array>
    &lt;!-- Put any entitlements your app requires here. Below is an example -->
    &lt;key>com.apple.security.files.user-selected.read-write&lt;/key>&lt;true/>
    &lt;/dict>
    &lt;/plist>
    </pre>

    <h4>Child entitlement file (inherits from the parent): </h4>
    <b>/build/entitlements.mas.inherit.plist </b>
    <pre>
    &lt;?xml version="1.0" encoding="UTF-8"?>
    &lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    &lt;plist version="1.0">
    &lt;dict>
    &lt;key>com.apple.security.app-sandbox&lt;/key>&lt;true/>
    &lt;key>com.apple.security.inherit&lt;/key>&lt;true/>
    &lt;/dict>
    &lt;/plist>
    </pre>

    <li>First thing to notice is app-sandbox is set to true. All apps in the MAS must be sandboxed. That means they don't have access to resources outside the app, unless you specifically request an exception (an entitlement) and it is approved. For example to be able to read and write to files in the user's computer (outside the app) you need to request user-selected files read-write access. If approved your app can read/write files that users have specifically opened or saved using the mac Open or Save dialog box. </li>
    <li>These entitlements must correspond to the entitlements you request for your app in Appstoreconnect.apple.com </li>
    <li>Read about entitlements <a href="https://developer.apple.com/documentation/bundleresources/entitlements">here</a>.</li>
    <li>The list of available app sandbox entitlement keys are <a href="https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html">here</a>.</li>
    <li>The application-groups key is an array containing your app identifier (TeamID and appId). </li>


    <hr>
    <h3>Step 9) Generate two Provisioning Profiles (AppleDevelopment and MacAppStore)</h3>
    <li>Go to your apple developer account profiles page <a href="https://developer.apple.com/account/resources/profiles/list">developer.apple.com/account/resources/profiles/list</a></li>
    <li>These expire after one year, so if you are updating your app, run the command at the bottom of 9a and 9b to see the expiration date. If they are expired you need to recreate them.</li>

    <h4>9a) Generate the AppleDevelopment Provisioning Profile</h4>
    <li>Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.</li>
    <li>Select "macOS App Development". Then click Continue.</li>
    <li>Select your appID, then click continue.</li>
    <li>Give it a recognizable name like "AppleDevelopment", then download it to your computer.</li>
    <li>Double click the file to install it, then place it in the project's build directory. The file name would be AppleDevelopment.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.</li>
    <li>This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command: </li>
    <li class="dlr"><code>security cms -D -i build/AppleDevelopment.provisionprofile</code></li>

    <h4>9b) Generate the MacAppStore Provisioning Profile</h4>
    <li>Click the + sign to add a new profile which will take you to the "Register a New Provisioning Profile" page.</li>
    <li>Select Mac App Store. Then click Continue.</li>
    <li>Select your appID, then click continue.</li>
    <li>Select your Mac App Distribution certificate, then click continue.</li>
    <li>Give it a recognizable name like "MacAppStore", then download it to your computer.</li>
    <li>Double click the file to install it, then place it in the project's build directory. The file name would be MacAppStore.provisionprofile. This corresponds to the provisioningProfile key in the package.json file. Whatever you name it, during the build process it gets renamed to embedded.provisionprofile.</li>
    <li>This is a binary file. If you want to read it's contents in XML format and you have X-Code's Command Line utilities installed, from the Terminal in the project folder run the below command: </li>
    <li class="dlr"><code>security cms -D -i build/MacAppStore.provisionprofile</code></li>

    <hr>
    <h3>Step 10) Build a development and distribution versions of the App with electron-builder</h3>
    <li>Install electron-builder as a development dependency: </li>
    <span class="dlr"><code>npm install -D electron-builder</code></span>
    <li>Optionally, you can build an unsigned local version of your app that is not packaged for the Mac App Store. Use the 7a version of the package.json file.</li>
    <li>Build the MAS-development version of the app using the 7b version of package.json above, which uses the AppleDevelopment.provisionprofile, and the Development signing certificate. Use this to test the MAS version on your computer.</li>
    <span class="dlr"><code>npm run dist</code></span>
    <li>After testing the Development version of the app, build the MAS distribution version and .pkg installer. Use the 7c version of package.json, the MacAppStore.provisionprofile, and the Distribution and Mac Installer Distribution signing certificates.</li>
    <span class="dlr"><code>npm run dist</code></span>

    <p>If you get a "command not found" error, then include the relative path. Here are the direct commands with the path:<br>
    Mac: <code>./node_modules/.bin/electron-builder</code><br>
    Windows: <code>.\node_modules\.bin\electron-builder.cmd</code>
    </p>

    <hr>
    <h3>Step 11) Test the app</h3>
    <p>Test the Development version of the app before building the distribution version. Make sure it works as expected.</p>
    <p>Then build the distribution version. This version will crash and give you a signing error if you try to open it on your computer. It must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store. However, there are some checks you can make before submitting it to Apple.</p>

    <li>You can test the signature if you have X-Code's CLI utilities installed. To check that your app is signed, go to the directory holding your app (e.g., MyApp/dist/mas) and enter the below command. If the app is signed it will display the details in the Terminal.</li>
    <li class="dlr"><code>codesign --display --verbose=2 <i>MyApp</i>.app</code></li>
    <li>To check that the .pkg file is signed, enter the below command from the .pkg file's directory. If it is signed it will display the details in the Terminal.</li>
    <li class="dlr"><code>pkgutil --check-signature <i>MyApp</i>-1.0.0.pkg</code></li>
    <li>The Transporter app (see next section) has built-in checks on your app that will let you know about some (but not all) problems with your app. Simply load the app in the Transporter and it will do several checks. If everything is okay, you can click the deliver button to send it to appstore connect. Then you can submit it for review.</li>
    <li>If you are getting errors you could start by making sure all the basics are working by using this process on a simple Electron app like the <a href="https://github.com/steve981cr/electron-app-store-example">Electron App Store Example</a> app on Github. Just add in your developer and app datails and provisioning profile.</li>


    <hr>
    <h3>Step 12) Upload the pkg file</h3>
    <li>There are three different tools you can use to upload the pkg file: <a href="https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds">developer.apple.com/help/app-store-connect/manage-builds/upload-builds</a>.</li>
    <li>The preferred tool is the <a href="https://apps.apple.com/us/app/transporter/id1450874784">Transporter app</a> which can be downloaded free from the Mac App Store.</li>
    <li>Open the Transporter app > Drag and drop your Electron app's pkg file into the Transporter app.</li>
    <li>It will check for errors. If no errors found click the Deliver button to send the app to your developer account.</li>
    <li>Go to <a href="https://appstoreconnect.apple.com">appstoreconnect.apple.com</a> and click MyApps > Prepare for Submission > Build + icon > Select the uploaded file - Done</li>
    <li>Note: the build may have a "Missing Compliance" warning next to it. If so, when you submit the app you will be asked about any encryption in your app, so just answer the questions given. See <a href="https://www.electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#cryptographic-algorithms-used-by-electron">electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#cryptographic-algorithms-used-by-electron</a>
    <li>If you are ready to submit the app for review then click "Submit for review".</li>
    <li>If you decide to make additional changes before submitting for review, you have to load another .pkg file through the Transporter app with a higher build number (e.g., 1.0.1).</li>

    <hr>
    <h3>Native Node NPM packages</h3>
    <p>Reference: <a href="https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules">electronjs.org/docs/latest/tutorial/using-native-node-modules</a></p>

    <p>
    Native node modules are npm packages that include C or C++ code.<br>
    C/C++ code must be compiled into executable binaries. Even if the modules are precompiled when installed, they must be recompiled for Electron. Electron-builder will do that automatically when you run the electron-builder script <code>npm run dist</code>.<br>
    To recompile native modules in development, you can add the below script to your package.json file:
    <pre>
    "postinstall": "electron-builder install-app-deps"
    </pre>

    Then after installing native modules, run the script: <code>npm run postinstall</code>
    </p>
    <p>If you don't recompile native modules, and try to run the app, you will get an error that says something like:
    <pre>
    Error: The module '/path/to/native/module.node'
    was compiled against a different Node.js version using
    NODE_MODULE_VERSION $XYZ. This version of Node.js requires
    NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
    the module (for instance, using `npm rebuild` or `npm install`).
    </pre>

    <p>Native modules must be pulled out of your built binary app and code signed separately. This is done automatically by electron-builder.</p>