Improve MDM assignment of Apps and Books

♪ ♪ Hello and welcome to WWDC. I'm Austin, and I work on the Apps and Books Management API. I'll be sharing with you improvements we have brought to a new API version, enabling your MDM solution to manage Apps and Books in a faster and more scalable way than ever before. You're likely already using the Apps and Books Management API to enable organizations using your product to manage their owned apps and books.

The organization may have acquired these assets through either Apple School Manager or Apple Business Manager. And the API allows for you to assign these owned apps and books to the organization's managed users and devices. We've introduced a lot of changes this year to the new Apps and Books API. We'll cover many of these throughout this session but focus on the two enhancements that will most improve your workflows: Real-time notifications and Asynchronous processing. For an in-depth look at the other changes, see the new developer documentation within the Device Management section on developer.apple.com and in the references for this session. Let's get started with Real-time notifications.

We now support Real-time notifications for state changes to assignments, assets, and registered users. You need to opt-in to these notifications, and you will only receive notifications for the types you subscribe to in client config.

Real-time notifications finally remove the need for you to continually sync state. Let's discuss the notification types a little more in-depth. The first notification type is for assignments.

An assignment is when an asset is allocated to either a user or device managed by an organization.

If you have to wait for confirmation that entire groups of assignments have been performed successfully, that will lead to delays in installing the content that users need. Now, with assignment notifications, you'll know in real-time exactly what assignments have successfully been performed and to which devices.

You subscribe to the asset management notification type in client config to receive these.

Apple will then proceed to notify you when assignment states are altered by either an associate, disassociate, or revoke assets event.

You may now rely on these notifications to provide users and devices faster access to content as they are assigned. Let's look at an example of this notification. When an assignment occurs, you get this notification. The example here was triggered by an associate assets call.

Apple posts these notifications with a shared secret in the authorization header provided by you in client config. The notification contains a payload, which is specific to a given notification type.

The type is denoted here, which for this notification is asset management. In our notification payload, we can see the assignments whose state has attempted to be altered, event ID, the unique identifier for this MDM-triggered asynchronous event. We'll get into more detail regarding the asynchronous nature of our new API in a bit.

Here is the result of the state change, whether it succeeded or failed.

And the type of change to assignment state, which here is an associate. The next notification type is for assets.

Assets are apps and books that an organization has purchased in either Apple School Manager or Apple Business Manager. That organization is not able to manage and assign the assets until your MDM knows that they own the content. With asset notifications, you're notified in real-time when changes to assets occur from purchases, transfers, or refunds, and your MDM can always know the current available count of each asset. You subscribe to the asset count notification type in client config to receive these.

Apple will then proceed to notify you when an asset state changes due to either a buy, transfer, or refund event.

These notifications will allow you to quickly provide users with their recently purchased assets. Let's also take a look at an example of this notification with the context of what the state of assets looked like before. To get the current state of assets, we call the "get assets" endpoint.

This is the new asset sync endpoint, which you can note by both the proper HTTP request method of GET and the versioned URI. Here, we are querying with the query parameters of adamId and pricingParam to receive the state of a single asset.

We are now requiring that the server token or sToken is provided in the authorization header of all new API requests in this bearer token format. We see in the assets array of this response for the asset we are interested in, there are 10,000 available for assignment and 15,000 in total. When a buy happens, you will get this notification. We see in the payload, the adamId for the asset that was purchased.

Then the delta, which in this case is a positive integer. This could either denote a buy or a transfer. You'd use this delta to update your counts without making another call to the asset sync endpoint. The last notification types are for registered users. Most deployments rely on device-based assignments, but when you need to assign content to users, creating registered users is the first step.

Associating these users to either personal or managed Apple IDs is then necessary for deployment. For a user's personal Apple ID to be associated to a registered user for a given sToken, the user must accept an invitation to associate their Apple ID. Now, with registered user notifications, you'll be updated in real-time with the latest state of users, both for their initial creation and subsequent invitation acceptance. You subscribe to the user management and user associated notification types in client config to receive these. Then Apple will notify you when user states are altered by either create, associate, update, or retire user events.

The user associated notifications specifically allow you to better track when a user has accepted an invitation to associate their Apple ID. Let's take a look at an example of these notifications with the context of what the state of users looked like prior. In order to get the current state of users, we call the get users endpoint. This is the new users sync endpoint. Here, filtering only for the user we are interested in by the clientUserId query parameter. This will limit the response size to only one user. Here, we have some common pagination fields found across our sync API, indicating the current page index, size, or in this context, the number of user objects in the current page, and the total pages in the provided query.

