Frameworks • iOS • 50:59
Last year we introduced the Files App and an easy way to view, edit, and share documents within your application. Learn best practices for implementing this technology, how to effectively manage documents in your app, and how to avoid common document manager pitfalls. Hear about the difference between a Document Browser and a Document Picker and when to use them. Gain a better understanding into how this technology works in a sandbox. Learn how to give your customers a great experience, beginning at sign-in and continuing throughout your app!
Speakers: Brandon Tennant, Thomas Deniau, Rony Fadel
Unlisted on Apple Developer site
Downloads from Apple
Transcript
This transcript has potential transcription errors. We are working on an improved version.
Good morning. Good morning, and welcome to Managing Documents In Your iOS Apps. I'm Brandon Tennant, a software engineer here at Apple and the Document Management team. And, later I'll be joined by my colleagues Thomas Deniau and Rony Fadel. So, today we're going to give you an overview of what document management on iOS is. And, then we'll share a few new things in this area.
Then, Thomas will come up on stage to show you how to use the Document Management API in your apps. And, finally, Rony will join us onstage to show you a few tips and tricks for raising the bar in your application. So, let's get started with a refresher about what document management on iOS is. It's a collection of technologies. First, there's an API for application developers. For cloud vendors, there's also the File Provider API. And, there's also the Files app.
In iOS 11, we introduced UIDocumentBrowserViewController. And, also significantly revamped UIDocumentPickerViewController. Using this new controller in your app, your customers will be able to manage and browse their files from all of their favorite cloud vendors. There's also powerful Search that searches across all of these cloud vendors. They'll be able to favorite Folders, and those favorite Folders will appear in the sidebar. And, they'll be able to organize their files using Tags. Recently used files also appear in the Recents tab.
So, by using UIDocumentBrowserViewController in your app, you'll be giving your customers a consistent experience, by bringing all of the power of Files into your app. It eliminates the need for you to write your own document browser. This allows you to focus on perfecting the experience your customers will have when viewing or editing documents in your app. To get started with this, see last year's session, "Building Great Document-based Apps in iOS." There's also API for cloud vendors. This is called the File Provider API. You use this to write file provider extensions, and also custom UI actions, including the account sign-in screen.
For application developers, you don't need to use this API for people to access your files. So, when you write a file provider extension, it will appear in the Files app, and in UIDocumentBrowserView Controllers, under the Locations tab-- under the Locations section. Also, because sign-in is implemented using FPUI ActionExtensionViewController, you'll want to use this so you can reduce friction for your customers by making logging into your service easier. Let's go through a few examples of that.
First, in this example, what you can do-- or, what the user is able to do, is sign into their service, without being interrupted from their workflow. They don't have to leave the app. They can just sign in and continue going along their business. An example of what to try and avoid, would be something like this, where there's redundant UI elements or branding onscreen. You can see the example of two nav bars, or two Cancel buttons. And, another example to try and avoid, is having a simple Sign In button, where all it does is launch to your application. This interrupts the customer's workflow. So, try to avoid doing that.
Lastly, we've seen great adoption from all of you developers and cloud vendors over the course of the last year. So, there's a lot of applications that use this technology already. So, now is a great time to try adopting UIDocumentBrowserViewController in your application today. And, if you're a cloud vendor that hasn't yet already provided a file provider extension, now's the time to do so. So, let's talk about a few new things.
First, for cloud vendors, we've seen some of the difficulties in making a file provider extension. And, what we're happy to announce today is there's a new tool for you. It's called the File Provider-Validation tool. This tool will guide you-- will help-- will run tests, and show you the issues with your file provider extension, and guide you towards fixing those. It's available for download today from developer.apple.com. And, when you download it, you'll get a couple of things. You're going to get a set of source files that you'll need to add to your file provider extension project, and an iOS application to install and run on your iPad.
Once you've modified your file provider project, installed the app on your iPad, and run it, you'll be greeted with a screen that looks like this. Your file provider will be listed-- will be shown on the left side, and when you tap that, there'a Run button that you can press to run our full suite of tests against your file provider extension. When you've done that, you'll see a list of successes and failures. You'll want to tap on the failure to dig deeper, and find the issues in your code. We'll be able to help you through this at the labs on Thursday and Friday.
Also, an exciting new thing this year announced was Siri shortcuts. And, we're happy to say that Siri shortcuts are coming to file provider extensions. What this does, is it surfaces recently used documents that were opened or created, and it makes them visible either in Search or on the Lock Screen.
You'll also be able to-- your customer will also be able to make shortcuts that are synced across devices. And, it's important to note that they're synced across devices, because in order to support this, your file provider will need to use unique identifiers for each file across all of the devices for a given customer. If this is true, or you can make this happen, all you need to do to support Siri shortcuts in your file provider extension is to add NSFileProvider UsesUniqueItemIdentifiers AcrossDevices to your file provider extension's info.plist file. Once you've done that, and submitted to the Store, you're done.
For application developers, there's nothing you need to do. For information about Siri shortcuts, check out yesterday's session, "Introduction to Siri Shortcuts." Also this year, we're happy to announce that we're releasing the Particle Sample app. This was sample code that we used in last year's session to demonstrate how to use UIDocumentBrowserViewController in your app. It looks like this, and it uses UIDocumentBrowserViewController as its main viewController.
It defines a file format. It implements state restoration, and imports assets using UIDocumentPickerViewController. You'll be able to download this today. The link is available in the WW app, and you'll also be able to search for it online. And, that's Particles. So, with that, I'd like to introduce Thomas onto the stage.
[ Applause ]
Hello, everyone. I'm Thomas, a software engineer on the Documents Management team. And, I'm going to take you through how you can leverage the document management features of iOS in your app. Together, we're going to discuss what the Document Picker and Document Browser are, when and how to use them. Then, we'll add a document picker to our demo app, Particles. And, finally, we talk about document types, and how to configure them properly in Xcode.
So, what does interacting with documents mean nowadays? Of course, it means that you need to provide UI to let your customers organize their documents. Starting with the ones in your app container. But, because most documents are in the cloud nowadays, it means that you need to let them access documents stored in the cloud, and in other apps.
How do you do this? Well, we have two solutions for you. The Document Picker and the Document Browser. What are the differences between these two? Well, both let you browse files stored locally on your iOS device, and in various cloud services. And, both let you access files from other apps.
However, they have different use cases. You [inaudible] Document Picker shortly, for a short period of time, for a quick user interaction with the files you want to reach. The Document Browser, on the other hand, is supposed to be the main document browsing UI of your app. Let's start with the Document Browser.
As Brandon mentioned, the document browser is what you see when you launch any of the UI applications. If your app is document-based, you should probably use a document browser to display these documents. And, if you choose to do so, this is what your customers will see when they launch your app. They immediately get to the files, which is what matters.
The Document Browser is full screen, and it lets your customers open and organize the documents that your app handles. As Brandon mentioned, it has all the features of the Files app. So, Search, Tags, Favorites, Recents, all of this comes for free, and we do all of the editing for you.
It can be customized with your own buttons, such as the [inaudible] button in the top right corner, or to match your application's look. As you can see, numbers and keynote look very different, yet both are based on the Document Browser controller. Of course, once your customer opens a document, you get to present your own UI on top of the browser to present your documentation UI for example. Now, because the Document Browser is the entry point of your app, it is best to make it the root view controller. However, we got a lot of feedback over the last year from you, saying it was not always easy to make it the root view controller.
If that is the case, we want to clarify the guideline we gave last year. The Document Browser can also be presented [inaudible] full screen, likely shortly after launch. However, it is still meant to be the starting point of your app. In document-based apps, what we should see first are the documents.
So, we do not recommend making it possible to get out of the browser. If you think you need to hide the browser, maybe what you might be looking for is Document Picker, which we are going to discuss next. How to get started with a new Document Browser controller.
You can start a new app in Xcode, and use the document-based app template. And, this template gives you Document Browser [inaudible] based app. If you have an existing app, and want to add a DocumentBrowserViewController to it, you can drag a Document Browser to your storyboard, and use the Initial View Controller checkbox in Xcode.
Once you have the Document Browser controller, you can customize it. You can add your own buttons to the bars and menus. And, you can set your own colors and themes to match your app's look. You can also customize the open and close document animations so that you get a nice zoom-in transition from your document's [inaudible] to your own document addition UI. To learn all about this, please watch last year's session, where we have covered this in detail. And, as Brandon mentioned, we have made the sample app that session last year, available as sample code today.
Now, the Document Picker is a different thing. You use it to let your customers open documents or assets stored in the cloud, or stored in other apps, but it is only shown to let them choose a file, and then it goes away. The Document Picker is what we use in Mail. When you want to attach a file to an email, you tap the Add Attachment button, and this sheet pops up. This is a document picker. You choose a file to attach, and the sheet goes away.
Same thing in iWork. If you want to attach a PDF, insert the PDF in your Pages document. You're going to tap this Insert From button, and the same sheet pops up. You choose a file, it goes away. So, if you need to display user interface to let your customers open-- view things from the cloud, and then hide it once the file is chosen, the Document Picker is a great option for you.
Why do we need to give you the Document Picker? Because as we have said, documents might be in multiple locations. They can be in the cloud, or in other app containers. And, by default, you do not add access to these. So, you need something to let you access, copy, and move documents between these locations, and this is what the Document Picker does.
It goes away once the files get chosen, so if you want something which stays onscreen for a long time, you should check out Document Browser instead. What can you do with Document Picker? You can use it for multiple things. You can use it to access files in the cloud directly. Now, creating copies, you can use it to move files to the cloud to implement a safety cloud feature. And, getting copies of documents is often confusing, but if you really want to, you can use it to copy things from and to the cloud.
So, let's say we want to let our customers access a movie they've stored in the cloud. This is a great use of Document Picker controller. You create a Document Picker controller, and you specify the types of file you want your users to choose as a first document. And, the second document is one of the constants we have described on the previous slide.
Then, you set the Document Picker delegate, because this is how we get notified that your customer has chosen their file, and you present it. Once the file is chosen, you're going to get called back at this delegate method. You get [inaudible] of your files in this method. You can use them directly. And, [inaudible] single URL, because there's a property you can set in the Picker to let your customer choose multiple files at once.
So, let's go ahead and add a Document Picker to our demo app, Particles, from last year. This is the app [inaudible] last year. It is based on the Document Browser to let me choose a file to open. As you can see, I have Recents, I have Tags, I have Search, I have Browse to list all my sources. All of this comes for free. Now, I can go ahead and open this file, and I can tweak this nice particle system.
Now, my customers love this app. But, they would like to make the particles a little nicer. So, they've asked the designers to design some better-looking particle images, and the designers have shared these images over iCloud. So, how do we get these images to customize them? What we're going to do, is add a Choose Image button in the navigation bar here to pick a file from iCloud, and customize these particles. So, you can open your storyboard, and here I am [inaudible] the controller. I'm going to drag a new bar button item to that editor. And, I'm going to animate Choose Image. [inaudible] Choose Image.
OK. Now, I get to write some code to present to the document picker of the controller. So, I can drag an action from my button to the source code, and I agree to call it Choose Image, and [inaudible]. Connect. And, now I have twice my code. So, let me display this in a bigger window.
Here I am in my chooseImage method. I'm going first to create a Document Picker controller. And, I specify the type of files I want my customers to choose. So, here this is UTTypeImage, and the mode. I'm using .import here because I want to embed the particle image in my document. But, in many cases, you will use [inaudible] here instead.
You set your document picker delegate, and you present it. When the Document Picker gets invoked, and the file is chosen, it going to call you back. So, we need to implement the document picker [inaudible] at method. I don't know if you noticed, but I have not set a property to choose document files. So, I'm going to check I have only one URL here. Get the first URL, and create an image from it. And, set it in our particle system, which is [inaudible]. Let's run this again. It [inaudible] my app and will open my simulator shortly.
So, here I am. I am in my simulator. I can open my file. And, I have this new Choose Image button in my navigation bar. I can tap it, and my Document Picker comes up. And, as you see, again, we have all the pictures of the Files app. We can search our files, you have Tags. You can browse. All of this comes for free. Now, my particle image is [inaudible] shared to me over iCloud, so they show up in [inaudible]. And, again, use this little star image here. Pick it, and my particles are little stars.
[ Applause ]
This was easy. And, when you are back at work, you will be able to add a Document Picker to your app in no time. It simply has very little code, and does not depend on any third-party library. Your customers simply get access to their files, no matter where they are stored. Now, you noticed that during the demo, we have again talked about file types. And, many among you probably don't know what these are. So, let's talk about file types.
Document Types let the system know which files your application knows how to handle. And, they're important because they let iOS open your app when the file is tapped in the Files app. They also let it show your app in the Share sheet. And, finally it lets iOS choose the proper icon for your documents.
So, if I configure my types properly, and if I want to [inaudible] extension, I'm going to see this when browsing particles files in the Files app. If I don't, I'm going to see this instead, which is not too good, and my customers won't be able to open my files from the Files app. So, let's configure this together.
There are two steps when you want to configure document types. You need to declare the type first, if it is not declared by iOS already, and then you need to claim it to tell iOS you can view or edit files of this type. Let's start with type declaration.
The first question you need to ask yourself is, do you need to declare it? Because in most cases, you'll be dealing with common file types, such as videos, images, PDFs, presentations, spreadsheets. If that is the case, iOS most likely already declared this for you. And, to know if this is the case, you can check out the documentation at this short URL. If that is the case, great, you do not have anything to do, and you can jump to claiming the type.
The other common case, is when you wrote an app which defines its own file format. You invented your own file format, and you get to define what that type is. Then you should declare your type as exported, which tells iOS you are the authority for this file type. This is a situation I'm in, in the Files app-- in the Particles app, sorry. My particles file format is my own. So, I can open Xcode to configure this type.
And, in this exported UI section, which lets me edit my info.plist, I specify the type identifier, which is a [inaudible] string that I choose. So, [inaudible] comes the example that [inaudible] sample code, the particles, and I need to declare a list of parent types in the Conforms To field.
What are parent types? Well, types form a tree, which we call the [inaudible] tree, and you can think of it like a [inaudible], like Swift. For example, JPEG images and HEIF images are both kinds of images. And, .image conforms to our root type for user-created, or user-visible, documents, which is called public.content. Now, public.content has other children, like, for example, public.spreadsheet.
You can find this list of types in the documentation I pointed to earlier. Now, we need to find a spot in this tree for my type, Particles. Since the particle system is not a common file category, there is no [inaudible] category for me. So, I can't just make it conform to public.content directly. And, I need to conform to public.content either directly, or indirectly through public.spreadsheet or .image if I want my files to show up in Recents and in Search.
Then you have a second tree, which we call the physical tree, which lets iOS know how the files are represented on-disk. And, here this is much simpler, because you only have two choices. In most cases, you will be dealing with a single file on disk for your document. If you need to group multiple resources together, and you have the file package, you're going to use com.apple.package. But, in most cases, you have a single file disk, so it's public.data. This is because I am in with particles, so I'm going to conform to public.data.
Now, because this is a tree, .data and .package both iterate from our root type from the physical hierarchy, which is public.item. But, you don't care about this, you just need to choose between .data and .package. Therefore, you have two parents, public.data and public.content. So, in my Xcode UI, I'm going to write, Conforms To public.data, public.content. The last thing I need to do is tell iOS which file extensions are associated with my type.
This is how iOS will know that .particles files are of the type [inaudible] defined. To do this, I add a UTType classification property to my [inaudible] properties. In this dictionary, I add a key called public.filename-extension, and [inaudible] file extension that you want to associate with your type. So, here I have a new item, of particles.
And, with this, our declaration is done. There's just one more thing I didn't mention. It is if you-- if this was the case where we were declaring our own type. But, you might also want to use type defined by another application. If that is the case, you also need to declare the type so that iOS knows about it, in case that app is not [inaudible].
And, because this is an imported type declaration, this means that if iOS finds an extra definition of that type somewhere else, it will prefer that definition over yours. This is also what you need to do if you want to use a common file type which is not declared by iOS yet. Now, do not freak out, it is the same UI as what we've just went through, except that it is in the imported section instead of exported.
Once you have your type defined, you can claim support for it, still in your info.plist, or the Xcode UI. To do this, you specify the type identifier that you have defined, and the only other thing that you need to do is define a rank. And, this lets iOS know what to do when you tap on the file and multiple apps can open this file. For this, you have three choices.
The first is if it is your own file type. You choose "owner." And, to be clear, this should only be used if you happen to have invented your own file type. In most cases, you want to use "default," if you can edit files of this type, or "alternate" if you can read files of this type, but not edit them. And a list of [inaudible], rules are different on macOS, so if [inaudible] macOS up, please check out this other short link.
When claiming support for a type, please be as specific as possible. We have just claimed support for a very specific file type, so .particles file type. But you can also claim support for categories, such as any image using public.image. This is fine, but you need to be as specific as possible to make your app show up exactly what it needs to show up. Do not claim support for [inaudible] types such as public.data or public.content, because this will make your app show up in places where your customers do not expect to see it, and it will confuse them.
So, what can you do with all of this information? Well, first, if you have a need to access files in the cloud, you should use the Document Browser or Document Picker to access these documents. Most cloud vendors have adopted our API's, so if you use one of these viewControllers, your customers will be able to access their files no matter where they are. And, you do not have to write code for each cloud vendor.
If you wrote your own custom document browsing UI before iOS 11, now's a great time to switch to UIDocumentBrowserViewController. It is packed with features-- it's packed with features, so please let us do the hard work, and just get all the features in your app for free. Finally, please make sure your document types are configured in Xcode properly so that your app shows up exactly where it needs to be, and help customers find it. And with this, I'm going to hand the stage over to my colleague Ronny.
[ Applause ]
Thank you, Thomas. Hello, everyone. I am Rony Fadel, a software engineer on the Documents Management team. So, Thomas has explained how easy it is to adopt a document browser and document picker API's in your app. Now, that you've adopted these API's, we'd like to cover some best practices to make sure that your app is a well-behaved citizen on the iOS ecosystem, the day you submit it to the App Store.
So, now that we've implemented a document browser-based app, or added picker support, now we're ready finally to pick some documents. Your app might want to access documents directly, avoiding the copies in import mode that Thomas has described, or if you want to edit your document directly. For this you'd need to invoke the Picker in Open Mode. In this example, we're in the Particles app, and we've created and presented a Picker in Open Mode. We're going to pick an image file to change our particle system's image.
Once we've picked a document, we receive a callback at one of these two delegate methods. The first one, if we're picking our document in the Browser, or the second one if we're picking it in the Picker, like our example. We see the document here, and we see actually the Document Picker here, serving our app the URL that we've just picked. If we attempt to access the document directly, we risk running into a permissions error.
Let's try to understand why this could happen. As you may know, your apps on iOS are Sandbox. The App Sandbox is a security feature, whereas every app has unrestricted access to documents in its own app container, and by default, access is restricted to documents in other containers, namely in other app containers and in cloud service containers. So, this is a security feature that guarantees that other apps and processes don't just go snooping around in your app container, accessing your documents. And, always make sure that if they do access them, access these documents, that is done with user consent.
So, since access to documents in other containers is restricted, how can your app gain access to these documents that your customer has picked? What we have to do, is to extend our App Sandbox to include these documents. Here's again the URL returned by the Browser or the Picker. This URL has a security scoped resource attached to it. You can think of this resource as a permissions token granted to you by the system, and accessing this token would allow your app to access this document.
We can start accessing this document using the following URL API's. When we call startAccessingSecurityScoped Resource, your app gets access to this document, and so you can start displaying or editing the document. And, once you're done using it, the document, you should call the stopAccessingSecurityScoped Resource API on that URL. And, as you can see here, access is again restricted to that document.
So, here's a simple recipe to guarantee that you will always interact successfully with Sandbox documents. We walked through this example where we make these calls. First, we make the startAccessing call on that URL, and so we can start interacting with that document. And, you notice in the defer block, we make the stopAccessing call once we're done using the document.
You notice that these calls are balanced, and that we only call stopAccessing if startAccessing returns "true." We keep resource access time as small as possible, because when we make this startAccessing call, we consume limited system resources, reserved just for your app. And so, we need to relinquish these resources once we're done using that document to make sure that we can access additional documents within our process. If you know for sure that this document exists inside of your app container, you do not need to make these calls. But, in case of doubt, make these calls. If they're not actually needed, they'll simply be a no-op.
Great. Now, we know how to gain access to our documents. We can go ahead and pick that document, like the particle image in our example. And, start accessing it. As you can see here, the cloud service that is hosting this document, as well as other apps also can access this document, and sometimes concurrently with your app. What we need here is a system-wide mechanism to make sure that access to this document is always coordinated, so that processes don't go stepping on each other's feet, accessing, reading, and writing to this document.
On iOS, this mechanism is called file coordination, and it is exposed via the NSFileCoordinator and NSFilePresenter API's. It acts as a system-wide multiple reader/single writer lock, and it's also the way for your app to instruct the system to download this document if it's not available locally. Because as you may know, a lot of these documents could be in the cloud, and not on the device.
So, you might find yourself writing a lot of boilerplate and error-prone code to handle sandboxing, to handle file coordination. If you're simply interested in displaying and editing your documents, the solution is much simpler. And, on iOS, it comes in the form of UIDocument. UIDocument has been available since iOS 5. It is the recommended way for your app to display and edit documents.
It handles sandboxing for you, so there's no need to make the start- and stopAccessing calls. And, it handles file coordination for you. So, there's no need for you to manually coordinate access to these documents. For more information on file coordination and UIDocument, we invite you to check out the "Building Document-Based Apps" session from WWDC 2015, which covers these topics in great detail.
Alright. We can now access our documents, and we are sure to read and write to them in a consistent state. We can edit our particle system. And now, what we're going to do is just switch apps for just a second, check out the WWDC webpage, and just jump back to our app.
Hmm. As you can see here, we were in the editor, but now we went back to the browser. Your customer always expects to be brought back to where they were when they were using your app. Let's try to understand what happened in our previous example. Here's a diagram of our app's lifecycle. We started off in the foreground while we were editing the app particle system, and we then were taken to the background when we used the App Switcher to switch to Safari.
The system suspended our app while it was in the background. It turns out that at the time, our system was under some memory pressure, and so the system terminated our app. When we used the App Switcher to switch back to our app, our app was relaunched. What we failed to do here was restore the UI state. And, that time was a good time to restore the UI state, to bring back our customer to where they were.
So, how do we implement state restoration? A simple and easy way would be to persist the URL we've received from the Document Browser, or the Document Picker, and restore it at app relaunch. That wouldn't work though, for two reasons. First, the document that the URL points to could have been moved or renamed. And so, we'd end up with a broken link at app relaunch. And second, the security scoped resource that is attached to our URL is not encoded when that URL is persistent.
And so, when we relaunch our app, we again lose access to this document, even if that document wasn't moved or renamed. The correct solution is to use a security scoped bookmark, that we get from our URL. And, as you can see, the bookmark correctly references the document, even if it has been moved or renamed.
To save the security scoped bookmark, we must first get it from the URL, using the bookmarkData API on the URL. And, we will then persist it to disk. Once our app is relaunched, we can restore the original URL using the URL resulting bookmarkData call. Alright. Now that we have all the ingredients to save and restore UI state, let's jump to a quick demo to see it in action.
So, here we are in the simulator, running the Particles app as seen previously. And, what we're going to do is just take our app to the background. And now, we are going to simulate the fact that the system is killing our app, by killing it in Xcode. If we launch our app again, we see that we jump back to the browser. So, now what we're going to do is implement state preservation and restoration, to be able to jump back to where we were.
So, I'll move to Xcode. First of all, in our app delegate, we'll declare to our app that we're interested in state preservation, and then restoration. And, to do that we first return "true" in application shouldSaveApplicationState. And also, return "true" in application shouldRestoreApplicationState. Second, we'll go to our storyboard, and give our DocumentBrowserViewController subclass a restoration ID, so that the system restores this object. And in this example, we'll simply use the storyboard ID.
Next, we're going to implement state preservation and restoration in this documentBrowserViewController subclass. So, first I start by implementing encodeRestorableState. We get the editorViewController, if it exists, and get the document URL from it. Once we have that URL-- I'm going to make this a bit bigger. Once we have this URL, we start accessing it to extend our Sandbox as described previously. And, the defer block, we stop accessing once we are done using it. If we can start accessing this document, we simply create a bookmarkData block from this document, and encode it.
And, finally, we don't forget to call super. Alright. Now that we know how to encode our restorable state, we'll implement restorable state decoding. And, to do this, we start implementing decodeRestorableState. And, we'll do the inverse steps. So, first we get the bookmarkData from the coder. And, if it exists, create that document URL using the URL resolvingBookmarkData call. And, we simply present the document at that URL. And, last but not least, we don't forget to call super. Alright. So, let's run our app.
And so, our app will now be launched in the simulator. As you can see, we can start using our document. And, again, going to take our app to the background. Simulate the system killing our app. And, we're going to relaunch our app, and as you can see here, we're back to our editor.
[ Applause ]
Awesome. We can now access documents, read and write to them without risking data corruption, and we can now even restore state and bring our customer back to where they were when they were using our app. Even if our app was killed in the background. So, if you open the files up, and we tap on Share in the callout menu, on documents that your app can handle, you notice that our app is now available in the Share sheet.
However, it says "Copy to" instead of "Open in." What this means is as soon as we tap on our app icon in the Share sheet, the system will make a copy of this document, and serve this copy to our app. And, practically this means that the customer would start editing a copy of the document. To allow your customers to open and edit the original document that we wish to access in your app, you need to adopt an iOS feature called Open in Place.
If you do adopt Open in Place, you see the "Open in" your app in the Share sheet, instead of the previous "Copy to." Adopting Open in Place is very simple. If you use the document-based app Xcode template, you'll get this behavior for free, as Open in Place is already enabled by default there.
Otherwise, you'll need to add the LSSupportsOpeningDocumentInPlace to your info.plist. Once you've declared to the system that your app handles Open in Place, we must access the document in the following UI application delegate method. Again, if your app is document browser-based, typically in this method, you make the revealDocument call on the documentBrowserViewController. Once the completion handler is called in this method, you present the document in the completion handler. This is already done for you in the Xcode template.
We can now tap on our app icon in the Share sheet, and go straight to our app. As you see here, we report progress in the UI, since the document could be in the cloud. And, since that download could take awhile, we also support user cancellation, so we can cancel opening this document, and jump back to the browser.
Here's how you can implement progress supporting in your app. If you call the documentBrowserViewController revealDocument API that's been described previously, you get that UI for free. So, you'll see a loading UI on top of the icon in the browser. Otherwise, you may opt to display your own progress UI. If your app uses UIDocument, you should know that UIDocument conforms to progressReporting. And so, to display your own progress UI, you simply access the progress property to display your own progress. Alright. Our app is now awesome. And, we're finally ready to ship it.
So, what's the takeaway today to make your apps excellent at managing documents on iOS? Adopt UIDocument when displaying and editing documents, as it eliminates a lot of boilerplate and error-prone code. However, if you already have document editing code that doesn't use UIDocument, adopt the start- and stopAccessing best practices to make sure that you interact successfully with Sandbox documents, or Sandbox-- with the app Sandbox. And also, coordinate accesses to your documents to make sure that you read and write to them in a consistent state.
Implement state restoration to always bring back your customer to where they were, when they were using your app, even if your app is killed in the background. Adopt Open in Place, so that your customer always edits the original document, and doesn't need to start editing copies of that document. And, also report progress, especially in a world where most of these documents could be in the cloud, and not available locally.
So, what did we cover today? We have shown you how easy it is to adopt the Document Browser and Document Picker API's. Give them a try in your app today. We learned about best practices so that our apps become excellent at managing documents, and for you cloud vendors, we talked about the new Siri shortcuts, and how they allow your app-- sorry, your documents that are frequently accessed to be available throughout the system for your customers.
And, we talked about the fileProvider validation tool, and gave guidelines on how to implement an effective authentication flow in your fileProviderUI extensions. For more information about this session, check out the session webpage at the following URL. Also make sure to check out this year's "Introduction to Siri Shortcuts" session. Thank you for your time. Have a great afternoon, and see you at the labs. Thank you.
[ Applause ]