安装适用于 iOS、macOS、tvOS 和 watchOS 的 SDK
Overview
Atlas Device SDK for Swift 允许您使用 Swift 或 Objective-C 编程语言来构建 iOS、macOS、tvOS 和 watchOS 应用程序。本页详细介绍了如何在项目中安装此 SDK 并开始使用。
先决条件
在开始之前,请确保您的开发环境满足以下前提条件:
您的项目使用本页 OS 支持部分列出的 Xcode 版本和最低操作系统版本。
您的项目已启用反射。Swift SDK 使用反射来确定模型的属性。您的项目不得设置
SWIFT_REFLECTION_METADATA_LEVEL = none
,否则 SDK 无法看到模型中的属性。如果您的项目未专门为此设置设定一个级别,则默认情况下会启用反射。
安装
您可以使用 SwiftPM
、CocoaPods
或 Carthage
将 Swift SDK 添加到您的项目。
提示
Atlas Device SDK 和 Realm
此 SDK 使用 Realm Core 数据库来实现设备数据持久化。安装 Swift SDK 时,包名称会反映 Realm 命名方式。
指定选项
在realm-swift
包的选项中,我们建议将Dependency Rule
设置为Up to Next Major Version
,并输入 当前Realm Swift SDK版本 。然后,单击Add Package
。
如果使用 CocoaPods 进行安装 ,您需要 CocoaPods1 。10 。1或更高版本。
将 SDK 作为依赖项添加到 Podfile 中
将pod 'Realm', '~>10'
行添加到您的主目标和测试目标中。
如果尚不存在use_frameworks!
行,请同时添加该行。
完成后,您的 Podfile 应如下所示:
# Uncomment the next line to define a global platform for your project # platform :ios, '11.0' target 'MyDeviceSDKProject' do # Comment the next line if you don't want to use dynamic frameworks use_frameworks! # Pods for MyDeviceSDKProject pod 'Realm', '~>10' target 'MyRealmProjectTests' do inherit! :search_paths # Pods for testing pod 'Realm', '~>10' end end
添加use_frameworks!
行(如果尚不存在)。
将pod 'RealmSwift', '~>10'
行添加到您的主目标和测试目标中。
完成后,您的 Podfile 应如下所示:
platform :ios, '12.0' target 'MyDeviceSDKProject' do # Comment the next line if you don't want to use dynamic frameworks use_frameworks! # Pods for MyDeviceSDKProject pod 'RealmSwift', '~>10' end
如果使用 Carthage 进行安装 ,你需要 Carthage0 。33 或更高版本。
下载并解压缩框架
下载 最新版本的 Swift SDK 并解压缩 zip。
提示
如果在 Swift 项目中使用 Objective-C API,我们建议您在项目中同时包含 Realm Swift 和 Realm Objective-C。 在 Swift 文件中,您可以访问 Swift API 和所有必需的包装器。 在 Swift/Objective-C 混合项目中使用 RealmSwift API 是可能的,因为绝大多数 RealmSwift 类型都是直接从 Objective-C 对应项中获取别名的。
导入 SDK
提示
Atlas Device SDK 和 Realm
此 SDK 使用 Realm Core 数据库来实现设备数据持久化。导入 Swift SDK 时,包名称会反映 Realm 命名方式。
在源文件顶部添加以下行以使用此 SDK:
import RealmSwift
应用下载文件大小
此 SDK 应只会使您的应用下载大小增大约 5 到 8 MB。我们分发的版本要大得多,因为它们包含了对 iOS、watchOS 和 tvOS 模拟器、某些调试符号和位码的支持,而所有这些在下载应用时均会被 App Store 自动删除。
故障排除
如果使用这些方法之一来安装此 SDK 后出现构建问题,请参阅我们的故障排除指南以了解有关解决这些问题的信息。
操作系统支持
重要
将 SDK 与 tvOS 搭配使用时,有一些特殊注意事项。请参阅为 tvOS 进行构建以了解更多信息。
Xcode 15
在版本10.50.0中进行了更改: 所需的最低 Xcode 版本为15.1
支持的操作系统 | Realm | Atlas App Services |
---|---|---|
iOS 12.0 + | X | X |
macOS 10.14 + | X | X |
tvOS 12.0 + | X | X |
watchOS 4.0 及更高版本 | X | |
VisionOS 1.0 及更高版本 | X | X |
Xcode 14
在版本10.50.0中进行了更改: 删除了对 Xcode 14的支持。
Swift SDK 版本10.50.0 删除了对 Xcode 14的支持。 对于 v 10.49.3及更早版本,这些 Xcode 14要求适用:
Xcode 版本14 1。 或更高版本。
使用 Xcode 14时,目标为 iOS 11.0或更高版本、macOS 10.13或更高版本、tvOS 11.0或更高版本、watchOS 4.0或更高版本。
Swift 并发支持
Swift SDK 支持 Swift 的并发相关语言功能。有关使用 Swift SDK 并发功能的最佳实践,请参阅以下文档。
异步/等待支持
从 Realm Swift SDK 10.15.0 和 10.16.0 版本开始,很多 Realm API 均支持 Swift“异步/等待”语法。项目必须符合以下要求:
Swift SDK 版本 | Swift 版本要求 | 支持的操作系统 |
---|---|---|
10.25.0 | Swift 5.6 | iOS 13.x |
10.15.0 或 10.16.0 | Swift 5.5 | iOS 15.x |
如果您的应用会在 async/await
上下文中访问 Realm,请使用 @MainActor
来标记此代码,从而避免出现与线程相关的崩溃。
有关 Swift SDK 中异步/等待支持的更多信息,请参阅Swift 并发:Async/Await API。
Actor(角色)支持
Swift SDK 支持使用 actor 隔离的 Realm 实例。有关更多信息,请参阅结合使用 Realm 与 Actor - Swift SDK。
Apple 隐私清单
在版本10.49.3中进行了更改: 将 RealmSwift 构建为动态框架以包含隐私清单。
Apple 要求使用RealmSwift
的应用程序提供隐私清单,其中包含有关 SDK 数据收集和使用实践的详细信息。 向 App Store 提交新应用或应用更新时,必须包含捆绑的清单文件。 有关 Apple 要求的更多详细信息,请参阅 即将发布的第三方 SDK 要求 在 Apple Developer 网站上。
从 Swift SDK 版本 10.46.0 开始,SDK 附带提供了 Realm
和 RealmSwift
的隐私清单。 每个软件包都包含自己的隐私清单,其中包含苹果所需的 API 披露以及使用这些 API 的原因。
您可以在每个包中或 realm-swift
Github存储库中查看隐私清单:
Realm
: https ://github.com/realm/realm-swift/blob/master/Realm/PrivacyInfo.xcprivacyRealmSwift
: https ://github.com/realm/realm-swift/blob/master/RealmSwift/PrivacyInfo.xcprivacy
要将这些清单包含在使用RealmSwift
的构建目标中,您必须将RealmSwift
构建为动态框架。 有关详细信息,请参阅 Swift 包管理器安装说明步骤(可选)将 RealmSwift 构建为动态框架。
Swift SDK 在为 App Store 构建的版本中不包含分析代码。该 SDK 不会自行登录到 Atlas。
如果您编写的应用程序使用任何 App Services 功能,例如,初始化应用程序客户端以:
您可能需要在应用程序的隐私清单中添加额外的披露信息,以详细说明在使用这些 API 时的数据收集和使用实践。
有关更多信息,请参阅 Apple 的 隐私清单文件文档。