iOS: What does the "Document Storage" setting actually mean for my app? How do I honour it?

I have an app that is successfully storing documents such that they show up in the user's iCloud Drive folder and are synced across devices. I can see my app's folder in the Files app under iCloud Drive.

If I go into the iOS Settings app and change the "Document Storage" setting for my app from "iCloud Drive" to "On My iPhone", I would expect my app to start using the "On My iPhone" location in the Files app instead. When I do so, I can see a new folder for my app appear in the "On My iPhone" section in the Files app, so that seems to confirm my assumption.

I am checking ubiquityIdentityToken and url(forUbiquityContainerIdentifier:) and these don't change: they still return the details of the iCloud directory even when my app is switched to "On My iPhone". As such, my app continues reading and writing files to the iCloud Drive directory instead of the On My iPhone directory.

I'm not sure how I am supposed to honour this setting. The documentation around ubiquityIdentityToken suggests it should return nil, but is this just for when the user is signed out of iCloud rather than just having changed the Document Storage setting for my app?

Or am I misunderstanding what the Document Storage setting is completely?

Document Storage setting for Pages:

After more research I think I understand.

The "Document Storage" setting is nothing to do with the ubiquity container. It's a setting that only shows for apps that have UISupportsDocumentBrowser (Supports Document Browser) set to true in the Info.plist.

This is not well documented as far as I can tell. I pieced this together from the existence of NSFileProviderManager.documentStorageURL and Understanding iOS: What Does 'Document Storage' Setting Mean for Apps?.

I must have added this entry accidentally, thinking it was necessary for my app, but my app doesn't use the document browser. It confused me when a folder was created for my app in iCloud Drive or On My iPhone depending on what this setting was, but because I was using FileManager's ubiquity APIs it was only saving to iCloud Drive.

The correct way for users to selectively turn iCloud on/off for each app is in the Settings app by navigating to Apple ID → iCloud → APPS USING ICLOUD: Show All → and toggling the switch for the app.