Box Preview SDK

注意

Objective-C（v3.0.0之前）版本的Box iOS Preview SDK已从主分支移动到objective-c-maintenance分支。从现在开始，主分支将包含从v3.0.0开始的iOS Preview SDK的Swift版本。

Box Preview SDK

此SDK使您轻松在iOS应用程序中展示Box文件。

• Box Preview SDK
• 注意
  • Box Preview SDK
  • 要求
  • 安装SDK
    • Carthage
    • CocoaPods
    • Swift包管理器
      • 将BoxPreviewSDK导入到项目中
      • 将BoxPreviewSDK作为依赖项添加
  • 入门
  • 示例应用配置
  • 使用示例应用
  • 打开PDF文件
  • 打开图像文件
  • 未来改进
  • 版本定义
    • 候选发布版 (RC)
    • 当前发布版
    • 长期支持
    • 支持阶段
      • 活跃
      • 维护
      • 停用
  • 版权和许可

需求

• iOS 11.0+
• Xcode 10.0+

安装 SDK

Carthage

步骤 1：将以下内容添加到您的 Cartfile

git "https://github.com/box/box-ios-sdk.git" ~> 5.0
git "https://github.com/box/box-ios-preview-sdk.git" ~> 3.0

步骤 2：更新依赖项

$ carthage update --use-xcframeworks --platform iOS

步骤 3：Carthage/Build 文件夹中的 xcframework 已经在 BoxPreviewSDKSampleApp Xcode 项目中引用。

有关更详细的说明，请参阅 Carthage 的官方文档。

CocoaPods

步骤 1：将以下内容添加到您的 Podfile

pod 'BoxPreviewSDK', '~> 3.0'

步骤 2：在包含 Podfile 的目录中运行以下命令以安装 pod

$ pod install

有关更详细的说明，请参阅 CocoaPods 的官方文档。

Swift Package Manager

导入 BoxPreviewSDK 到项目中

步骤 1：点击 Xcode 项目的文件

步骤 2：点击 Swift Packages，然后点击加号以添加一个包

步骤 3：输入以下仓库 URL https://github.com/box/box-ios-preview-sdk.git 并点击下一步

步骤 4：保持默认设置以获取最新版本，并点击下一步完成导入

整个过程应如下所示

添加 BoxPreviewSDK 作为依赖

有关详细说明，请参阅SPM 的官方文档。

开始使用

要开始使用 SDK，您需要从 Box 开发者控制台 获取您应用的 Client ID 和 Client Secret。如果您熟悉 Box 内容 SDK 中的 OAuth2 示例应用 的入门，您会发现这个过程非常相似。

示例应用配置

一个使用 OAuth2 验证的示例应用可以在以下仓库中找到 此处。此应用演示了如何使用 Box Preview SDK 通过 OAuth2 验证进行调用，并且可以直接运行，通过输入您的凭据进行登录。

要执行示例应用

步骤 1：运行 carthage

$ cd BoxPreviewSDKSampleApp
$ carthage update --use-xcframeworks --platform iOS

步骤 2：打开 Xcode 项目文件

$ open OAuth2SampleApp.xcodeproj

步骤 3：输入您的客户端 ID 和客户端密钥

首先，从 Box 开发者控制台 中找到您 OAuth2 应用程序的客户端 ID 和密钥。然后，将这些值添加到 Constants.swift 文件中的示例应用中

static let clientId = "YOUR CLIENT ID GOES HERE"
static let clientSecret = "YOUR CLIENT SECRET GOES HERE"

步骤 4：设置重定向 URL

使用上一步中相同的客户端ID，在Box开发者控制台中将应用程序的重定向URL设置为boxsdk-<<YOUR CLIENT ID>>://boxsdkoauth2redirect，其中<<YOUR CLIENT ID>>将被替换为您的客户端ID。例如，如果您的客户端ID为vvxff7v61xi7gqveejo8jh9d2z9xhox5，则重定向URL应为boxsdk-vvxff7v61xi7gqveejo8jh9d2z9xhox5://boxsdkoauth2redirect

