15. Using the Mac App Store

Written by Sarah Reichelt

After working through all the sections in this book, you now have four Mac apps. Each one is a different style of app, and each has a different purpose.

The next step in your journey to becoming a Mac developer is distributing your apps.

The App Store is the only distribution option for iOS apps, but macOS apps can use both the Mac App Store and external distribution.

In this section, you’ll look at both these possibilities. This chapter discusses the options and then covers using the Mac App Store for testing and release.

Distribution Options

What are the advantages and disadvantages of using the App Store?

First the advantages:

1. Apple handles everything. They serve the apps, they handle payments and refunds, they provide a review and rating mechanism, and they provide crash reports.

2. Users feel more secure about downloading apps from the App Store and are less reluctant to provide payment details.

3. You can open your apps for beta testing using TestFlight. Apple handles the distribution, feedback mechanisms and expiration dates automatically.

4. It’s easy to release updates to your app’s users. You upload a new version and the App Store app installs it.

And now for some disadvantages:

1. You’re at the mercy of the app review system. The reviewers pass most apps without problem or with minor modifications. But this isn’t always the case.

2. Apple takes a cut of your sales: either 30% or 15%, depending on whether you’re in the small business program.

3. Your app must be sandboxed. For most apps this is not a problem, but for an app like ImageSipper, this rules out the App Store.

4. Apple doesn’t support update pricing or free trials. You can fake a trial by making the app free and having an in-app purchase to unlock it, but this is messy. Apple has no provision for upgrade pricing. If you release a major revision and you want your existing users to pay, you have to create an entirely new app in the App Store. And then, there’s no way to give those existing users a discount.

You may wonder why I haven’t included the cost of the Apple Developer program as a disadvantage. As you’ll see in the next chapter, Apple is gradually making this a necessity regardless of your distribution method.

One nice thing is that you don’t have to pick one method or the other. You’re free to distribute your app through the App Store and externally at the same time.

But for the rest of this chapter, you’re going to walk through the process of testing and distributing via the Mac App Store. If you’re familiar with this from working with iOS apps, or if you’ve decided not to use the Mac App Store, then you can skip ahead to the next chapter.

Setting up your Developer Account

Apple has two sites that you’ll use. Apple Developer is where you’ll manage your membership, download beta software, read the forums and so on. And App Store Connect is where you’ll configure your apps, sign agreements, handle payments and perform other tasks related to distributing and supporting your app.

The first step is to make sure you have an Apple Developer account. You’ll need an Apple ID with two-factor authentication turned on. Start the enrollment process at the Apple Developer Program page.

Next, you need to accept agreements by going to Agreements, Tax, and Banking at App Store Connect. You must accept the Free Apps agreement. If you want to charge for your apps, you’ll also need to accept the Paid Apps agreement and provide your banking and tax information.

Once you have a Developer account, link it to Xcode. Open Xcode and go to Xcode ▸ Preferences ▸ Accounts. Click the + button and follow the steps to add your Apple ID account:

This allows Xcode to work out all the code signing and to generate the required certificates. And with all this set up, you can open Xcode to proceed.

For the purposes of this chapter, you’ll make a sample project and work through the stages of setting it up in App Store Connect and testing it through TestFlight.

Identifying Your App

Each app must have a unique identifier in the App Store. You set this using the Bundle Identifier. It identifies your app forever and can never change once you’ve created the app in App Store Connect.

Create a new app project in Xcode and fill in the Organization Identifier and the Product Name. Xcode uses those to generate a Bundle Identifier for the app.

The usual scheme for bundle identifiers is to reverse your domain name and add the app name. For example, imagine you develop as Great Mac Apps and your domain name is greatmacapps.com. When creating a new project for your ReallyUsefulApp, you’ll use com.greatmacapps as the Organization Identifier. Xcode generates a bundle identifier of com.greatmacapps.ReallyUsefulApp:

You can use my example Organization Identifier, but you’ll have to come up with your own app name. I’ve registered ReallyUsefulApp so it won’t work for you. :]

Note: If you’ve already linked your Apple Developer account to Xcode, you can set the Team here, but you’ll see another way to set it later in the chapter.

Once you’ve saved your new project, select the top entry in the Project navigator, click the target and go to the General tab. In the Identity section, you’ll see the App Category, Bundle Identifier, Version and Build:

Select the primary category for your app here. You’ll have to set this again in the App Information section of App Store Connect, where you can optionally choose a secondary category. But if you don’t set it here, Xcode complains later.

If you want to change the default Bundle Identifier, enter the new one here.

