Contentstack

Contentstack Swift SDK

Contentstack CI

Contentstack 是一个 API 优先的无头 CMS。开发者可以使用它以自己喜欢的语言构建强大的跨平台应用程序。构建您的应用程序前端，剩下的事情交给 Contentstack 来处理。了解更多。

Contentstack 提供 iOS SDK 以在 iOS 平台上构建应用程序。下面是详细指南和有用的资源，帮助您开始使用我们的 iOS SDK。

先决条件

最新的 Xcode 和 Mac OS X

设置和安装

要在 iOS 平台上使用此 SDK，您需要按照以下步骤安装 SDK。

CocoaPods
  1. 将以下行添加到您的 Podfile
  2. pod 'ContentstackSwift'
  3. 运行 pod install，您现在应该拥有最新的 Contentstack 版本。
导入头文件/模块
import ContentstackSwift

使用 Contentstack 的关键概念

堆栈 (Stack)

堆栈就像一个容器，用于保存您应用程序的内容。 了解更多关于 堆栈 的信息。

内容类型 (Content Type)

内容类型允许您定义页面或数字资产部分的结构或蓝图。它是一个类似表单的页面，为内容管理员提供了一个输入和上传内容的界面。了解更多。

条目 (Entry)

条目是使用已定义的内容类型创建的实际内容。 了解更多关于 条目 的信息。

资源 (Asset)

资源是指上传到 Contentstack 的所有媒体文件（图像、视频、PDF、音频文件等）。 这些文件可以用于多个条目。 了解更多关于 资源 的信息。

环境 (Environment)

发布环境对应于一个或多个部署服务器或内容交付目的地，条目需要发布到这些地方。 了解如何使用 环境。

Contentstack iOS SDK：5 分钟快速入门

初始化您的 SDK

要在您的应用程序中开始使用 SDK，您需要通过提供与它们关联的所需密钥和值来初始化堆栈。

  let stack:Stack = Contentstack.stack(apiKey: API_KEY, deliveryToken: DELIVERY_TOKEN, environment: ENVIRONMENT)

要获取上面提到的 API 凭据，您需要登录到您的 Contentstack 帐户，然后在顶部面板导航栏中，转到设置 -> 堆栈以查看您的 API 密钥和交付令牌。

返回的堆栈对象是一个 Contentstack 客户端对象，可用于初始化不同的模块并针对我们的 内容交付 API 进行查询。 以下部分解释了每个模块的初始化过程。

从您的堆栈查询内容

要获取内容类型的所有条目，请使用以下查询

let stack = Contentstack.stack(apiKey: apiKey,
            deliveryToken: deliveryToken,
            environment: environment)

stack.contentType(uid: contentTypeUID).entry().query()
   .find { (result: Result<ContentstackResponse<EntryModel>, Error>, response: ResponseType) in
     switch result {
     case .success(let contentstackResponse):
         // Contentstack response with AssetModel array in items.
     case .failure(let error):
         //Error Message
     }
 }

要从内容类型中获取特定条目，请使用以下查询

 let stack = Contentstack.stack(apiKey: apiKey,
             deliveryToken: deliveryToken,
             environment: environment)

 stack.contentType(uid: contentTypeUID).entry(uid: UID)
 .fetch { (result: Result<EntryModel, Error>, response: ResponseType) in
    switch result {
    case .success(let model):
         //Model retrive from API
    case .failure(let error):
         //Error Message
    }
 }

高级查询

您可以使用我们的 iOS API 参考查询内容类型、条目、资源等。

iOS API 参考文档

处理图像

我们引入了图像交付 API，允许您检索图像，然后对其进行操作和优化，以用于您的数字资产。 它允许您执行许多其他操作，例如裁剪、修剪、调整大小、旋转、叠加等。

例如，如果您想裁剪图像（宽度为 300，高度为 400），您只需在图像 URL 的末尾附加查询参数，例如，https://images.contentstack.io/v3/assets/uid_136download?crop=300,400。 您可以使用更多参数来处理图像。

阅读图像交付 API 文档.

您也可以在此 SDK 中使用图像交付 API 函数。 以下是其在 SDK 中的一些用法示例。

/* set the image quality to 100 */
let quality: UInt = 100
let imageTransform = ImageTransform().qualiy(quality)
let url = try imageURL.url(with: imageTransform)

/* resize the image by specifying width and height */
let width: UInt = 100
let height: UInt = 100
let urlboth = try imageURL
    .url(with: makeImageTransformSUT()
        .resize(
            Resize(size:
                Size(width: width, height: height)
        )
    )
 )

