diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md index f3136d539cb..42270fcc7a2 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md @@ -88,14 +88,14 @@ If you use the installation step in the builder, keep the following in mind: For iOS packaging, install or prepare the following: -* Xcode or Xcode Command Line Tools to bundle and sign the iOS app on macOS +* Xcode or Xcode Command Line Tools to bundle and sign the iOS app on macOS, unless you use the experimental **Build without a Mac** option * Apple signing assets, including a `.p12` certificate and a `.mobileprovision` profile, if you want to build for a physical device or distribute the app * A bundle identifier that matches the Apple signing configuration, if you want to build for a physical device or distribute the app Install full Xcode if you want to use the iOS simulator for testing. {{% alert color="warning" %}} -iOS packaging for a final signed device build requires macOS. On Windows, you can prepare the portable signing package, but you still need a Mac to generate the final signed IPA. +To generate a signed IPA on Windows, use the experimental **Build without a Mac** option. Without this option, PWA Wrapper on Windows prepares a portable signing package, and you need a Mac to generate the final signed IPA. {{% /alert %}} ### Steps for iOS on macOS{#steps-on-mac} @@ -131,9 +131,19 @@ To generate a signed iOS package on macOS, do the following: ### Steps for iOS on Windows -On Windows, PWA Wrapper can prepare the iOS bundle but not complete the final signing step. The builder produces a portable signing package that can be moved to a Mac. +On Windows, you can sign the iOS app directly with the experimental **Build without a Mac** option. Without this option, the builder produces a portable signing package that you must move to a Mac for the final signing step. -On Windows, use the same steps 1 through 7 as in [Steps for iOS on macOS](#steps-on-mac), then continue as follows: +To generate a signed IPA on Windows without a Mac, use the same steps 1 through 4 as in [Steps for iOS on macOS](#steps-on-mac), then continue as follows: + +1. Go to the signing step and create or select an iOS signing configuration. +1. Select **Build without a Mac (experimental)**, then click **OK** in the **Experimental Feature** dialog. +1. Click **Build**. +1. Wait for the build to complete. +1. Open the output directory and retrieve the signed `.ipa`. + +For more information, see [Build a Signed IPA Without a Mac](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#build-without-a-mac) in *Sign PWA Wrapper Apps*. + +To use the portable signing package instead, use the same steps 1 through 7 as in [Steps for iOS on macOS](#steps-on-mac), then continue as follows: 1. Open the output folder and locate the portable signing ZIP. 1. Copy the portable signing ZIP to a Mac. @@ -147,7 +157,7 @@ Keep the following limitations in mind: * The builder installation step for iOS is available only on macOS hosts * Copying packaged web resources is currently not supported on iOS, so the wrapped app must load its frontend resources from the deployed Mendix runtime -For platform-specific details about the signing step inside this build flow, see [Sign iOS Apps on macOS](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos) in *Sign PWA Wrapper Apps* for macOS builds and [Prepare iOS Apps on Windows](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows) in *Sign PWA Wrapper Apps* for Windows builds. +For platform-specific details about the signing step inside this build flow, see [Sign iOS Apps on macOS](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos) in *Sign PWA Wrapper Apps* for macOS builds and [Sign iOS Apps on Windows](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows) in *Sign PWA Wrapper Apps* for Windows builds. ## Choosing Permissions and Packaging Options @@ -201,6 +211,6 @@ If your app depends on device hardware, validate the final packaged app on repre After building the wrapper app, continue with the appropriate distribution process for your target platform. -If you still need platform-specific details for the signing step in the build flow, see [Sign Android Apps on Windows and macOS](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-android-apps-on-windows-and-macos), [Sign iOS Apps on macOS](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos), or [Prepare iOS Apps on Windows](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows). +If you still need platform-specific details for the signing step in the build flow, see [Sign Android Apps on Windows and macOS](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-android-apps-on-windows-and-macos), [Sign iOS Apps on macOS](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos), or [Sign iOS Apps on Windows](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows). To understand which capabilities you can use from your Mendix app, see [PWA Wrapper Capabilities](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-capabilities/). diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md index adc5cb6e7b9..78e36e36aaa 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md @@ -25,7 +25,7 @@ For an overview of the supported capabilities, see [PWA Wrapper Capabilities](/r Keep the following build and installation constraints in mind: -* Final iOS signing requires macOS +* Final iOS signing requires macOS, unless you use the experimental **Build without a Mac** option on Windows * Copying packaged web resources is currently not supported on iOS, so the wrapped iOS app must load frontend resources from the deployed Mendix runtime * Real-device installation requires signed packages * If an incompatible or newer build of the app is already installed on a device, it may need to be uninstalled before your current build can be installed diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md index 98f96a9820b..90a52d5f817 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md @@ -35,7 +35,7 @@ To avoid this download in air-gapped environments, pre-populate the Gradle wrapp ## Bundled Binaries Executed Locally -In addition to the runtime downloads above, PWA Wrapper ships the following binaries inside its own extension package. These are not downloaded at build time—they are included in the extension at install time and are invoked as local subprocesses during Android and HarmonyOS build, signing, and packaging steps. They run with the same operating-system privileges as the Studio Pro process. +In addition to the runtime downloads above, PWA Wrapper ships the following binaries inside its own extension package. These are not downloaded at build time—they are included in the extension at install time and are invoked as local subprocesses during Android, HarmonyOS, and iOS build, signing, and packaging steps. They run with the same operating-system privileges as the Studio Pro process. | Binary | Purpose | Platform | | --- | --- | --- | @@ -44,6 +44,9 @@ In addition to the runtime downloads above, PWA Wrapper ships the following bina | `aapt2` / `aapt2.exe` | Android Asset Packaging Tool | Android | | `apksigner.jar` | APK signing | Android | | `android.jar` | Android SDK stub library used during compilation | Android | +| `adb.exe`, `AdbWinApi.dll`, `AdbWinUsbApi.dll` | Android Debug Bridge, used to install the app on connected devices and emulators | Android (Windows hosts) | +| `zsign.exe` | iOS code signing when **Build without a Mac** is selected | iOS (Windows hosts) | +| `zsign` | iOS code signing when **Build without a Mac** is selected | iOS (macOS hosts) | These binaries are third-party open-source tools redistributed with the extension. They are not fetched from the network at runtime. @@ -53,7 +56,7 @@ When the builder opens, PWA Wrapper inspects the local machine to auto-detect ex ### JDK Discovery -PWA Wrapper needs a Java runtime to execute the build tools listed above. It searches for an installed JDK in the following order and uses the first usable result it finds. +PWA Wrapper needs a Java runtime to execute the Java-based build tools listed above. It searches for an installed JDK in the following order and uses the first usable result it finds. ### macOS Method @@ -85,7 +88,8 @@ Consult the following summary for information at a glance: | Category | What happens | When | Data leaves machine? | | --- | --- | --- | --- | | Gradle distribution download | Downloads `gradle-8.9-bin.zip` from `services.gradle.org` | First Android build only | No (download only; no data sent) | -| Bundled binary execution | Runs `apktool.jar`, `bundletool.jar`, `aapt2`, `apksigner.jar`, `android.jar` locally | Every applicable build | No | +| Bundled binary execution | Runs `apktool.jar`, `bundletool.jar`, `aapt2`, `apksigner.jar`, `android.jar`, and `adb.exe` (Windows) locally | Every applicable build | No | +| iOS signing without a Mac | Runs the bundled `zsign` or `zsign.exe` locally; may run a locally installed `openssl` to re-encode a temporary copy of the `.p12` file | Every iOS build with **Build without a Mac** selected | No | | JDK filesystem scan | Reads `JAVA_HOME`, `/Library/Java/JavaVirtualMachines/`, version manager directories, or Windows Studio Pro settings | When the builder opens | No | | Studio Pro filesystem scan | Scans `/Applications/` and `~/Applications/` for Studio Pro app bundles (macOS only) | When the builder opens | No | diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md index c34c5154f9b..64c14c63f38 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md @@ -2,14 +2,18 @@ title: "Sign PWA Wrapper Apps" url: /refguide/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/ weight: 25 -description: "Configure Android and iOS signing for PWA Wrapper on macOS and Windows." +description: "Describes how to sign Android and iOS apps with PWA Wrapper on macOS and Windows, including experimental iOS signing without a Mac." aliases: - /refguide/mobile/pwa-wrapper/sign-pwa-wrapper-apps/ --- ## Introduction -This page explains the signing step within the PWA Wrapper build flow. It covers Android signing on Windows and macOS, iOS signing on macOS, and the Windows-to-macOS handoff required for final iOS signing. +This page explains the signing step within the PWA Wrapper build flow. It covers the following scenarios: + +* Android signing on Windows and macOS +* iOS signing on macOS +* iOS signing on Windows, either with the experimental **Build without a Mac** option or by completing the signing on a Mac Use this page as a reference while completing [Build PWA Wrapper Apps](/refguide/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps/). @@ -21,16 +25,17 @@ PWA Wrapper includes signing as part of the platform build flow. The following s | --- | --- | --- | | Android | Windows or macOS | Create a local signing configuration and generate a signed APK | | iOS | macOS | Create an iOS signing configuration and generate a signed IPA | -| iOS | Windows | Prepare the iOS package and portable signing bundle, then complete signing on macOS | +| iOS | Windows, with **Build without a Mac** (experimental) | Create an iOS signing configuration and generate a signed IPA | +| iOS | Windows, with the portable signing bundle | Prepare the iOS package and portable signing bundle, then complete signing on macOS | -Keep the following rules in mind: +Keep the following constraints in mind: * Unsigned Android packages are suitable only for limited emulator testing * Unsigned iOS packages are suitable only for simulator scenarios * Installation on real devices and distribution of the app through a store require signing * Use the same signing identity for later builds of the same app to allow you to ship app updates -## Manage Signing Configurations{#configurations} +## Manage Signing Configurations {#configurations} To manage signing configurations in PWA Wrapper, do the following: @@ -59,7 +64,7 @@ Android signing works on both supported host platforms. Use the following guidance when choosing a signing approach: -* **No signing** is suitable only for local emulator testing +* An unsigned package is suitable only for local emulator testing * A signed APK is required for installing the app on Android devices * A release-signed package is required for normal distribution workflows such as Google Play submission @@ -93,12 +98,12 @@ After creating the signature, do the following: Keep the following recommendations in mind: * Use one stable signing configuration per app line if you plan to publish updates -* Back up the generated Android signing directory before moving to another machine—the relevant directories are listed in [Manage Signing Configurations](#configurations, above.) +* Back up the generated Android signing directory before moving to another machine—the relevant directories are listed in [Manage Signing Configurations](#configurations), above * Validate the signed APK on a physical Android device before release -## Sign iOS Apps on macOS +## Set Up iOS Signing -Final iOS signing is only supported on macOS. +The following steps apply to iOS signing on both macOS and Windows. ### Before You Start {#before-you-start} @@ -110,7 +115,7 @@ Before creating the iOS signing configuration, make sure you have the following: * A provisioning profile in `.mobileprovision` format * The passphrase for the `.p12` file -For Apple-specific background and asset preparation, use the official Apple documentation: +You can create these files yourself through the Apple Developer workflow, or receive them from the team that manages your Apple signing assets. For Apple-specific background and asset preparation, use the official Apple documentation: * [Certificates overview](https://developer.apple.com/help/account/certificates/certificates-overview/) * [Create a development provisioning profile](https://developer.apple.com/help/account/provisioning-profiles/create-a-development-provisioning-profile/) @@ -118,10 +123,10 @@ For Apple-specific background and asset preparation, use the official Apple docu Before building, verify the following: -* the bundle identifier in PWA Wrapper matches the app identifier used in the provisioning profile -* the provisioning profile was generated using the same certificate that was exported as the `.p12` file -* the certificate and provisioning profile type match the intended use, such as `development` for testing or `distribution` for release -* the target test devices are included in the provisioning profile when required +* The bundle identifier in PWA Wrapper matches the app identifier used in the provisioning profile +* The provisioning profile was generated using the same certificate that was exported as the `.p12` file +* The certificate and provisioning profile type match the intended use, such as `development` for testing or `distribution` for release +* The target test devices are included in the provisioning profile when required If you receive signing assets from another team, ask specifically for the exported `.p12` file, the `.mobileprovision` file, and the `.p12` passphrase. A `.cer` file by itself is not sufficient for PWA Wrapper. @@ -142,14 +147,17 @@ After you have the Apple signing files, do the following: PWA Wrapper stores the signing configuration for later iOS builds. +## Sign iOS Apps on macOS + +On macOS, PWA Wrapper signs iOS apps with Xcode or the Xcode Command Line Tools by default. You can also use the experimental **Build without a Mac** option on macOS to sign the app without Xcode. For more information, see [Build a Signed IPA Without a Mac](#build-without-a-mac). + ### Build the Signed iOS Package on macOS After the signature is configured, do the following: -1. Select the signature in the iOS build flow. -2. Complete the packaging steps. -3. Generate the package. -4. Retrieve the generated output from the build folder. +1. In the signing step, select the signature. +2. Complete the remaining build steps and click **Build**. +3. Retrieve the generated output from the output directory. Depending on your configuration, the output can include the following: @@ -164,49 +172,41 @@ Keep the following recommendations in mind: * Make sure the bundle identifier in PWA Wrapper matches the app identifier used in Apple signing * If device installation fails, verify that the device UDID is included in the provisioning profile you used -## Prepare iOS Apps on Windows - -Windows can prepare iOS packages, but it cannot complete the final signing step. +## Sign iOS Apps on Windows {#prepare-ios-apps-on-windows} -{{% alert color="warning" %}} -If you build an iOS package on Windows, you still need a Mac to produce the final device-ready IPA. -{{% /alert %}} - -### Prepare the Signing Files +On Windows, you can sign iOS apps in one of the following ways: -Before starting the Windows flow, obtain the following files from your Apple signing process: +* **Build without a Mac (experimental)** – PWA Wrapper signs the IPA on your Windows machine, so you do not need a Mac. For more information, see [Build a Signed IPA Without a Mac](#build-without-a-mac). +* **Portable signing bundle** – PWA Wrapper prepares the iOS package and a portable signing ZIP, and you complete the signing on a Mac. For more information, see [Generate the Portable Signing Bundle on Windows](#generate-the-portable-signing-bundle-on-windows). -* A `.p12` certificate export -* The `.p12` passphrase -* A matching `.mobileprovision` file +Both ways use the iOS signing configuration described in [Set Up iOS Signing](#set-up-ios-signing). -You can create these files yourself through the Apple Developer workflow, or receive them from the team that manages your Apple signing assets. For Apple-specific certificate, provisioning profile, and Keychain export steps, see the official Apple documentation linked in the [Before You Start](#before-you-start) section above. +### Build a Signed IPA Without a Mac {#build-without-a-mac} -If the Apple signing assets are created on a Mac by another team member, confirm that the delivered files are a usable `.p12` export and a matching provisioning profile. A `.cer` file alone is not sufficient for PWA Wrapper. +{{% alert color="warning" %}} +**Build without a Mac** is an experimental feature. Test the generated app thoroughly on a physical device before you submit it to the App Store. If the App Store rejects your submission, rebuild the app on a Mac without this option. +{{% /alert %}} -### Create the iOS Signing Configuration +The **Build without a Mac** option is available on Windows and macOS. After the signature is configured, do the following: -To configure iOS signing in PWA Wrapper on Windows, do the following: +1. In the signing step, select the signature. +2. In the build step, select **Build without a Mac (experimental)**. +3. In the **Experimental Feature** dialog, click **OK**. +4. Click **Build**. +5. Open the output directory and retrieve the signed device `.ipa`. -1. Open PWA Wrapper and select **iOS**. -2. Go to the signing step. -3. Select **Create New Signature**. -4. Enter a unique signature name. -5. Upload the `.mobileprovision` file. -6. Upload the `.p12` file. -7. Enter the `.p12` passphrase. -8. Click **Create Signature** to save the signature. +Depending on your configuration, the output can also include a simulator `.app` and the portable signing ZIP. ### Generate the Portable Signing Bundle on Windows -After the signature is configured, do the following: +If you don't select **Build without a Mac (experimental)**, PWA Wrapper on Windows prepares the iOS package but does not sign it. After the signature is configured, do the following: -1. Continue through the iOS packaging flow. -2. Generate the package. +1. In the signing step, select the signature. +2. Complete the remaining build steps and click **Build**. 3. Open the output directory. 4. Locate the portable signing ZIP created by PWA Wrapper. -The Windows output can include a portable signing ZIP together with other prepared iOS artifacts. The ZIP is intended to be moved to a Mac for the final modify-and-sign step. +The Windows output can include a portable signing ZIP together with other prepared iOS artifacts. Move the ZIP to a Mac for the final signing step. ### Complete Signing on macOS @@ -222,22 +222,31 @@ To finish the Windows-generated package on macOS, do the following: When the portable signing ZIP includes the `signing/` folder, the script can use the bundled `.p12` and `.mobileprovision` files for final signing. -## Troubleshooting and Limitations +## Limitations Keep the following PWA Wrapper-specific signing limitations in mind: -* Installation on a real Android device requires a signed package -* Installation on a real iOS device requires a signed IPA +* Installation on real Android and iOS devices requires a signed package * The iOS install step in PWA Wrapper is available only when the builder runs on macOS +* **Build without a Mac** is experimental, so test the generated app on a physical device before you submit it to the App Store * Changing signing identity between releases prevents normal upgrade installation for apps that are already installed * Provisioning profiles, certificates, and bundle identifiers must match the app you are packaging +## Troubleshooting + Common iOS signing mistakes include the following: -* uploading a `.cer` file instead of a `.p12` file -* exporting a certificate without its private key -* using a provisioning profile created for a different bundle identifier -* using a development certificate with a distribution profile, or vice versa -* forgetting to include the target test device in the provisioning profile +* Uploading a `.cer` file instead of a `.p12` file +* Exporting a certificate without its private key +* Using a provisioning profile created for a different bundle identifier +* Using a development certificate with a distribution profile, or vice versa +* Forgetting to include the target test device in the provisioning profile + +If you use **Build without a Mac**, you can also encounter the following errors: + +* **The provisioning profile is expired** – PWA Wrapper rejects an expired provisioning profile before signing. Upload or select a provisioning profile that has not expired, and build again. +* **The signing certificate is not authorized by the provisioning profile** – The `.p12` certificate is not one of the certificates the provisioning profile allows. Use a provisioning profile that was generated with the certificate in your `.p12` file, and build again. +* **The app icon cannot be processed** – The build fails with a message that names the part that could not be processed. Rebuild the app on a Mac with **Build without a Mac (experimental)** cleared. +* **A correct `.p12` passphrase is reported as wrong on macOS** – Older `.p12` exports, such as those created by Keychain Access, use an encryption format that requires OpenSSL on macOS. Install OpenSSL by running `brew install openssl@3`, and build again. If signing succeeds but installation still fails, verify the bundle identifier, signing type, provisioning profile, and target device eligibility before rebuilding. diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md index 11e47f936b7..8a820774086 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps.md @@ -78,14 +78,14 @@ If you use the installation step in the builder, keep the following in mind: For iOS packaging, install or prepare the following: -* Xcode or Xcode Command Line Tools to bundle and sign the iOS app on macOS +* Xcode or Xcode Command Line Tools to bundle and sign the iOS app on macOS, unless you use the experimental **Build without a Mac** option * Apple signing assets, including a `.p12` certificate and a `.mobileprovision` profile, if you want to build for a physical device or distribute the app * A bundle identifier that matches the Apple signing configuration, if you want to build for a physical device or distribute the app Install full Xcode if you want to use the iOS simulator for testing. {{% alert color="warning" %}} -iOS packaging for a final signed device build requires macOS. On Windows, you can prepare the portable signing package, but you still need a Mac to generate the final signed IPA. +To generate a signed IPA on Windows, use the experimental **Build without a Mac** option. Without this option, PWA Wrapper on Windows prepares a portable signing package, and you need a Mac to generate the final signed IPA. {{% /alert %}} ### Steps for iOS on macOS{#steps-on-mac} @@ -105,7 +105,7 @@ To generate a signed iOS package on macOS, do the following: * screen orientation 3. Review the available permissions and enable only the permissions related to the capabilities your app uses. For capability-to-permission guidance, see [Capability to Permission Mapping](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-capabilities/#capability-to-permission-mapping). -4. Go to the signing step and create or select an iOS signing configuration. For platform-specific details, see [Sign iOS Apps on macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos). +4. Go to the signing step and create or select an iOS signing configuration. For details, see [Set Up iOS Signing](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#set-up-ios-signing). 5. Continue to the packaging step and click **Generate Package**. {{< figure src="/attachments/refguide10/mobile/pwa-wrapper/package-ios-app.png" alt="Packaging step for building an iOS package with PWA Wrapper" max-width="500px" >}} @@ -118,9 +118,18 @@ To generate a signed iOS package on macOS, do the following: ### Steps for iOS on Windows -On Windows, PWA Wrapper can prepare the iOS bundle but not complete the final signing step. The builder produces a portable signing package that can be moved to a Mac. +On Windows, you can sign the iOS app directly with the experimental **Build without a Mac** option. Without this option, the builder produces a portable signing package that you must move to a Mac for the final signing step. -On Windows, use the same steps 1 through 7 as in [Steps for iOS on macOS](#steps-on-mac), then continue as follows: +To generate a signed IPA on Windows without a Mac, use the same steps 1 through 4 as in [Steps for iOS on macOS](#steps-on-mac), then continue as follows: + +1. Select **Build without a Mac (experimental)**, then click **OK** in the **Experimental Feature** dialog. +2. Continue to the packaging step and click **Generate Package**. +3. Wait for the build to complete. +4. Open the output directory and retrieve the signed `.ipa`. + +For more information, see [Build a Signed IPA Without a Mac](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#build-without-a-mac) in *Sign PWA Wrapper Apps*. + +To use the portable signing package instead, use the same steps 1 through 7 as in [Steps for iOS on macOS](#steps-on-mac), then continue as follows: 1. Open the output folder and locate the portable signing ZIP. 2. Copy the portable signing ZIP to a Mac. @@ -134,7 +143,7 @@ Keep the following limitations in mind: * The builder installation step for iOS is available only on macOS hosts * Copying packaged web resources is currently not supported on iOS, so the wrapped app must load its frontend resources from the deployed Mendix runtime -For platform-specific details about the signing step inside this build flow, see [Sign iOS Apps on macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos) in *Sign PWA Wrapper Apps* for macOS builds and [Prepare iOS Apps on Windows](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows) in *Sign PWA Wrapper Apps* for Windows builds. +For platform-specific details about the signing step inside this build flow, see [Sign iOS Apps on macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos) in *Sign PWA Wrapper Apps* for macOS builds and [Sign iOS Apps on Windows](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows) in *Sign PWA Wrapper Apps* for Windows builds. ## Choosing Permissions and Packaging Options @@ -188,6 +197,6 @@ If your app depends on device hardware, validate the final packaged app on repre After building the wrapper app, continue with the appropriate distribution process for your target platform. -If you still need platform-specific details for the signing step in the build flow, see [Sign Android Apps on Windows and macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-android-apps-on-windows-and-macos), [Sign iOS Apps on macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos), or [Prepare iOS Apps on Windows](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows). +If you still need platform-specific details for the signing step in the build flow, see [Sign Android Apps on Windows and macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-android-apps-on-windows-and-macos), [Sign iOS Apps on macOS](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#sign-ios-apps-on-macos), or [Sign iOS Apps on Windows](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/#prepare-ios-apps-on-windows). To understand which capabilities you can use from your Mendix app, see [PWA Wrapper Capabilities](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-capabilities/). diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md index 5d22ed050ba..9625016c298 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-limitations.md @@ -23,7 +23,7 @@ For an overview of the supported capabilities, see [PWA Wrapper Capabilities](/r Keep the following build and installation constraints in mind: -* Final iOS signing requires macOS +* Final iOS signing requires macOS, unless you use the experimental **Build without a Mac** option on Windows * Copying packaged web resources is currently not supported on iOS, so the wrapped iOS app must load frontend resources from the deployed Mendix runtime * Real-device installation requires signed packages * If an incompatible or newer build of the app is already installed on a device, it may need to be uninstalled before your current build can be installed diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md index e1b66a89687..91eec09eea9 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-security.md @@ -35,7 +35,7 @@ To avoid this download in air-gapped environments, pre-populate the Gradle wrapp ## Bundled Binaries Executed Locally -In addition to the runtime downloads above, PWA Wrapper ships the following binaries inside its own extension package. These are not downloaded at build time—they are included in the extension at install time and are invoked as local subprocesses during Android and HarmonyOS build, signing, and packaging steps. They run with the same operating-system privileges as the Studio Pro process. +In addition to the runtime downloads above, PWA Wrapper ships the following binaries inside its own extension package. These are not downloaded at build time—they are included in the extension at install time and are invoked as local subprocesses during Android, HarmonyOS, and iOS build, signing, and packaging steps. They run with the same operating-system privileges as the Studio Pro process. | Binary | Purpose | Platform | | --- | --- | --- | @@ -44,6 +44,9 @@ In addition to the runtime downloads above, PWA Wrapper ships the following bina | `aapt2` / `aapt2.exe` | Android Asset Packaging Tool | Android | | `apksigner.jar` | APK signing | Android | | `android.jar` | Android SDK stub library used during compilation | Android | +| `adb.exe`, `AdbWinApi.dll`, `AdbWinUsbApi.dll` | Android Debug Bridge, used to install the app on connected devices and emulators | Android (Windows hosts) | +| `zsign.exe` | iOS code signing when **Build without a Mac** is selected | iOS (Windows hosts) | +| `zsign` | iOS code signing when **Build without a Mac** is selected | iOS (macOS hosts) | These binaries are third-party open-source tools redistributed with the extension. They are not fetched from the network at runtime. @@ -53,7 +56,7 @@ When the builder opens, PWA Wrapper inspects the local machine to auto-detect ex ### JDK Discovery -PWA Wrapper needs a Java runtime to execute the build tools listed above. It searches for an installed JDK in the following order and uses the first usable result it finds. +PWA Wrapper needs a Java runtime to execute the Java-based build tools listed above. It searches for an installed JDK in the following order and uses the first usable result it finds. ### macOS Method @@ -85,7 +88,8 @@ Consult the following summary for information at a glance: | Category | What happens | When | Data leaves machine? | | --- | --- | --- | --- | | Gradle distribution download | Downloads `gradle-8.9-bin.zip` from `services.gradle.org` | First Android build only | No (download only; no data sent) | -| Bundled binary execution | Runs `apktool.jar`, `bundletool.jar`, `aapt2`, `apksigner.jar`, `android.jar` locally | Every applicable build | No | +| Bundled binary execution | Runs `apktool.jar`, `bundletool.jar`, `aapt2`, `apksigner.jar`, `android.jar`, and `adb.exe` (Windows) locally | Every applicable build | No | +| iOS signing without a Mac | Runs the bundled `zsign` or `zsign.exe` locally; may run a locally installed `openssl` to re-encode a temporary copy of the `.p12` file | Every iOS build with **Build without a Mac** selected | No | | JDK filesystem scan | Reads `JAVA_HOME`, `/Library/Java/JavaVirtualMachines/`, version manager directories, or Windows Studio Pro settings | When the builder opens | No | | Studio Pro filesystem scan | Scans `/Applications/` and `~/Applications/` for Studio Pro app bundles (macOS only) | When the builder opens | No | diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md index ad464cf1c8b..752d0c9dc3c 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps.md @@ -2,12 +2,16 @@ title: "Sign PWA Wrapper Apps" url: /refguide10/mobile/distributing-mobile-apps/pwa-wrapper/sign-pwa-wrapper-apps/ weight: 25 -description: "Configure Android and iOS signing for PWA Wrapper on macOS and Windows." +description: "Describes how to sign Android and iOS apps with PWA Wrapper on macOS and Windows, including experimental iOS signing without a Mac." --- ## Introduction -This page explains the signing step within the PWA Wrapper build flow. It covers Android signing on Windows and macOS, iOS signing on macOS, and the Windows-to-macOS handoff required for final iOS signing. +This page explains the signing step within the PWA Wrapper build flow. It covers the following scenarios: + +* Android signing on Windows and macOS +* iOS signing on macOS +* iOS signing on Windows, either with the experimental **Build without a Mac** option or by completing the signing on a Mac Use this page as a reference while completing [Build PWA Wrapper Apps](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps/). @@ -19,16 +23,17 @@ PWA Wrapper includes signing as part of the platform build flow. In the current | --- | --- | --- | | Android | Windows or macOS | Create a local signing configuration and generate a signed APK | | iOS | macOS | Create an iOS signing configuration and generate a signed IPA | -| iOS | Windows | Prepare the iOS package and portable signing bundle, then complete signing on macOS | +| iOS | Windows, with **Build without a Mac** (experimental) | Create an iOS signing configuration and generate a signed IPA | +| iOS | Windows, with the portable signing bundle | Prepare the iOS package and portable signing bundle, then complete signing on macOS | -Keep the following rules in mind: +Keep the following constraints in mind: * Unsigned Android packages are suitable only for limited emulator testing * Unsigned iOS packages are suitable only for simulator scenarios * Installation on real devices and distribution of the app through a store require signing * Use the same signing identity for later builds of the same app to allow you to ship app updates -## Manage Signing Configurations{#configurations} +## Manage Signing Configurations {#configurations} To manage signing configurations in PWA Wrapper, do the following: @@ -57,7 +62,7 @@ Android signing works on both supported host platforms. Use the following guidance when choosing a signing approach: -* **No signing** is suitable only for local emulator testing +* An unsigned package is suitable only for local emulator testing * A signed APK is required for installing the app on Android devices * A release-signed package is required for normal distribution workflows such as Google Play submission @@ -91,12 +96,12 @@ After creating the signature, do the following: Keep the following recommendations in mind: * Use one stable signing configuration per app line if you plan to publish updates -* Back up the generated Android signing directory before moving to another machine—the relevant directories are listed in [Manage Signing Configurations](#configurations, above.) +* Back up the generated Android signing directory before moving to another machine—the relevant directories are listed in [Manage Signing Configurations](#configurations), above * Validate the signed APK on a physical Android device before release -## Sign iOS Apps on macOS +## Set Up iOS Signing -Final iOS signing is only supported on macOS. +The following steps apply to iOS signing on both macOS and Windows. ### Before You Start {#before-you-start} @@ -108,7 +113,7 @@ Before creating the iOS signing configuration, make sure you have the following: * A provisioning profile in `.mobileprovision` format * The passphrase for the `.p12` file -For Apple-specific background and asset preparation, use the official Apple documentation: +You can create these files yourself through the Apple Developer workflow, or receive them from the team that manages your Apple signing assets. For Apple-specific background and asset preparation, use the official Apple documentation: * [Certificates overview](https://developer.apple.com/help/account/certificates/certificates-overview/) * [Create a development provisioning profile](https://developer.apple.com/help/account/provisioning-profiles/create-a-development-provisioning-profile/) @@ -116,10 +121,10 @@ For Apple-specific background and asset preparation, use the official Apple docu Before building, verify the following: -* the bundle identifier in PWA Wrapper matches the app identifier used in the provisioning profile -* the provisioning profile was generated using the same certificate that was exported as the `.p12` file -* the certificate and provisioning profile type match the intended use, such as `development` for testing or `distribution` for release -* the target test devices are included in the provisioning profile when required +* The bundle identifier in PWA Wrapper matches the app identifier used in the provisioning profile +* The provisioning profile was generated using the same certificate that was exported as the `.p12` file +* The certificate and provisioning profile type match the intended use, such as `development` for testing or `distribution` for release +* The target test devices are included in the provisioning profile when required If you receive signing assets from another team, ask specifically for the exported `.p12` file, the `.mobileprovision` file, and the `.p12` passphrase. A `.cer` file by itself is not sufficient for PWA Wrapper. @@ -140,14 +145,17 @@ After you have the Apple signing files, do the following: PWA Wrapper stores the signing configuration for later iOS builds. +## Sign iOS Apps on macOS + +On macOS, PWA Wrapper signs iOS apps with Xcode or the Xcode Command Line Tools by default. You can also use the experimental **Build without a Mac** option on macOS to sign the app without Xcode. For more information, see [Build a Signed IPA Without a Mac](#build-without-a-mac). + ### Build the Signed iOS Package on macOS After the signature is configured, do the following: -1. Select the signature in the iOS build flow. -2. Complete the packaging steps. -3. Generate the package. -4. Retrieve the generated output from the build folder. +1. In the signing step, select the signature. +2. Complete the remaining build steps and click **Build**. +3. Retrieve the generated output from the output directory. Depending on your configuration, the output can include the following: @@ -162,49 +170,41 @@ Keep the following recommendations in mind: * Make sure the bundle identifier in PWA Wrapper matches the app identifier used in Apple signing * If device installation fails, verify that the device UDID is included in the provisioning profile you used -## Prepare iOS Apps on Windows - -Windows can prepare iOS packages, but it cannot complete the final signing step. +## Sign iOS Apps on Windows {#prepare-ios-apps-on-windows} -{{% alert color="warning" %}} -If you build an iOS package on Windows, you still need a Mac to produce the final device-ready IPA. -{{% /alert %}} - -### Prepare the Signing Files +On Windows, you can sign iOS apps in one of the following ways: -Before starting the Windows flow, obtain the following files from your Apple signing process: +* **Build without a Mac (experimental)** – PWA Wrapper signs the IPA on your Windows machine, so you do not need a Mac. For more information, see [Build a Signed IPA Without a Mac](#build-without-a-mac). +* **Portable signing bundle** – PWA Wrapper prepares the iOS package and a portable signing ZIP, and you complete the signing on a Mac. For more information, see [Generate the Portable Signing Bundle on Windows](#generate-the-portable-signing-bundle-on-windows). -* A `.p12` certificate export -* The `.p12` passphrase -* A matching `.mobileprovision` file +Both ways use the iOS signing configuration described in [Set Up iOS Signing](#set-up-ios-signing). -You can create these files yourself through the Apple Developer workflow, or receive them from the team that manages your Apple signing assets. For Apple-specific certificate, provisioning profile, and Keychain export steps, see the official Apple documentation linked in the [Before You Start](#before-you-start) section above. +### Build a Signed IPA Without a Mac {#build-without-a-mac} -If the Apple signing assets are created on a Mac by another team member, confirm that the delivered files are a usable `.p12` export and a matching provisioning profile. A `.cer` file alone is not sufficient for PWA Wrapper. +{{% alert color="warning" %}} +**Build without a Mac** is an experimental feature. Test the generated app thoroughly on a physical device before you submit it to the App Store. If the App Store rejects your submission, rebuild the app on a Mac without this option. +{{% /alert %}} -### Create the iOS Signing Configuration +The **Build without a Mac** option is available on Windows and macOS. After the signature is configured, do the following: -To configure iOS signing in PWA Wrapper on Windows, do the following: +1. In the signing step, select the signature. +2. In the build step, select **Build without a Mac (experimental)**. +3. In the **Experimental Feature** dialog, click **OK**. +4. Click **Build**. +5. Open the output directory and retrieve the signed device `.ipa`. -1. Open PWA Wrapper and select **iOS**. -2. Go to the signing step. -3. Select **Create New Signature**. -4. Enter a unique signature name. -5. Upload the `.mobileprovision` file. -6. Upload the `.p12` file. -7. Enter the `.p12` passphrase. -8. Click **Create Signature** to save the signature. +Depending on your configuration, the output can also include a simulator `.app` and the portable signing ZIP. ### Generate the Portable Signing Bundle on Windows -After the signature is configured, do the following: +If you don't select **Build without a Mac (experimental)**, PWA Wrapper on Windows prepares the iOS package but does not sign it. After the signature is configured, do the following: -1. Continue through the iOS packaging flow. -2. Generate the package. +1. In the signing step, select the signature. +2. Complete the remaining build steps and click **Build**. 3. Open the output directory. 4. Locate the portable signing ZIP created by PWA Wrapper. -The Windows output can include a portable signing ZIP together with other prepared iOS artifacts. The ZIP is intended to be moved to a Mac for the final modify-and-sign step. +The Windows output can include a portable signing ZIP together with other prepared iOS artifacts. Move the ZIP to a Mac for the final signing step. ### Complete Signing on macOS @@ -214,28 +214,37 @@ To finish the Windows-generated package on macOS, do the following: 2. Unzip the package. 3. Open Terminal and change to the extracted directory. 4. Run `chmod +x run-on-mac.sh`. -5. Set the `.p12` passphrase as an environment variable by running `export P12_PASSWORD='your-passphrase'`. +5. Set the `.p12` passphrase as an environment variable without saving it to your shell history. To do this, run `read -rs P12_PASSWORD && export P12_PASSWORD`, then enter the passphrase and press Enter. 6. Run `./run-on-mac.sh`. 7. Open the `output/` folder and retrieve the generated device `.ipa` and simulator `.app`. When the portable signing ZIP includes the `signing/` folder, the script can use the bundled `.p12` and `.mobileprovision` files for final signing. -## Troubleshooting and Limitations +## Limitations Keep the following PWA Wrapper-specific signing limitations in mind: -* Installation on a real Android device requires a signed package -* Installation on a real iOS device requires a signed IPA +* Installation on real Android and iOS devices requires a signed package * The iOS install step in PWA Wrapper is available only when the builder runs on macOS +* **Build without a Mac** is experimental, so test the generated app on a physical device before you submit it to the App Store * Changing signing identity between releases prevents normal upgrade installation for apps that are already installed * Provisioning profiles, certificates, and bundle identifiers must match the app you are packaging +## Troubleshooting + Common iOS signing mistakes include the following: -* uploading a `.cer` file instead of a `.p12` file -* exporting a certificate without its private key -* using a provisioning profile created for a different bundle identifier -* using a development certificate with a distribution profile, or vice versa -* forgetting to include the target test device in the provisioning profile +* Uploading a `.cer` file instead of a `.p12` file +* Exporting a certificate without its private key +* Using a provisioning profile created for a different bundle identifier +* Using a development certificate with a distribution profile, or vice versa +* Forgetting to include the target test device in the provisioning profile + +If you use **Build without a Mac**, you can also encounter the following errors: + +* **The provisioning profile is expired** – PWA Wrapper rejects an expired provisioning profile before signing. Upload or select a provisioning profile that has not expired, and build again. +* **The signing certificate is not authorized by the provisioning profile** – The `.p12` certificate is not one of the certificates the provisioning profile allows. Use a provisioning profile that was generated with the certificate in your `.p12` file, and build again. +* **The app icon cannot be processed** – The build fails with a message that names the part that could not be processed. Rebuild the app on a Mac with **Build without a Mac (experimental)** cleared. +* **A correct `.p12` passphrase is reported as wrong on macOS** – Older `.p12` exports, such as those created by Keychain Access, use an encryption format that requires OpenSSL on macOS. Install OpenSSL by running `brew install openssl@3`, and build again. If signing succeeds but installation still fails, verify the bundle identifier, signing type, provisioning profile, and target device eligibility before rebuilding.