Version shows the versioning for the app. You can use whatever scheme you prefer, but one option is the Major.Minor.Patch scheme, often referred to as Semantic Versioning. In this scheme, the version has three numbers. Major updates increase the first number, minor changes increase the second number and bug fixes increase the third number.

Each version can have many builds. Open the About box for any app you’ve built. You’ll see the version followed by a number or string in parentheses. The part in parentheses is the build. You must change this every time you upload your app to Apple.

When you’re testing your app, you’ll keep the version the same and change the build to identify new updates.

When you update the released app, you’ll change the version and the build.

Code Signing

Apple uses code signing as a way to verify your app. When you upload your app to Apple, their servers analyze it, match it to your developer identity and attach a digital signature. If any malware changes the app’s code, the signature won’t match and macOS won’t run it.

Still in Xcode at the target settings, move to the next tab: Signing & Capabilities. You’ve looked at this tab quite a few times already, but only the App Sandbox section. Now, you’re interested in the Signing section.

The Bundle Identifier came across from the General tab. The item to set here is the Team. Since you’ve linked your account to Xcode, you can select your team name from this popup. This changes the Signing Certificate selection from Sign to Run Locally to Development:

Press Command-B to build your app. If it’s the first time you’ve used your account, you’ll get a dialog asking you to give codesign permission to access your Apple Developer account in your keychain. Enter your Mac’s user password and click Always Allow. If you click Allow, you’re going to get very sick of this dialog!

Next, go to the Product menu and select Archive. All the app builds you’ve done so far have been using the Debug configuration. Archiving uses the Release configuration, which removes debugging features only needed during development. When Xcode has finished creating the archive, it’ll open the Organizer window and show it to you:

Uploading Your App

Now, it’s time to make Xcode earn its keep. This next stage used to be very convoluted and tedious, but modern versions of Xcode do a lot of the work for you.

In the Organizer window, make sure you’ve selected the latest archive of your app and click Validate App. This checks to see if you’ve already set up the app at App Store Connect, and if not, offers to register it for you. This step saves a lot of time and effort. It creates an app identifier at Apple Developer, sets up a new app in App Store Connect and links the two:

Xcode suggests the app name and bundle identifier from the project. The language is your default language and the SKU also uses the bundle identifier. The SKU (Stock Keeping Unit) is an identifier for your purposes only. You can make it whatever you like, but it must be unique within your own apps. When you’re happy with these settings, click Next.

At this point, you’ll find out whether your app’s name is available. If you get an error because the app name is already in use, go back, change the name, create a new archive and try again.

Before starting a new app, it’s a good idea to do a preliminary search in the App Store for your preferred name. But even if it isn’t appearing in the App Store, another developer may have claimed the name and not released yet, or it may be available in another country. So at this stage, it’s trial and error until you find a unique name.

Once you get past that stage, there are more questions. Leave Upload your app’s symbols checked so you can get usable crash logs. You’ll see how to work with them later in the chapter. Let Xcode manage the versioning as it suggests, then click Next again:

The next dialog asks about signing your app. Select Automatically manage signing as it’ll save you a lot of grief. Click Next again. If you’re missing any developer certificates, Xcode now offers to generate them for you. Accept the offer; it’s another huge convenience as it means you don’t have to go to Apple Developer, generate all the certificates, then download and import them into your keychain manually.

Xcode whirs away for a while, then it shows you a summary for review. When you’re ready to proceed, click Validate:

Xcode gets busy again, and after a while, reports that your app has been successfully validated. Click Done to close the dialog.

And now you can see and configure your app at App Store Connect.

Configuring the App

Log in to App Store Connect and click My Apps. Find your new app, which should be the first one in the list, and click the icon or name to select it:

You’re now at your new app’s page in the App Store section. And you’ll see a lot of boxes to fill in!

The first entry in the sidebar is 1.0 Prepare for Submission, and that’s where you are now. The top section is for screen shots. Unlike for iOS apps, you only need to supply one size of screen shots. You can find the details under Screenshot specifications at App Store Connect Help. Scroll down to the Mac section to see the permitted image sizes. If you want to add a movie as an app preview, read App preview specifications. Again, you’ll need to scroll down to find the Mac details.

Next, work your way down the app page filling in the blanks. Don’t worry about the Build section yet. That’s where you’ll select a build for app review later.

In the App Review Information section, it’s important that you provide a username and password if your app has user accounts. If not, uncheck Sign-in required. Add any notes you think will help the reviewer decide in your favor and provide your contact details so they can get in touch if there’s a problem.