iOS API 参考文档

将 Sync API 与 iOS SDK 结合使用

Sync API 负责将您的 Contentstack 数据与您的应用程序同步，并通过提供增量更新来确保数据始终是最新的。 Contentstack 的 iOS SDK 支持 Sync API，您可以使用它来构建强大的应用程序。 请阅读以了解如何将 Sync API 与 Contentstack iOS SDK 结合使用。

初始同步

初始同步过程会对您的应用程序数据执行完整同步。 它会返回响应中指定堆栈的所有已发布的条目和资源。

要启动初始同步过程，请使用 syncStack 方法。

let stack = Contentstack.stack(apiKey: apiKey,
             deliveryToken: deliveryToken,
             environment: environment)

stack.sync(then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})

响应还包含一个同步令牌，您需要存储该令牌，因为此令牌用于稍后获取后续增量更新，如下面的后续同步部分所示。

您还可以通过使用 高级同步查询 在初始同步中获取自定义结果。

同步分页

如果初始同步（或后续同步）的结果包含超过 100 条记录，则响应将分页。 它在响应中提供分页令牌。 但是，您不必手动使用分页令牌来获取下一批； SDK 会自动执行此操作，直到同步完成。

如果您只想获取选定的批次，可以使用分页令牌。 如果同步过程在中间中断（由于网络问题等），则此功能特别有用。 在这种情况下，可以使用此令牌从中断的地方重新启动同步过程。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(paginationToken: paginationToken)

stack.sync(syncStack, then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})

后续同步

您可以使用同步令牌（在初始同步后收到）来下次获取更新的内容。 同步令牌仅获取在上次同步后添加的内容，以及已删除或更新的内容的详细信息。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(syncToken: syncToken)

stack.sync(syncStack, then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})

高级同步查询

您可以使用高级同步查询来获取经过筛选的结果。 让我们详细看看它们。

从特定日期开始的初始同步

要从特定日期初始化同步，您可以使用 sync 参数指定日期。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(syncToken: syncToken)

stack.sync(syncTypes: [.startFrom(date)], then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})
特定内容类型的初始同步

您还可以使用仅特定内容类型的条目初始化同步。 为此，请使用 syncOnly 并将内容类型 UID 指定为其值。

但是，如果您这样做，后续同步将仅包括指定内容类型的条目。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(syncToken: syncToken)

stack.sync(syncTypes: [.contentType("contentTypeUID")], then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})
使用特定语言的初始同步

您还可以使用仅特定语言区域的条目初始化同步。为此，请使用 sync 并将语言区域代码指定为其值。

但是，如果您这样做，后续同步将仅包括指定语言区域的条目。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(syncToken: syncToken)

stack.sync(syncTypes: [.locale("en-gb")], then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})
使用发布类型的初始同步

您还可以根据特定的发布类型初始化同步，包括条目和资源。 可接受的值为 PublishType 枚举：entryPublished、entryUnpublished、entryDeleted、assetPublished、assetUnpublished、assetDeleted 和 contentTypeDeleted。 为此，请使用 syncPublishType 并指定参数。

但是，如果您这样做，后续同步将仅包括指定发布类型的条目。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(syncToken: syncToken)

stack.sync(syncTypes: [.publishType(.assetPublished)], then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})
使用多个参数的初始同步

要初始化从特定日期开始的特定内容类型的条目同步，请使用下面给出的代码段。

请注意，后续同步将仅包括指定内容类型的条目。

let stack = Contentstack.stack(apiKey: apiKey,
         deliveryToken: deliveryToken,
         environment: environment)

let syncStack = SyncStack(syncToken: syncToken)

stack.sync(syncTypes: [.locale("en-gb"), .contentType("contentTypeUID")], then: { (result: Result<SyncStack, Error>) in
switch result {
case .success(let syncStack):
     let items = syncStack.items
     
     //error for any error description
     //syncStack for SyncStack
     //syncStack.syncToken: contains token for next sync Store this token For next sync
     //syncStack.paginationToken: contains token for next sync page this token for next sync
     //syncStack.items: contains sync data
     If let token = syncStack.paginationToken {
         UserDefault.standard.setValue(token, forKey:"PaginationToken")
     }else if let token = syncStack.syncToken {
         UserDefault.standard.setValue(token, forKey:"SyncToken")
     }

case .failure(let error):
     print(error)
}
})

有用的链接