In our users array, we can see the only user we are interested in, in this case, with a status of registered, as opposed to associated, and an invitation code. This user has clearly yet to be associated to an Apple ID. All our sync API also include a version identifier, which will change whenever a write occurs to the underlying data. This can be extremely useful when traversing large responses to indicate when data on prior pages may have changed. You can associate a managed Apple ID to a registered user using the new update users endpoint. This results in a registered user notification as seen here. In our notification payload, we see users whose state has attempted to be altered, unique identifier for this MDM triggered asynchronous event, the result of the state change, whether it succeeded or failed, the type of change to user state, which here is an update. Looking at the users array, we see the clientUserId for the user's state we are interested in, containing an idHash and status of associated, concluding that the managed Apple ID association was successful. You use this to update your state of this user without making another call to the user sync endpoint. Instead of you associating, it is instead possible that you provide the user with an invitation link to associate their own Apple ID to the registered user. Here, we are looking at that associated user notification. We see in the notification payload the user object containing the information regarding the associated user including but not limited to their clientUserId, an idHash indicating an associated Apple ID, the invite code they accepted, and status denoting associated. You use this to update your state of this user without making another call to the user sync endpoint.

Let's talk about how you enroll to receive these notifications. You must opt in via client config for each sToken you manage.

You provide a shared secret for authentication with the notificationAuthToken and the notificationUrl to post these to. The token is used to verify that these notifications are, in fact, coming from Apple, and this can be updated anytime via client config.

Provide an HTTP 200-level response when you receive notifications in order to let Apple know that they've been delivered successfully. Apple will attempt to retry the notification if a non-200 response is returned or a timeout occurs. Apple will provide a best-effort delivery. This attempt to reach you will be made a few times before discarding the notification. This means if you are unable to receive notifications for any period of time, you will need to poll for the latest state. Sync only for what you know to be in a potentially stale state as a result of the missed notifications.

The second major enhancement brought to this new API is asynchronous processing.

In the initial version of the API, all management was performed synchronously. You make a request to manage some assets, and Apple performs the management while you wait for a synchronous response. This meant you handled parallelism, whereas asynchronous processing enables server-enforced parallelism on Apple's end. This results in processing optimizations, which leads to larger requests being fulfilled more quickly.

Ordered processing reduces the amount of intermittent failures and subsequent retries due to your specific request patterns.

And this ultimately leads to stress-free large deployments, and, for education, easier back-to-school seasons. Apple has already benefited from asynchronous processing for Apps and Books, purchases, and transfers in both Apple School Manager and Apple Business Manager, allowing organizations to see inventory on hand in minutes rather than hours.

Let's look at how this all comes together to make for a great new Apps and Books management experience.

Say there's an organization that you manage with 10,000 users, each with their own device.

And you're asked to assign 25 apps that are critical for their daily tasks to each device.

You're looking at performing 250,000 assignments. Let's look at how you would have done this previously.

Your server makes a request to Apple to manage licenses. Apple returns a response to you synchronously. This response would contain the licenses assigned to requested devices.

This single request manages only one app up to a maximum of ten devices, resulting in only ten assignments.

This requires a minimum of 25,000 requests to perform the 250,000 assignments. With the new API, this 25,000 minimum requests becomes just 10 requests, all possible by moving to asynchronous processing. Let's look at how you achieve this.

On the left, we now have the addition of your notification server. Process still starts with you making a request to Apple to manage assets. In the request, you provide the sToken in the authorization header. You can now provide us with multiple assets in a single request, up to 25 currently. This dynamic limit is exposed in service config and provide up to 1,000 devices to perform assignment to, another dynamic limit also exposed in service config. Apple will return a response synchronously to you.

In this response, we have the HTTP status code, which is important to this new API. We return appropriate non-200 status codes for errors, so you should initially interrogate the response to ensure it is a 200 before proceeding. Then, most importantly, we have the unique identifier for this asynchronous event whose status can either be gotten from calling our new event status endpoint or by waiting for matching assignment notifications. As the assignments complete, assuming you are subscribed, Apple will post notifications to you. In each of these notifications, we have a subset of the requested assignments listed in our notification payload, the metadata regarding the assignments, indicating whether it was a success or a failure, the type, and the corresponding event ID. You should wait for these successful assignment notifications to then proceed with sending install commands to the devices listed. Another advantage of our new management endpoints is Ordering. Let's say you get a request to reassign some assets from one group of users to another. This can be achieved by you sequentially firing off a disassociate followed by an associate request. First, you post the disassociate request. Apple then responds with the event ID for the disassociate. Then, you post the subsequent associate request. Apple responds with another event ID, but this time, for the associate. Assuming you are subscribed, Apple will post notifications to you as the disassociations complete. Then, Apple will post notifications to you as the associations complete. Big changes to our API, like notifications, allow you to keep your state in-sync with Apple, removing the need to continually make requests to ensure you have the latest state.

Asynchronous processing allows for everyone to have a better experience, whether it be employees or students getting access to the content they need, IT admins performing large deployments rapidly, or you effectively managing an organization's assets.

The legacy API will continue to be supported at this time. Note that using the new and legacy API versions in conjunction for the same token will not be officially supported.

This new API is the way forward for Apps and Books Management and is available today. We look forward to you testing and integrating with this new API as soon as possible, providing your users with the best possible Apps and Books Management experience.

For more insight, please check out our updated developer documentation. Thank you for your time, and hope you enjoy the rest of WWDC. [ethereal percussion music]