In the App Sandbox Information section, give details of any sandbox exemptions you’ve requested. This isn’t necessary if you only use the standard App Sandbox check boxes, but if you use any temporary entitlements, click the + button, select each entitlement and explain why you need it.

Scroll to the top and click Save when you’ve made your changes.

Now, step through the General section of the sidebar. In App Information, you can give your app a subtitle if you like. Select one or two app categories — Xcode doesn’t currently transmit the category you selected in your project.

Click Set up Content Rights Information, answer the question and click Done.

To set the rating for your app, click Set Age Rating Across All Platforms. Make a selection on each line and click Next. Answer the questions about web access and gambling, then click Next again.

You’ll see the age rating based on the information you provided, but there are two more checkboxes you can select if they’re appropriate for your app. Then, click Done to finish this section:

Click Save on this page and move on to Pricing and Availability. Select the pricing for your app in your local currency, and the App Store converts this around the world. Click Save to record your choice.

App Privacy

You may have noticed that apps in the App Stores now display their privacy settings and list how much of your data they gather. Select App Privacy in the sidebar and then click Get Started to fill this in. If your app collects any data, you’ll have to provide details.

You also need to provide a URL to your privacy policy. If you don’t have a privacy page, you can generate one at this App Privacy Policy Generator.

Click Publish when you’ve set that up.

And now that you’ve configured your app in App Store Connect, it’s time to upload it to the Apple servers and put your testers to work.

TestFlight

Apple has only recently opened TestFlight to macOS apps although it has been available for iOS apps for some years. TestFlight is a system that allows you to distribute pre-release versions of your app using the TestFlight app. You can have a closed test where you invite specific people to try your app, and you can have an open beta where up to 10,000 users can test it.

To set this up, return to Xcode and the Organizer window, opening it from the Window menu if it isn’t already open. Choose your app in the popup at the top left and select the latest archive. This time, click Distribute App.

Make sure App Store Connect is selected and click Next:

In the next dialog, confirm that Upload is selected and click Next again.

Since you’ve already validated the app, this should go through without a hitch. You’ll get the same dialogs, so keep clicking Next to use the same options as before. When you get to the summary, click Upload and wait for Xcode to do its thing.

When the upload is complete, you’ll get a new dialog and this one has a link to App Store Connect:

Get back to App Store Connect in your browser, click My Apps and select your app. This time, click TestFlight at the top. You may need to wait a few minutes before your app appears, but then it shows up in the Version 1.0 Build list, with its status set to Processing. The processing can take some time, so go get a cup of coffee and come back later.

Export Compliance

After Apple has processed your app, you’ll see a warning symbol marked Missing Compliance. Because Apple distributes your app from the USA, it’s subject to US export laws, and you must report if your app uses any form of encryption.

App Store Connect Help — Export compliance overview covers all the details. Read this to make sure you know what’s expected of you.

Click the Manage link and answer the question. If you answer Yes, you’ll have to work through a few dialogs, but eventually, you’ll get to where you can click Start Internal Testing:

If your app does not use any encryption, you can add this entry to your Info.plist:

<key>ITSAppUsesNonExemptEncryption</key>
<false/>

This saves you having to go through this for every new build.

Internal Testing

After you click Start Internal Testing, you’ll be back in the TestFlight tab for your app, but this time it’s listed as Ready to Submit. Before opening the app to external testers, Apple has to review it, but you can get it out to internal testers right away.

Internal testers are Users in your App Store Connect account. Click Users and Access at the top of the page and use the blue + button to add new users. They need to have either Admin, App Manager, Marketing or Developer roles to access TestFlight builds.

With your testers set up, go back to your app’s TestFlight settings. Click the + button beside Internal Testing and give your internal testers a group name. Leave Enable automatic distribution enabled and click Create:

Your build now has a Ready to Test status, and you can use the blue + in the Testers section to add your test users. They’ll receive an email invitation to join your test program:

If the user has TestFlight installed, the email link opens it and shows your app for the user to Accept and Install. Otherwise, the link opens a web page with instructions.

TestFlight installs the app in the Applications folder. Users can run it like any other app. The TestFlight app allows them to submit feedback with comments and screenshots:

You can view feedback reports in the TestFlight section of your app’s page in App Store Connect, under Feedback ▸ Screenshots. This is where you read all responses, even if the tester didn’t attach a screenshot.

New Test Versions

As you receive feedback, you’ll want to update the app and release new test versions. In Xcode, make your edits and then change the build but leave the version as it is. Archive the app and use the Organizer to Distribute the App as before.