第5步：在应用程序中插入客户端ID以接收重定向

在示例应用程序中打开Info.plist文件，并在此处找到密钥：URL Types --> 项0 --> URL Schemes --> 项0。使用上一步中的相同客户端ID，将项0的值设置为boxsdk-<<YOUR CLIENT ID>>，其中<<YOUR CLIENT ID>>将被替换为您的客户端ID。例如，如果您的客户端ID为vvxff7v61xi7gqveejo8jh9d2z9xhox5，重定向URL应为boxsdk-vvxff7v61xi7gqveejo8jh9d2z9xhox5

第6步：运行示例应用程序

使用示例应用程序

应用程序将打开并提示开始OAuth2.0身份验证。点击“OAuth2.0身份验证”以继续。

在下一屏幕上，点击“登录”。

弹出一个iOS系统对话框，询问是否同意打开URL进行身份验证。点击“继续”以继续。

加载Box登录页面。输入您的凭据并点击“授权”以继续。

确认屏幕显示了在Box开发者控制台中定义的应用程序名称及配置的权限。点击“授予Box访问权限”以授予您的应用程序对Box账户的访问权限。

下一屏幕显示账户根目录下的所有文件。如果您在屏幕上看不到任何文件，请检查您是否在Box账户的根目录中保存了文件。注意，为了简化，本示例应用程序中没有显示文件夹。从该屏幕，您可以点击返回箭头以注销，或点击列表中的文件名称以下载它并显示它。当前应用程序支持PDF和所有iOS支持的图像文件。

打开PDF文件

在文件列表中点击一个PDF文件。进度条指示文件从Box检索时的下载进度。当进度达到100%时，文档将显示。

顶部工具栏包含返回文件列表的箭头、文件名、当前页数、大纲视图按钮（如果文档包含大纲）和画廊视图按钮。可以通过点击文档来切换工具栏。

大纲视图允许您查看文档的分级结构，并提供快速导航到特定页面。

画廊视图显示每一页的大缩略图，并提供快速导航到特定页面。

该文档支持左右滑动手势导航每页一次，捏合缩放手势和拖拽。

对于包含多页的PDF文件，屏幕底部的缩略图导航栏允许快速浏览整个文档。

打开图片文件

在文件列表中轻触图片文件（当前支持JPG、JPEG、PNG文件）。进度条显示文件从Box检索出来的下载进度。当进度达到100%时，图片将被显示。

顶部工具栏包含一个返回文件列表和文件名的箭头。可以通过轻触图片来切换工具栏。

图片支持缩放手势和滚动。

Preview SDK支持一次打开多个图片，但在示例应用中尚未暴露。您可以自行试验此功能，通过调用BoxPreviewSDK.openImageFiles(fileIds:selectedId:delegate:allowedAction:displayThumbnails)进行。

• 加载屏幕底部的缩略图导航栏中的所有图片
• 支持左右滑动手势进行图片浏览
• 相册视图

未来增强

您可以在Box Preview SDK的未来的更新中期待以下增强

• 支持更多文件类型
• 本地文件缓存
• 从上次查看的文件启动应用
• 更多功能！

发布定义

从2019年10月19日开始，Box Swift SDK for iOS将可供公众使用。这意味着所有Box开发者都能够使用SDK来在Box上构建原生的iOS应用程序。在未来几个月中，我们将根据客户反馈对SDK进行频繁更新，此文档旨在设定以下预期

1. 在接下来的几个月中您将看到的各种发布类型，它们的含义以及如何识别它们
2. 每种发布类型的支持政策

在未来几个月内，Box Swift SDK for iOS的发布将属于以下类型之一

• 候选发布版 (RC)
• 当前发布版
• 长期支持

发布候选版（RC）

