14.
Third-Party Distribution
Written by Marin Bencevic
Heads up... You’re accessing parts of this content for free, with some sections shown as text.
Heads up... You’re accessing parts of this content for free, with some sections shown as text.
Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.
Unlock now
If you’re reading this chapter, you’re probably considering taking destiny into your own hands and releasing your app without the App Store.
It’s dangerous to walk that road alone! Take this chapter as a guide. It will talk you through preparing your app so anyone can download it and install it. You’ll learn how to notarize your app, how to create a DMG file for your app and also some tips on surviving the harsh world of 3rd party macOS app distribution.
Note: In case you’re wondering, push notifications and CloudKit will still work, even if you’re not distributing your apps on the App Store.
Before you get started with distributing apps, you’ll need an Apple ID enrolled in the Apple Developer Program. Yes, even though you’re not using the App Store, you still need a developer account.
The process of distributing apps is complicated by an annoying but useful macOS feature called Gatekeeper. Gatekeeper constantly checks the apps you’re running, making sure there’s nothing shady inside of them. Have you ever launched an app only to be surprised by an alert telling you the app is from an unidentified developer? That’s Gatekeeper.
You’ve probably noticed not all apps cause this alert to pop up. It usually happens with less-popular or non-native apps. The ones that don’t pop up the alert are properly signed and notarized. In the next section, you’ll do that for your app to make sure Gatekeeper lets your users run it.
Signed, notarized and delivered
Note: To learn more about what code signing is and how it works, take a look at Chapter 13, “Releasing on the App Store”.
For other people to run your app, you’ll need to sign it with a Developer ID certificate. That’s a special kind of certificate that lets you distribute your app outside the App Store. Only the Account Holder of your Apple Developer account can create this certificate.
If you have a personal Apple Developer account, you’re already the Account Holder. If you’re in a team, check your role by going to App Store Connect’s Users and Access section: apple.co/2Da59iB. If you see yourself in the Account Holder tab, you’re good.
If you’re not the Account Holder, you’ll have to ask the Account Holder to export a macOS Developer ID Application certificate for you. They can do that from Xcode. Apple provides easy-to-follow instructions on how to export certificates: apple.co/2mj29Mh.
Signing, however, is not enough. You also need to notarize the app. Notarization is a process where you send your app to Apple and let them perform automatic checks on it to make sure it’s not doing anything malicious. Once Apple confirms the app is okay, they give your app a ticket. This ticket tells Gatekeeper to relax when a user opens your app, because Apple checked it.
Think of notarization as an airport security check: Your app needs to go through TSA before it can fly across the world to your users’ Macs.
In the last chapter, I mentioned code signing guarantees you made your app and haven’t changed it since you signed it. The latter part is important for notarization: Whenever your app changes, you need to renotarize the app’s binary.
Keep in mind that notarization is an automatic process that usually takes a couple of minutes. It’s much more relaxed than App Review and you should expect your app to go through notarization without any issues unless you’re doing something very suspicious.
Apple made notarization easy; you can do everything in Xcode. Open your app in Xcode.
The first thing you need to do is make an archive of your app. Before you do that, make sure your project compiles without any errors. Then, in the menu bar go to Product ▸ Destination and make sure you’ve selected My Mac. Click Product ▸ Archive. This compiles your app and creates an executable that you can notarize. Depending on the size of your app, this process might take a few minutes — you can think of a cool website domain while you wait. :]
Once it’s finished archiving, Xcode will open the Organizer. In the sidebar, you should see your app under macOS Apps. If you just created an archive, your app should be selected, but you can come back here later and select the app and all your archives will be listed.
Now that you have an archive, the next steps are signing and notarization. Xcode automatically does this in one fell swoop.
Note: To notarize your app, you need to have Hardened Runtime enabled. The Hardened Runtime locks down the app and protects your users from exploits. It’s enabled by default for Catalyst apps, so unless you disabled it manually, you should be fine. You can see it in Xcode in the Signing & Capabilities tab of your app target’s settings.
Click Distribute App. In the screen that pops up, select Developer ID and click Next. Select Upload and click Next. In the next screen, select Automatically manage signing.
Note: At this point, Xcode might show an error saying that you either don’t have a Developer ID certificate or you don’t have its private key. If that’s the case, contact your Account Holder and make sure they export a new Developer ID Application certificate by following Apple’s instructions: apple.co/2mj29Mh.
Once signed, you’ll get a summary.
Click Upload and Xcode will start uploading the archive to the notary service.
Now you wait. If you’ve decided on your domain, maybe you can brainstorm some website design ideas at this point. :]
You can check your app’s status in the Organizer. If you closed the window, you can open it by selecting Window ▸ Organizer. You’ll see the status under the Status column. You can also click on Show Status Log to see what’s been going on.
Once notarization completes, it will change to Ready to distribute. If something goes wrong, the status will change to Rejected. In that case, you can click on Show Status Log to see why the notarization service rejected your app.
Now that you have a notarized app, you can export the binary you’ll share with your users. Click Export Notarized App from the right sidebar. Select a location on disk and you’ll have your app!
While you could distribute this app as it is, most developers choose to distribute their apps as compressed disk images, aka DMG files. In the next section, you’ll see how and why you’d do that.
Creating a DMG file
If you’ve ever downloaded a macOS app, chances are it came in a .dmg file, which is short for Disk Image. When you double-click a .dmg file, it mounts a new disk that contains the app and sometimes additional files like a read-me document.
Cleaning up your window
First, let’s clean up the window. Press Command-1 to view the disk image as a grid of icons. Then, in the View menu, hide everything that isn’t already hidden by clicking Hide Toolbar, Hide Path Bar and Hide Status Bar. You should see a completely blank window.
Adding your app
Now that the window looks nice, it’s time to add your app and an alias to Applications. From a different Finder window, copy your exported app to the disk image and position it in the left box.
Notarizing disk images
You can sign and notarize a .dmg file pretty quickly, just by using the command line. You’ll begin by signing the .dmg file.
codesign \
-s "Developer ID Application: Ray Wenderlich (3G4T3B2D7X)" \
Journalyst-converted.dmg
xcrun altool --notarize-app \
-f Journalyst-converted.dmg \
--primary-bundle-id com.raywenderlich.Journalyst \
-u ray@raywenderlich.com
No errors uploading ’Journalyst-converted.dmg’.
RequestUUID = 66accdd9-7d26-4173-8e88-ea53f61b37b0
xcrun altool --notarization-history 0 \
-u ray@raywenderlich.com
Date RequestUUID Status Status Code Status Message
----- ----------- ------- ----------- ----------------
(...) (...) success 0 Package Approved
xcrun stapler staple Journalyst-converted.dmg
Key points
- To distribute macOS apps without the App Store, you need to sign the app with a Developer ID certificate.
- Apps and other software packages need to be notarized to verify they’re malware-free.
- You can use Xcode to notarize apps.
- You package apps inside disk images (.dmg files) for easier downloading and installation.
- Sign .dmg files using the
codesigncommand-line tool. - Notarize .dmg files using the
altoolcommand-line tool. - After notarization, make sure to staple the ticket to the .dmg file by using the
staplerutility.
Where to go from here?
Unfortunately, unless you want to distribute your app via email, you’ll also need a website to host and show off your app. If you’re making a paid app, you’ll need to deal with payments and managing licenses. This sounds scary, but there are some tools to help you.