Your testers receive notifications about all updates.

Keep iterating over this process until your app is ready for a bigger audience.

External Testing

Internal testing is for people in your organization, and you can invite up to 100 testers. External testing lets you open your app to many more testers. You invite specific people by email and you can publish a link to allow anyone to join your test program.

But, before you can release an app for external testing, you have to get it reviewed.

You’ll see Test Information in the sidebar with a yellow warning badge. Click the link, fill in all the fields and click Save at the top.

Note: If this doesn’t get rid of the yellow triangle, check Sign-in required, enter fake credentials and save again. Then go back and uncheck that option.

Click the + beside External Testing and add a group name for your external testers.

Select the build you want to test externally by clicking its build number. On the next page, enter what you want your testers to test and click Save.

You’ll see your internal test group already listed in the Group section. Click the +, check your external group and click Next. Now, you can confirm the test instructions before clicking Submit for Review:

Then wait. You should hear within 24 hours.

Once you have a build that Apple has approved for testing, you’ll see a public link in the TestFlight page for your external group. Copy the link and make it available for anyone who wishes to test your app. You can also add testers by email address:

Keep releasing new test versions as your users report in until you feel that your app is ready to meet the world.

Releasing Your App

By going through the TestFlight process, you’ve done most of the work already.

Log in to App Store Connect and open your app’s page. In the App Store tab, scroll down to Build, and click the blue + button. Select the build you want to release and click Done.

Make sure you’ve filled in all the app information as you want it to appear in the App Store. Scroll to the bottom of the page and set the release timing options.

Back at the top of the page, click Save and then Add for Review. Wait for around 24 hours, and you’ll receive the verdict from the app reviewer.

If all goes well, your app passes, and it appears in the App Store over the next few hours or whenever you specified.

But what if you get rejected?

In most cases, the reviewers are quite clear about what needs to change. You can appeal, but unless it’s a change that would break your app, the most productive move is to comply with their requests. Respond to let them know you’ve done so, upload a new build, cross your fingers and try again.

Apple has an App Review page with a section on Avoiding common app rejections, which has some useful advice.

Checking your Crash Logs

macOS users, like iOS users, have the option of allowing their systems to share crash reports and diagnostics with developers.

To see if your users have reported any crashes, open Xcode and go to Window ▸ Organizer. Select your app from the popup at the top left and then click Crashes in the sidebar. This includes crash reports from TestFlight and from App Store versions. You can adjust the filters across the top to see only the relevant reports.

Sadly, ReallyUsefulApp has crashed. :[

Once you’ve found a crash report, select it to see the full crash log. In the right sidebar, click Open in Project…. Select your project and click Open. Xcode opens your app’s project and goes to the Debug navigator.

Expand the thread showing the warning symbol to see the same details as in the crash report. The more prominent entries are more closely related to your own code and so are more informative. Click each one until you spot what caused the error. In this case it was quite obvious:

Who wrote this terrible code? ;]

Now, you can fix the problem and submit an update to TestFlight or to the App Store.

Updating the App

After your app has been available for a while, you’ll want to release a new version. Make your changes in Xcode, update the version and build details, create a new archive and upload to App Store Connect as before.

In your browser, log in to App Store Connect. Go to My Apps and select your app. In the sidebar, where it says macOS App, you’ll see your current version marked as Ready for Sale. Click the blue + to add a new version and enter its number.

Unless you’ve made major changes that need new informational text or new screenshots, you can leave most of the information as is. Fill in What’s New in This Version to let users know what you’ve changed.

You can go through the TestFlight process again, but if it’s a minor bug fix, you can go directly to the App Store. Once the Apple servers have processed your build, select it in the Build section, save the details and submit it for review.

As with a new release, you can specify whether you want the update released automatically or on a set date. Once the update is on the App Store, users get notifications through their App Store app.

Key Points

• The App Store provides a non-exclusive mechanism for distributing your macOS apps.
• You need an Apple ID with two-factor authentication and an Apple Developer account connected to Xcode.
• Xcode does a lot of the hard work of generating certificates, app identifiers and app records.
• TestFlight allows you to get feedback and bug reports for pre-release versions.
• Your app must pass app review before you can open it for external testing and again before you can release it on the App Store.
• You upload updates in the same way as new apps and Apple releases them to your users automatically.

Where to Go From Here?

If you need further information on any aspect of distributing your app through Apple, App Store Connect Help is very comprehensive.

Now you know how to test and distribute your apps through the Mac App Store. In the next chapter, you’ll look at ways to distribute your app outside the App Store.