iCloud.*

Key-Value Storage

Key-Value Storage (KVS) is the easiest aspect of iCloud to use and Apple recommends that all apps benefit from its implementation. Essentially, it provides the ability to associate data (values) with keys (strings). These key-value pairs are synchronized across all of the user's iCloud-enabled devices, allowing you to retrieve specific data using the associated key.

Note that storage space for KVS is strictly limited. You can declare a maximum of 1024 keys and the total size of all values should be less than 1 MB. Keys should be less than 64 symbols (bytes). You may opt to store all data in a single key with a large set of data or divide the data into multiple keys — simply note that if a key-value pair is modified, it will be synchronized as a whole entity, so separating data across several keys may improve synchronization speed and minimize cellular data usage.

Documents in iCloud

Documents in iCloud is designed to synchronize files across a user's iCloud-enabled devices and the iCloud plugin provides APIs to read and write these files.

Note that the storage space for Documents in iCloud is limited to the user's iCloud Drive space. Also be aware that the user can manually delete specific stored files via the iOS settings screen, so your app should not assume that a certain file exists in iCloud storage.

CloudKit

CloudKit is the most recent addition to the iCloud framework. This is a distributed database where you can store records either privately and publicly. Private records can only be accessed by the user who created them, while public records are shared between users. Essentially, CloudKit is a very powerful tool for storing data as well as sharing data between users.

Note that CloudKit storage space "scales with your users" but, in general practice, your app should not exceed the free storage limit unless there's a dedicated need for extensive database usage.

iCloud Containers

In addition to the steps above, if you want to use Documents in iCloud or CloudKit, you must associate an iCloud Container with the app as follows:

1. In the Apple Developer portal, from the same section reached in the steps above, select Include CloudKit support in the iCloud row.

2. In the same row, click the Edit button. Here you can create a new iCloud Container or associate an existing iCloud Container with the app. If you are creating an iCloud Container for the first time, note that you'll need to create/register it first, then repeat this step to associate the new container with the app and iCloud.

3. Generate (or regenerate) all provisioning profiles that include the selected App ID. For details on this process, please refer to the Creating Provisioning Profiles section here.

Sharing Data

For Documents in iCloud and CloudKit, you can share the data between multiple apps. This is facilitated by associating a dedicated iCloud Container with each app via the Apple Developer portal as outlined in the steps above. From that point, Solar2D will automatically extract the container information during the build process for each platform in which iCloud is set to true:

settings =
{
    iphone =
    {
        iCloud = true,
    },

    tvos =
    {
        -- Optional (only for use with Apple TV and tvOS)
        iCloud = true,
    },

    macos =
    {
        -- Optional (only for use with macOS desktop apps)
        iCloud = true,
    },
}

If using only KVS, you can share data between different apps by specifying a kvstore-identifier in the iphone table of build.settings. This will override the default boolean true which simply enables KVS for the same app on the user's iCloud-enabled devices.

settings =
{
    iphone = 
    {
        --iCloud = true,  -- Default
        iCloud = { ["kvstore-identifier"] = "com.example.shared_KVS" },
    }
}

iCloud.setKVSListener()

iCloud.set()

iCloud.get()

iCloud.delete()

iCloud.identityToken()

iCloud.synchronize()

iCloud.table()

iCloud.docInit()

iCloud.docList()

iCloud.docWrite()

iCloud.docRead()

iCloud.docDelete()

iCloud.docCheck()

iCloud.docDownload()

iCloud.docEvict()

iCloud.docConflicts()

iCloud.docConflictData()

iCloud.docResolve()

iCloud.recordCreate()

iCloud.recordDelete()

iCloud.recordFetch()

iCloud.recordFetchMultiple()

iCloud.recordQuery()

iCloud.recordCreateZone()

iCloud.recordAccountStatus()

iCloudKVSEvent

iCloudDocEvent

iCloudRecordEvent

CloudKitRecord

Key-Value Storage

-- This simple example counts user taps across devices and keeps a
-- synchronized counter in the cloud using Key-Value Storage (KVS)

local iCloud = require( "plugin.iCloud" )

-- Create text object for text readout
local text = display.newText( "iCloud", display.contentCenterX, display.contentCenterY, nil, 20 )

-- Set/reset the text readout
local function setText()
    text.text = tostring( iCloud.get( "taps" ) )
end

-- KVS listener function
local function listenKVS( event )
    setText()
end

-- Set the KVS listener
iCloud.setKVSListener( listenKVS )

-- Set the initial text readout
setText()

-- Tap listener function
local function globalTap( event )
    local tapCount = 1 + ( iCloud.get( "taps" ) or 0 )
    iCloud.set( "taps", tapCount )
    iCloud.synchronize()
    setText()
end

-- Detect taps in Runtime
Runtime:addEventListener( "tap", globalTap )