Docs 菜单
Docs 主页
/ /
Atlas Device SDKs

安装适用于 iOS、macOS、tvOS 和 watchOS 的 SDK

在此页面上

  • Overview
  • 先决条件
  • 安装
  • 导入 SDK
  • 应用下载文件大小
  • 故障排除
  • 操作系统支持
  • Swift 并发支持
  • Apple 隐私清单

Atlas Device SDK for Swift 允许您使用 Swift 或 Objective-C 编程语言来构建 iOS、macOS、tvOS 和 watchOS 应用程序。本页详细介绍了如何在项目中安装此 SDK 并开始使用。

在开始之前,请确保您的开发环境满足以下前提条件:

  • 您的项目使用本页 OS 支持部分列出的 Xcode 版本和最低操作系统版本。

  • 您的项目已启用反射。Swift SDK 使用反射来确定模型的属性。您的项目不得设置 SWIFT_REFLECTION_METADATA_LEVEL = none,否则 SDK 无法看到模型中的属性。如果您的项目未专门为此设置设定一个级别,则默认情况下会启用反射。

您可以使用 SwiftPMCocoaPodsCarthage 将 Swift SDK 添加到您的项目。

提示

Atlas Device SDK 和 Realm

此 SDK 使用 Realm Core 数据库来实现设备数据持久化。安装 Swift SDK 时,包名称会反映 Realm 命名方式。

1

在 Xcode 中,选择 File > Add Packages...

2

将以下内容复制并粘贴到搜索/输入框中。

https://github.com/realm/realm-swift.git
3

realm-swift 包的选项中,我们建议将Dependency Rule 设置为Up to Next Major Version ,并输入 当前Realm Swift SDK版本 。然后,单击Add Package

4

在版本10.49.3中进行了更改: 无需同时添加两者,只需添加一个包。

选择RealmSwiftRealm ,然后单击Add Package

  • 如果您使用 Swift 或 Swift 和Objective-C API,请添加RealmSwift

  • 如果使用Objective-C API,请添加Realm

5

要使用 SDK 提供的隐私清单,请将RealmSwift构建为动态框架。 如果将RealmSwift构建为静态框架,则必须提供自己的隐私清单。

要将RealmSwift构建为动态框架,请执行以下操作:

  1. 在项目 Targets中,选择构建目标。

  2. 转到 General 标签页。

  3. 展开Frameworks and Libraries元素。

  4. 对于RealmSwift框架,将Embed选项从“不嵌入”更改为“嵌入并签名”。

现在,Xcode 会动态构建RealmSwift ,并且可以提供 SDK 提供的隐私清单。

如果使用 CocoaPods 进行安装 ,您需要 CocoaPods1 。10 。1或更高版本。

1

在命令行中,运行pod repo update以确保 CocoaPods 可以访问权限最新的可用Realm版本。

2

如果您还没有项目的 Podfile,请在项目的根目录中运行pod init ,为项目创建项目。 Podfile 允许您指定项目对 CocoaPods 的依赖项。

3

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
4

在命令行中,运行pod install以获取依赖项。

5

CocoaPods 会为您生成一个.xcworkspace文件。 此文件配置了所有依赖项。 从现在开始,打开此文件(而不是.xcodeproj文件)来处理您的项目。

如果使用 Carthage 进行安装 ,你需要 Carthage0 。33 或更高版本。

1

通过将github "realm/realm-swift"行附加到您的 Cartfile 中,将 SDK 添加为依赖项。

您可以通过在项目目录中运行以下命令来创建 Cartfile 或将其追加到现有文件中:

echo 'github "realm/realm-swift"' >> Cartfile
2

在命令行中,运行carthage update --use-xcframeworks以获取依赖项。

3

Carthage 将构建的依赖项放在Carthage/Build目录中。

在 Xcode 中打开项目的xcodeproj文件。 Go “项目导航器”面板,然后单击应用程序名称以打开项目设置编辑器。 选择General标签页。

在 Finder 中,打开Carthage/Build/目录。 将该目录中找到的RealmSwift.xcframeworkRealm.xcframework文件拖动到项目的General设置的Frameworks, Libraries, and Embedded Content部分。

将 xcframework 文件拖到 Xcode项目中。
点击放大
1

下载 最新版本的 Swift SDK 并解压缩 zip。

2

Realm.xcframeworkRealmSwift.xcframework (如果使用)拖动到 Xcode项目的文件导航器。 选择Copy items if needed复选框并按Finish

提示

如果在 Swift 项目中使用 Objective-C API,我们建议您在项目中同时包含 Realm Swift 和 Realm Objective-C。 在 Swift 文件中,您可以访问 Swift API 和所有必需的包装器。 在 Swift/Objective-C 混合项目中使用 RealmSwift API 是可能的,因为绝大多数 RealmSwift 类型都是直接从 Objective-C 对应项中获取别名的。

提示

Atlas Device SDK 和 Realm

此 SDK 使用 Realm Core 数据库来实现设备数据持久化。导入 Swift SDK 时,包名称会反映 Realm 命名方式。

在源文件顶部添加以下行以使用此 SDK:

#include <Realm/Realm.h>
import RealmSwift

此 SDK 应只会使您的应用下载大小增大约 5 到 8 MB。我们分发的版本要大得多,因为它们包含了对 iOS、watchOS 和 tvOS 模拟器、某些调试符号和位码的支持,而所有这些在下载应用时均会被 App Store 自动删除。

如果使用这些方法之一来安装此 SDK 后出现构建问题,请参阅我们的故障排除指南以了解有关解决这些问题的信息。

重要

将 SDK 与 tvOS 搭配使用时,有一些特殊注意事项。请参阅为 tvOS 进行构建以了解更多信息。

在版本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

在版本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 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。

Swift SDK 支持使用 actor 隔离的 Realm 实例。有关更多信息,请参阅结合使用 Realm 与 Actor - Swift SDK。

在版本10.49.3中进行了更改: 将 RealmSwift 构建为动态框架以包含隐私清单。

Apple 要求使用RealmSwift的应用程序提供隐私清单,其中包含有关 SDK 数据收集和使用实践的详细信息。 向 App Store 提交新应用或应用更新时,必须包含捆绑的清单文件。 有关 Apple 要求的更多详细信息,请参阅 即将发布的第三方 SDK 要求 在 Apple Developer 网站上。

从 Swift SDK 版本 10.46.0 开始,SDK 附带提供了 RealmRealmSwift 的隐私清单。 每个软件包都包含自己的隐私清单,其中包含苹果所需的 API 披露以及使用这些 API 的原因。

您可以在每个包中或 realm-swift Github存储库中查看隐私清单:

要将这些清单包含在使用RealmSwift的构建目标中,您必须将RealmSwift构建为动态框架。 有关详细信息,请参阅 Swift 包管理器安装说明步骤(可选)将 RealmSwift 构建为动态框架

Swift SDK 在为 App Store 构建的版本中不包含分析代码。该 SDK 不会自行登录到 Atlas。

如果您编写的应用程序使用任何 App Services 功能,例如,初始化应用程序客户端以:

您可能需要在应用程序的隐私清单中添加额外的披露信息,以详细说明在使用这些 API 时的数据收集和使用实践。

有关更多信息,请参阅 Apple 的 隐私清单文件文档。

来年

欢迎使用 Atlas Device SDK 文档