Solar2D 文档 — 插件 | iCloud - Solar2D 游戏引擎

概述

iCloud 插件允许访问 Apple 的 iCloud API，并提供工具在用户的设备之间同步数据。

重要

虽然 iCloud 是 iOS 操作系统的一部分，但用户可能没有登录他们的 iCloud 帐户，或者用户可能选择完全禁用 iCloud。因此，即使未启用 iCloud，用户也能与您的应用交互非常重要。

iCloud 存储/共享

iCloud 提供三种不同的数据存储和共享方式

键值存储

**键值存储**(KVS) 是 iCloud 最容易使用的方面，Apple 建议所有应用都应该利用其实现。本质上，它提供了将数据（值）与键（字符串）关联的功能。这些键值对会在用户所有启用 iCloud 的设备之间同步，允许您使用关联的键检索特定数据。

请注意，KVS 的存储空间非常有限。您可以声明最多 1024 个键，所有值的总大小应小于 1 MB。键应少于 64 个符号（字节）。您可以选择将所有数据存储在一个键中，并使用大型数据集，或者将数据分成多个键 - 只需注意，如果一个键值键值对被修改，它将作为一个整体实体进行同步，因此将数据分成多个键可以提高同步速度并最大限度地减少蜂窝数据的使用。

iCloud 中的文档

**iCloud 中的文档**旨在跨用户的启用 iCloud 的设备同步文件，iCloud 插件提供了读取和写入这些文件的 API。

请注意，iCloud 中文档的存储空间限制为用户的 iCloud Drive 空间。另请注意，用户可以通过 iOS 设置屏幕手动删除特定的存储文件，因此您的应用不应假设 iCloud 存储中存在某个文件。

CloudKit

**CloudKit** 是 iCloud 框架的最新成员。这是一个分布式数据库，您可以在其中私有或公开地存储记录。私有记录只能由创建它们的用户访问，而公共记录在用户之间共享。本质上，CloudKit 是一个非常强大的工具，用于存储数据以及在用户之间共享数据。

请注意，CloudKit 存储空间“随用户扩展”，但一般情况下，除非有专门的大量数据库使用需求，否则您的应用不应超过免费存储限制。

项目设置

要使用此插件，请在 `build.settings` 的 `plugins` 表中添加一个条目。添加后，构建服务器将在构建阶段集成该插件。

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

启用 iCloud

使用 iCloud 需要在应用的配置文件中进行某些设置。您**不能**将通配符 App ID 与 iCloud 一起使用，因此您必须配置并使用显式 App ID（指南）。要为您的应用配置 iCloud，请按照以下基本步骤操作

登录 Apple Developer 门户，进入**会员中心**，然后导航到证书、标识符和配置文件控制面板。
在所需平台下点击**标识符**。您应该会在那里看到列出的所有应用。选择要添加 iCloud 支持的应用，然后在服务列表下方点击**编辑**。
在服务列表中，选中**iCloud**复选框。
生成（或重新生成）所有包含所选 App ID 的配置文件。有关此过程的详细信息，请参阅创建配置文件部分此处。

iCloud 容器

除了上述步骤之外，如果要使用 iCloud 中的文档或 CloudKit，则必须将**iCloud 容器**与应用关联，如下所示

在 Apple Developer 门户中，从上述步骤到达的同一部分，选择包含 CloudKit 支持在**iCloud**行中。
在同一行中，点击**编辑**按钮。您可以在此处创建新的 iCloud 容器或将现有的 iCloud 容器与应用关联。如果您是第一次创建 iCloud 容器，请注意，您需要先创建/注册它，然后再重复此步骤以将新容器与应用和 iCloud 关联。
生成（或重新生成）所有包含所选 App ID 的配置文件。有关此过程的详细信息，请参阅创建配置文件部分此处。

共享数据

对于 iCloud 中的文档和 CloudKit，您可以在多个应用之间共享数据。这是通过 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 将专用 iCloud 容器与每个应用关联来实现的，如上所述，通过 Apple Developer 门户。从那时起，Solar2D 将在构建过程中自动为每个将 `iCloud` 设置为 `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,
    },
}

如果仅使用 KVS，则可以通过在 `build.settings` 的 `iphone` 表中指定 `kvstore-identifier` 来在不同的应用之间共享数据。这将覆盖默认的布尔值 `true`，该值仅为用户启用 iCloud 的设备上的同一应用启用 KVS。

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

函数

键值存储

事件

键值存储

类型

CloudKit

CloudKitRecord

示例

键值存储

-- 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 )

类型	库
修订版	版本 2024.3703
关键词	iCloud，同步，存储
平台	iOS、tvOS、macOS

iCloud.*

概述

iCloud 存储/共享

键值存储

iCloud 中的文档

CloudKit

项目设置

启用 iCloud

iCloud 容器

共享数据

函数

事件

类型

示例

键值存储