Tutorial: Using iCloud Key-Value Storage

18 December 2015

Tutorial: Using iCloud Key-Value Storage

Today, we are pleased to introduce the iCloud plugin, available as of Daily Build 2015.2795. This plugin is currently in “beta” while we finish polishing the documentation and give it further rounds of testing.

In this tutorial, we’ll explore Key-Value Storage or KVS (we will address “Documents in iCloud” and “CloudKit” in other tutorials).

Overview

KVS allows you to store “key-value” pairs in Apple’s iCloud using a very simple set of API calls. With KVS you can store strings, numbers, and tables of data using a simple iCloud.set() call.

Before you dive in, there are some KVS limits to be aware of:

• You can use 1 megabyte of storage at most.
• You can have up to 1024 total keys.
• Keys can be up to 64 bytes long and include unicode characters. Unicode characters take up more space than alpha-numeric characters. You can use up to 63 alpha-numeric characters.

Depending on your requirements, you can use one key with a lot of tabled data, or you can use many keys with separate bits of data. Keep in mind that when you sync one key with a lot of data, you’re changing a lot at once. Also remember that data is generally synced over both WiFi and Cellular, so syncing keys with large amounts of data can be time consuming, even when only one small part of that data changed.

Provisioning your app

Before you can deploy your iCloud-capable app to the store, your provisioning profile must have iCloud enabled. This is done in the Member Center of the Apple Developer portal under Certificates, Identifiers & Profiles. Once there, click Identifiers → App IDs. Click on the desired app (it can not use a wildcard App ID) and scroll down to the iCloud row. There, check the box to enable iCloud. Next, click the radio button to enable CloudKit, then click on the Edit button.

On the next screen, check the box for your app’s bundle ID:

Click Continue and then Done. At this point, you will need to regenerate your provisioning profile (see the Creating Provisioning Profiles section here).

Updating build.settings

To include the iCloud plugin, you must add it to your build.settings file:

In addition, you must edit the block for iphone and/or tvos:

Corona Enterprise

For Enterprise builds, you have to include the Corona_plugin_iCloud.framework which is located in the Enterprise plugins download tab on the Daily Builds page.

In addition, there are some Xcode settings required for enabling iCloud, located on the project’s Capabilities screen. Here, ensure that iCloud is enabled and that Key-value storage is checked.

Saving values to iCloud

In any scene or Lua file where you need to access iCloud services, you must require the plugin:

Then, when you’re ready to save some data, simply call iCloud.set() with a key and value, for example:

This will set a key named playMusic with the value of "on".

Accepted values

KVS allows you to store the following data types:

• numbers
• strings
• tables

While you cannot store booleans this way, they can be part of table data. Alternatively, you can simply use numbers like 1 or 0 to indicate true or false, or just store the strings "true" or "false", but you will need to convert them back to boolean values before you use them as Lua booleans.

Note that if you choose to store a table, it must contain only key-value pairs. Tables with numeric keys (arrays) can not be stored directly as tables. In other words, the following array will produce an error if you attempt to store it to KVS:

If you have an array to store, one option is to use json.encode() on the table and save it as string data, then use json.decode() on the string to convert it back into a table after you retrieve it from iCloud.

Retrieving data

To get data back from KVS, simply call the iCloud.get() method:

If the value can’t be found, nil will be returned. It’s that simple!

Deleting data

If you no longer need some data, you can recover used storage by deleting the key from iCloud using the iCloud.delete() method:

Synchronizing data

An important purpose of iCloud is to allow users with multiple devices to share data between them. In other words, if you finish a level in a game on your iPad, you should be able to pick up your iPhone and play the next level. If you load certain saved settings (data) from KVS when the app starts, the app should have the latest data — but what if the app is open at the same time on both devices and changes to the data occur?

One option is to enable a listener function via iCloud.setKVSListener() that will execute when values change, effectively keeping your app up-to-date. Consider this block of code:

See the iCloudKVSEvent documentation for the various values returned as part of the event table.

Conclusion

This tutorial is just the first in respect to storing and sharing data in Apple’s iCloud. To learn more, please refer to the iCloud documentation.

---