diff --git a/docs/how-to/PyStackTraceOnXcode.png b/docs/how-to/PyStackTraceOnXcode.png deleted file mode 100644 index 69cf31890..000000000 Binary files a/docs/how-to/PyStackTraceOnXcode.png and /dev/null differ diff --git a/docs/how-to/code-signing/macOS.rst b/docs/how-to/code-signing/macOS.rst index d98ea62fb..e7c4ad525 100644 --- a/docs/how-to/code-signing/macOS.rst +++ b/docs/how-to/code-signing/macOS.rst @@ -28,30 +28,35 @@ be guided through in this tutorial: 5. Anticipating potential issues with the identity in the future +.. _apple-dev-enroll: Enrolling in the Apple Developer program ---------------------------------------- You can enroll in the Apple Developer program either as an individual, or as an -organization. In both cases, you'll have to follow the instructions on the -`Apple Developer website `__. +organization. In both cases, you'll have to follow the instructions on the `Apple +Developer website `__. -Once you click "Start Enrollment Now" at the bottom of the page, you can either -sign in with your existing Apple ID or alternatively, create a new one: +Once you click "Start Enrollment Now" at the bottom of the page, you can either sign in +with your existing Apple ID or alternatively, create a new one: .. image:: images/AppleID.png :width: 300 -As part of the registration procedure, you'll have to pay a **$99 fee**, which -will be charged on an annual basis. +There are two types of Apple Developer account - a *personal* account, and a *business* +account. If you use your personal Apple ID to create an Apple Developer account, +converting it to a business account later can be painful. If you use your personal Apple +ID to create a business account, extracting your personal credentials later can also be +painful. -.. admonition:: Fee waivers +As part of the registration procedure, you'll have to pay a **$99 fee**, which will be +charged on an annual basis. - If you're registering as a non-profit organization, an educational institution - or a government entity, you may be eligible for a fee waiver, which you can - read more about `here - `__. +.. admonition:: Fee waivers + If you're registering as a non-profit organization, an educational institution or a + government entity, you may be eligible for a fee waiver, which you can read more about + `here `__. Generating a certificate request on Keychain Access --------------------------------------------------- diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 77d0723bb..a59af3298 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -18,6 +18,5 @@ stand alone. access-packaging-metadata contribute-code contribute-docs - See errors on iOS internal/index publishing/index diff --git a/docs/how-to/publishing/android.rst b/docs/how-to/publishing/android.rst index f88d57013..6f861d4c5 100644 --- a/docs/how-to/publishing/android.rst +++ b/docs/how-to/publishing/android.rst @@ -2,12 +2,16 @@ Android ======= -Overview --------- - The Google Play Store is the most widely-used Android app store. This guide focuses on how to distribute a BeeWare app on the Google Play Store. +.. admonition: App Stores are a moving target + + The Google Play Store makes frequent changes to the workflows and nomenclature + associated with publishing apps. As a result, it's very difficult to keep a guide + like this one up to date. If you spot any problems, `let us know + `__. + Build the app in release mode ----------------------------- @@ -22,7 +26,7 @@ Use Briefcase to build a release bundle for your application: (venv) $ briefcase package android [hello-world] Building Android App Bundle and APK in release mode... ... - [hello-world] Packaged android/Hello World/app/build/outputs/bundle/release/app-release.aab + [hello-world] Packaged dist/Hello World-1.0.0.aab .. group-tab:: Linux @@ -31,7 +35,7 @@ Use Briefcase to build a release bundle for your application: (venv) $ briefcase package android [hello-world] Building Android App Bundle and APK in release mode... ... - [hello-world] Packaged android/Hello World/app/build/outputs/bundle/release/app-release.aab + [hello-world] Packaged dist/Hello World-1.0.0.aab .. group-tab:: Windows @@ -40,7 +44,7 @@ Use Briefcase to build a release bundle for your application: (venv) C:\...>briefcase package android [hello-world] Building Android App Bundle and APK in release mode... ... - [hello-world] Packaged android\Hello World\app\build\outputs\bundle\release\app-release.aab + [hello-world] Packaged dist\Hello World-1.0.0.aab This will result in an Android App Bundle file being generated. An `Android App Bundle `__ is a publishing @@ -76,7 +80,7 @@ name. .. code-block:: console - $ ~/Library/Caches/org.beeware.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "android/gradle/Hello World/app/build/outputs/bundle/release/app-release.aab" upload-key -storepass android + $ ~/Library/Caches/org.beeware.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "dist/Hello World-1.0.0.aab" upload-key -storepass android adding: META-INF/MANIFEST.MF adding: META-INF/UPLOAD-K.SF adding: META-INF/UPLOAD-K.RSA @@ -101,7 +105,7 @@ name. .. code-block:: console - $ ~/.cache/briefcase/tools/java/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "android/gradle/Hello World/app/build/outputs/bundle/release/app-release.aab" upload-key -storepass android + $ ~/.cache/briefcase/tools/java/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "dist/Hello World-1.0.0.aab" upload-key -storepass android adding: META-INF/MANIFEST.MF adding: META-INF/UPLOAD-K.SF adding: META-INF/UPLOAD-K.RSA @@ -126,7 +130,7 @@ name. .. code-block:: doscon - C:\...>%LOCALAPPDATA%\BeeWare\briefcase\Cache\tools\java\bin\jarsigner.exe -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore %HOMEPATH%\.android\upload-key-helloworld.jks "android\gradle\Hello World\app\build\outputs\bundle\release\app-release.aab" upload-key -storepass android + C:\...>%LOCALAPPDATA%\BeeWare\briefcase\Cache\tools\java\bin\jarsigner.exe -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore %HOMEPATH%\.android\upload-key-helloworld.jks "dist\Hello World-1.0.0.aab" upload-key -storepass android adding: META-INF/MANIFEST.MF adding: META-INF/UPLOAD-K.SF adding: META-INF/UPLOAD-K.RSA @@ -179,10 +183,10 @@ certificate when you upload your app for distribution. Add the app to the Google Play store ------------------------------------ -To publish to the Google Play store, you will need a Google Play Developer -account, which costs 25 USD. You will then need to provide -information for your app's store listing including an icon and screenshots, -upload the app to Google, and finally roll the app out to production. +To publish to the Google Play store, you will need a Google Play Developer account, +which costs 25 USD. You will then need to provide information for your app's store +listing including an icon and screenshots, upload the app to Google, and finally roll +the app out to production. Register for a Google Play Developer account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -204,12 +208,11 @@ Create a listing ~~~~~~~~~~~~~~~~ Visit the `Google Play console. `__ and -log in. You will see a button labeled **Publish an Android App on Google Play** -or a button to **Create Application**. Click it. +log in. You will see a button labeled **Create App**; click this button. -Once you've done that, click **Create Application**. Choose a language and -write a brief app title, up to 50 characters. We suggest making this the -same as your app's Formal Name in its ``pyproject.toml``. +Fill out the details for your app. We suggest using your app's formal name (as defined +in ``pyproject.toml`` as the App name; the other details relate to the listing and legal +compliance. At the bottom of of the page, press **Create App**. This will take you to **Store Listing** section of your app. You will need to provide a short app description (up to 80 characters) and a full @@ -243,23 +246,21 @@ Google Play supports optional graphic assets including promo videos, TV banners, and 360 degree stereoscopic images. See also `Google's advice on graphic assets. `__ -Once you've completed the store listing, you'll need to fill out a range of -other details about your app, including the category where it should appear in -the Play Store, pricing details, details about the app's content and its -suitability for children, and contact details for you as a developer. The -navigation pane (typically on the left side of the screen) contains grayed out -check marks covering all the sections with required details. Visit each of -these sections in turn; when you have met the requirements of each section, the -check mark will turn green. Once all the checkmarks are green, you're ready to -release your app. +Once you've completed the store listing, you'll need to fill out a range of other +details about your app, including the category where it should appear in the Play Store, +pricing details, details about the app's content and its suitability for children, and +contact details for you as a developer. The navigation pane (typically on the left side +of the screen) contains grayed out check marks covering all the sections with required +details. Visit each of these sections in turn; when you have met the requirements of +each section, the check mark will turn green. Once all the checkmarks are green, you're +ready to release your app. Create a release ~~~~~~~~~~~~~~~~ -Click **App releases** in the navigation pane. To produce a production app -(i.e., an app in the public Play Store that anyone can download) click -**Manage** within the **Production track**, then select **Create Release.** -If prompted to enable App Signing by Google Play, click **Continue**. +In the left navigation bar, select **Production** (in the "Release" grouping), Then +select **Create Release.** If prompted to enable App Signing by Google Play, click +**Continue**. .. admonition:: Non-production releases @@ -268,33 +269,28 @@ If prompted to enable App Signing by Google Play, click **Continue**. test releases `__. -In an earlier section of this tutorial, we used ``briefcase publish`` and -``jarsigner`` to create a signed Android App Bundle file. It is stored at -``android/Hello World/app/build/outputs/bundle/release/app-release.aab`` -(substituting the name of your own app as necessary). Upload this file to the -Google Play console within **Browse Files** under **Android App Bundles and -APKs to add.** +In an earlier section of this tutorial, we used ``briefcase publish`` and ``jarsigner`` +to create a signed Android App Bundle file. It is stored in the ``dist`` folder of your +project. Upload this file to the Google Play console in the **App Bundles** section, +fill out the **Release notes** section of the app, and click **Next**. -You will need to write release notes for the app in the **What's new in this -release?** section. If this is your first upload of the app, you can use -something like "Initial application release." Review your application details, +Google will then check that you've filled out all the necessary compliance details for +your app; if there are any missing, you'll be prompted to complete those details. -Once you have answered those questions, you can switch back to the -**App releases** tab. Click **Edit release**, save your changes, and -click **Start Rollout To Production.** +Once you've completed those details, select **Publishing Overvie** from the navigation +sidebar. You should see "Changes ready to send for review", and a button marked **Send +for review**. Click this button. -The Google Play Store will now review your app. You will be emailed if any -updates are required; otherwise, after a day or two, your app will be rolled -out to the Play Store. +The Google Play Store will now review your app. You will be emailed if any updates are +required; otherwise, after a day or two, your app will be rolled out to the Play Store. Publish an update ----------------- -At some point, you'll want to publish an updated version of your application. -Generate a fresh AAB file, signed with the *same* certificate as your original -release. Then log into the Play Store console, and select your application. -Select **Release Management** in the navigation bar, then **App Releases**. +At some point, you'll want to publish an updated version of your application. Generate a +fresh AAB file, signed with the *same* certificate as your original release. Then log +into the Play Store console, and select your application. Select **Release Management** +in the navigation bar, then **App Releases**. -At this point, the release process is the same as it was for your initial -release; create a release, upload your AAB file, and submit the application -for roll out. +At this point, the release process is the same as it was for your initial release; +create a release, upload your AAB file, and submit the application for roll out. diff --git a/docs/how-to/publishing/iOS.rst b/docs/how-to/publishing/iOS.rst new file mode 100644 index 000000000..00139c304 --- /dev/null +++ b/docs/how-to/publishing/iOS.rst @@ -0,0 +1,120 @@ +=== +iOS +=== + +This guide will walk you through the process of publishing an app to the Apple App +Store. + +.. admonition: App Stores are a moving target + + The Apple App Store makes frequent changes to the workflows and nomenclature + associated with publishing apps. As a result, it's very difficult to keep a like + this one up to date. If you spot any problems, `let us know + `__. + +To distribute an app on the iOS App Store, you'll need to :ref:`enroll in the Apple +Developer Program `. You don't need to generate any of the +certificates described on that page - you just need an Apple ID registered in the +developer program. + +Once you've signed up for an Apple ID account, open the Xcode Settings dialog, and +add your account under the "Accounts" tab. + +Open the app in Xcode +===================== + +Use Briefcase to open the Xcode project associated with your project. + +.. code-block:: console + + (venv) $ briefcase open iOS + +Run the app in the simulator +============================ + +In order to submit your app to the App Store, you will need to provide a range of +screenshots: + +* 3-5 screenshots running on a 6.5" iPhone (e.g., iPhone 14 Plus) +* 3-5 screenshots running on a 5.5" iPhone (e.g., iPhone 8 Plus) +* 3-5 screenshots running on an 12.9" iPad Pro (Gen 6; without a physical home button) +* 3-5 screenshots running on an 12.9" iPad Pro (Gen 2; with a physical home button) +* (optionally) 3-5 screenshots running on a 6.7" iPhone (e.g., iPhone 14 Pro Max) + +The iOS and iPad simulators have a "Save Screen" button in their title bar; this will +capture screenshots of the necessary size. + +You can change simulator device by clicking on the device target int the top bar of the +Xcode window. Click on the device name, and select the device from the list. If the device +you need doesn't exist on this list, click on "Manage Run Destinations" to add a simulator +for that device type. + +Produce an App archive +====================== + +Select the root node of the Xcode project browser (it should be the formal name of your +app), then select the **Signing & Capabilities** tab from configuration options that are +displayed. The "Team" option under "Signing" will be listed as "None"; select the name +of the development team that will sign the app. If there's no team listed, select "Add +an Account", and choose one of the teams that is associated with your Apple ID. + +In the top bar of the Xcode window, change the target device from a simulator to "Any +iOS device". Clean the build products folder (select "Clean Build Folder..." from the +Product menu), then build an archive by selecting "Archive" from the Product menu. This +will perform a clean build of your application, build an archive, and open a new window, +called the Organizer. It should list a freshly created archive of your app, with the +current version number. + +Select the archive, and click the "Distribute App" on the right side of the Organizer +window. This will display a wizard that will ask details about your app; accept the +default values; once the wizard completes, your app binary has been sent to the App +Store for inclusion in a release. + +After a few minutes, you should receive an email notifying you that the binary has been +processed. + +Create an App Store entry +========================= + +Log into `App Store Connect `__, click on "My Apps", +then on + to add an app. + +Fill out the form for a new app. If you've run the app in Xcode, the Bundle ID for your +app should be listed; select it from the list. You must also create an SKU for your app +- we suggest ``ios-``, substituting the short app name that you selected when +you initially created your app. So, if you've created an app with a formal name of +"Hello World", with an app name of ``helloworld``, and a bundle of ``org.beeware``, you +should have a Bundle ID of ``org.beeware.helloworld``; we'd suggest an SKU of +``ios-helloworld``. + +You'll then be shown another page for app details, including: + +* Primary and Secondary Category. +* Screenshots +* Promotional Text +* Description +* Keywords +* Support URL +* Marketing URL +* A URL for your app's privacy policy +* Version number +* The name of the copyright holder + +Under the "Build" section, you'll be able to select the archive that you uploaded +through Xcode. + +The "App Review Information" section allows you to provide contact details in case Apple +has questions during the review process. If your app requires a login, you *must* +provide a set of credentials so that Apple can log in. You can also provide any +additional notes to assist the reviewer. + +Click on "Pricing and Availability" tab on the sidebar, and set up the pricing schedule +and availability for your app. + +Then, click on "App Privacy", and click on "Get Started"; this will ask you a series of +questions about the information about users that your app collects. + +Once these details have all been provided, click on the "1.0 Prepare for Submission" link +in the sidebar. On the right of the screen, click on "Add for Review"; this will ask some +final questions, and provide one more button "Submit for Review". Click that button, and +you're done! diff --git a/docs/how-to/publishing/index.rst b/docs/how-to/publishing/index.rst index 25fdd00cc..39a05857c 100644 --- a/docs/how-to/publishing/index.rst +++ b/docs/how-to/publishing/index.rst @@ -9,3 +9,4 @@ covers how to publish your app to the appropriate distribution system. :maxdepth: 1 android + iOS diff --git a/docs/how-to/see_errors_on_ios.rst b/docs/how-to/see_errors_on_ios.rst deleted file mode 100644 index 78f0e6b1c..000000000 --- a/docs/how-to/see_errors_on_ios.rst +++ /dev/null @@ -1,16 +0,0 @@ -See Errors on iOS -========================= - -If you have a BeeWare iOS project that has a crash, it can be difficult to see -the stack trace. Here's how to do it - - -1. Build your iOS project. You don't have to start it. - -2. Open that iOS project in Xcode. Click the Run button (looks like an arrow) - and wait for the simulator to open. Cause the app to crash. - -3. Your stack trace ought to appear in the 'debugger area' at the bottom of the - screen. If you can't see that area, you may have to activate it with - ``View`` > ``Debug Area`` > ``Show Debug Area`` - - .. image:: PyStackTraceOnXcode.png