iCloud.*

Type Library
Revision Release 2022.3683
Keywords iCloud, sync, storage
Platforms iOS, tvOS, macOS

Overview

The iCloud plugin enables access to Apple's iCloud APIs and provides instruments to synchronize data across a user's devices.

Important

While iCloud is part of the iOS operating system, users may not log in with their iCloud account, or a user may choose to disable iCloud entirely. Thus, it's important that users can interact with your app even if iCloud is not enabled.

iCloud Storage/Sharing

iCloud provides three distinct ways of storing and sharing data:

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.

Project Settings

To use this plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

settings =
{
    plugins =
    {
        ["plugin.iCloud"] =
        {
            publisherId = "com.coronalabs"
        },
    },
}

Enabling iCloud

Using iCloud requires certain settings within your app's provisioning configuration. You can not use a wildcard App ID with iCloud, so you must configure and use an explicit one (guide). To configure iCloud with your app, follow these basic steps:

  1. Log into the Apple Developer portal, enter the Member Center, and navigate to the Certificates, Identifiers & Profiles dashboard.

  2. Click on Identifiers under the desired platform. There you should see all of your apps listed. Select the app for which you want to add iCloud support and, below the list of services, click Edit.

  3. In the list of services, select the iCloud checkbox.

  4. 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.

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" },
    }
}

Functions

Key-Value Storage

iCloud.table()

Documents in iCloud

Events

Key-Value Storage

iCloudKVSEvent

Documents in iCloud

iCloudDocEvent

CloudKit

Types

CloudKit

Examples

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 )