自10月19日起，SDK的初始版本为候选版（RC）。这意味着：(1) 核心功能已存在并通过测试，(2) 从此点开始，新增功能将被视为基于客户反馈的改进或增强。RC 版本通常会更多（每几周一次），随后是当前版本。如果您计划使用 RC 版本，我们建议

• 不要将其用于生产作业（如果不可避免，我们建议在准备好的情况下升级到当前版本。）
• 制定一个计划，以确保您的应用程序始终处于最新的 RC 版本（因为一旦发布新的 RC 版本，旧的 RC 版本就不再受支持）

此外，RC 版本可能包含与前一个版本相比的破坏性变化，我们建议开发者在采用新 RC 版本之前对其应用程序进行充分测试。

发布 RC 版本背后的想法是快速迭代 SDK（错误修复、功能调整等），使其达到生产就绪状态，通常我们预计 SDK 在 RC 阶段不会超过一个月。

RC 版本支持

RC 版本

• 发布时被视为 活跃状态
• 当下一个版本变为活跃状态时，转向 结束寿命

当前版本

当前版本比候选版更加稳定，因此我们预计当前版本的发布周期将更少。我们通常预计大约每 3 个月刷新一次当前版本（可能更短或更长，具体取决于发布内容的紧迫性）。

新当前版本通常包含新功能、错误修复，可能包含破坏性更改。我们将突出显示每个当前版本发布说明部分中（如果有）的所有破坏性更改，并建议开发者在将其用于生产使用之前对其应用程序进行充分测试。

当前版本位于我们的 SDK 开发前沿，适用于正在积极开发并希望获得最新和最佳功能的客户。当前版本不适用于长期使用，并且只有在下一个版本可用后，将只提供足够支持，以允许平稳过渡到新版本。

当前版本支持

当前版本

• 发布时被视为 活跃状态
• 在成为活动状态3个月后，或当下一个版本成为活动状态，以较晚者为准，过渡到维护状态。
• 在成为活动状态6个月后，或当下一个版本成为活动状态3个月后，以较晚者为准，达到生命周期的结束。

长期支持

长期支持（LTS）版本是我们计划保证其在较长一段时间内兼容性的一种版本。SDK的公共接口不应该发生变化，以破坏客户的程序，并且该版本应在其整个生命周期中继续至少接收错误修复。我们预计每18至24个月刷新一次长期发布版本。

由于上述原因，我们建议所有不打算频繁更新（大约每6至12个月）其应用程序的开发人员只使用SDK的长期发布版本。

长期发布支持

长期发布

• 发布后被视为活动状态。
• 在成为活动状态1年后，或当下一个版本成为活动状态，以较晚者为准，过渡到维护状态。
• 在成为活动状态2年后，或当下一个LTS版本成为活动状态1年后，以较晚者为准，达到生命周期的结束。

支持阶段

活动状态

一旦一个版本被认为可以发布，就会切出新版本，并进入活动状态。然而，SDK可能会添加新功能，包括对新API端点的支持。

维护

经过一段时间，版本的开发不再活跃，但客户可能仍然依赖于它。此时，我们考虑该版本处于维护阶段；通常，只有bug修复会被考虑包含在新版本中。当然，根据客户需求，我们可能会选择包含新功能，但通常客户应预计SDK功能集在其生命周期的其余部分将基本保持不变。

生命周期结束

Box不再支持某个版本后，它将进入生命周期结束（EOL）状态，客户不应期望有任何其他更改。如果客户想获得支持，必须升级到较新的版本。

版权和授权

版权2019 Box，Inc。保留所有权利。

根据Apache许可证2.0版本（“许可证”）授权；除非根据适用法律要求或经书面同意，否则不得使用此文件，除非符合许可证。您可以在以下位置获取许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则按照“原样”及根据许可证在本地上分发软件，不提供任何明示或默示的保证或条件。有关许可证中的具体语言，请参阅许可证，以了解许可权限和限制。