tvOS Resources and Data Storage in Xamarin

  • Article

This article covers working with resources and persistent data storage in a Xamarin.tvOS app.

tvOS Resource Limitations

Unlike iOS devices, the new Apple TV provides extremely limited persistent, local storage for tvOS apps or data. For very small items (such as user preferences), your tvOS app still has access to NSUserDefaults with a limit of 500 KB of data. However, if your Xamarin.tvOS app needs to persist larger amounts of information, it must store and retrieve that data from iCloud.

Additionally, tvOS limits the size of an Apple TV app to 200MB. If your app requires resources beyond this size, they will need to be packaged and loaded using On-Demand Resources (up to an additional 2GB). Given these limitations, it is critical that you correctly time the downloading of additional assets to provide the best experience for your app's users. For more information, please see Apple's On-Demand Resources Guide.

Non-Persistent Downloads

Each tvOS app is provided a temporary cache directory that its additional resources and assets are downloaded to. This directory will be preserved as long as the app is still running. However, as the Apple TV needs to free up room for other apps or system usage, this cache can be deleted.

As a result, your app cannot rely on previously downloaded content being available the next time it is launched. Your Xamarin.tvOS app should always check for the existence of required resources and download them as required.

Important

While you have the ability to download other assets and resources as required, Apple warns against consuming all of the space in your app's cache, as it can lead to unpredictable results.

Managing Resources

As stated above, because of the limited, non-persistent storage of information available to tvOS apps, these restrictions require careful planning to create a great user experience for your Xamarin.tvOS app.

iCloud Data Storage

Because storage on the Apple TV is limited, not only is there very limited persistent, local storage, your app has no guarantee that any information it previously downloaded will be available the next time it is run.

As a result, your Xamarin.tvOS app must store any user data in an iCloud Data Store. Apple provides two iCloud-based data storage options for your tvOS apps:

  • iCloud Key-Value Storage (KVS) - For small pieces of information (less than 1MB) that your app might require (like user preferences), you can use iCloud KVS Storage. iCloud KVS data is automatically synced to the cloud and all of the user's devices running the same app. For more information please see the Key-Value Storage section of our Introduction to iCloud document or Apple's Designing for Key-Value Data in iCloud documentation.
  • CloudKit - For the storage of larger pieces of information (greater than 1MB), use Apple's CloudKit Framework. Unlike iCloud KVS Storage, CloudKit data can be shared amongst all the users of your app (as well as being private to a single user). Form more information, please see our Introduction to CloudKit documentation or Apple's CloudKit Quick Start.

Important

Apple provides tools to help developers properly handle the European Union's General Data Protection Regulation (GDPR).

On-Demand Resources

On-Demand Resources provide app content and assets (separate from the app bundle), that are hosted on the App Store and downloaded as required by your app. Up to an additional 2GB of data can be served using On-Demand Resources. They enable the initial app download to be smaller (tvOS apps are limited to a maximum of 200MB), while still providing rich assets as required.

When a tvOS app requests On-Demand Resources, the system will automatically manage the downloading and storage of this content to the app's cache directory. Your app must wait for this content to be downloaded and made available before it can continue.

These resources may continue to be cached on the Apple TV throughout multiple launches of your app, thus speeding launch cycle. However, your app cannot rely on any previously downloaded content being available the next time it is launched. See the Non-Persistent Downloads section above for more details.

You use Xcode to create bundles of related content (such as all assets for game level 2) associated with a give Resource Tag. Later your app will request On-Demand Resource by specifying this Resource Tag. Your app should present a UI to the user stating that content is being downloaded. For more information, please see Apple's On-Demand Resources Guide.

Important

Care should be taken to strike the right balance between the number of times the app has to download On-Demand Resources and the size of the individual downloads. User may become frustrated with your app if gameplay is interrupted constantly to download new content or if a single download takes too much time.

Summary

This article has covered the size, resource and data storage limitations placed on a Xamarin.tvOS app by the tvOS system. It has presented options to work around these limitations and suggestions to create a great user experience for your app.