Kentico Cloud Swift SDK

总结

KenticoCloud iOS SDK是一个用于检索内容的库。您可以将SDK作为CocoaPod包使用，也可以手动添加。

示例应用

此存储库包含示例应用，展示SDK的基本用法。它显示了一个示例项目的内容，该项目展示了Kentico Cloud功能和最佳实践。此功能齐全的项目包含Dancing Goat（一家咖啡店连锁店的营销内容）。如果您没有自己的示例项目，任何Kentico Cloud订阅的管理员都可以通过生成一个。

快速入门

1. 添加一个poD

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'KenticoCloud'
end

$ pod install

2. 创建类型对象 - 在此示例中，类型对象是 Article。它代表基于Kentico Cloud中的Content类型检索的内容项。此内容类型有三个元素，以下分别具有以下代码名称： title（一个文本元素）teaser_image（一个资产元素）和post_date（一个日期时间元素）。

import ObjectMapper
import KenticoCloud

class Article: Mappable {
    var title: TextElement?
    var asset: AssetElement?
    var postDate: DateTimeElement?
    
    required init?(map: Map){
        let mapper = MapElement.init(map: map)
        title = mapper.map(elementName: "title", elementType: TextElement.self)
        asset = mapper.map(elementName: "teaser_image", elementType: AssetElement.self)
        postDate = mapper.map(elementName: "post_date", elementType: DateTimeElement.self)
    }
    
    func mapping(map: Map) {
    }
}

3. 准备Delivery客户端

import KenticoCloud

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID")

4. 准备一个查询

let articlesQueryParameters = QueryBuilder.params().type(article).language("es-ES")

5. 获取并使用内容项

client.getItems(modelType: Article.self, queryParameters: articleQueryParameters) { (isSuccess, itemsResponse, error) in
    if isSuccess {
        if let articles = itemsResponse?.items {
            // use your articles here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
}

安装

CocoaPods

CocoaPods 是Cocoa项目的依赖项管理器。您可以使用以下命令安装它

$ gem install cocoapods

要使用CocoaPods将KenticoCloud集成到您的Xcode项目中，请在您的 Podfile 中指定它

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'KenticoCloud'
end

然后，运行以下命令

$ pod install

使用DeliveryClient

DeliveryClient 类是SDK的获取内容的主要类。使用此类，您可以检索您的Kentico Cloud项目的桌面内容。

要创建类的实例，您需要提供一个项目ID

// Initializes an instance of the DeliveryClient client
let cloudClient = DeliveryClient.init("975bf280-fd91-488c-994c-2f04416e5ee3")

创建 DeliveryClient 后，您可以通过调用客户端实例上的方法开始查询您的项目存储库。有关细节，请参见基本查询。

预览未发布内容

要检索未发布的内容，您需要创建一个包含项目 ID 和预览 API 密钥的 DeliveryClient。每个 Kentico Cloud 项目都有自己的预览 API 密钥。

import KenticoCloud

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID", previewApiKey:"PREVIEW_API_KEY")

有关更多详细信息，请参阅使用交付 API 预览未发布内容。

从受保护的项目获取内容

要从受保护的项目中检索内容，您需要创建一个包含项目 ID 和安全 API 密钥的 DeliveryClient。

import KenticoCloud

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID", secureApiKey:"SECURE_API_KEY")

有关更多详细信息，请参阅保护交付 API。

配置重试策略

客户端在遇到错误后可以重试获取项目。默认情况下，重试策略启用，最大重试次数为 5。您可以在创建 DeliveryClient 时配置最大重试次数。

import KenticoCloud

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID", isRetryEnabled: true, maxRetryAttempts: CUSTOM_MAX_ATTEMPTS_NUMBER)

您还可以禁用重试策略。

import KenticoCloud

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID", isRetryEnabled: false)

获取项

使用强类型模型

为了接收强类型项，您需要实现您的项目模型。它必须遵守 Mappable 协议并实现映射功能。您可以使用您自己的映射或我们提供的强类型元素类型。

元素类型映射

import ObjectMapper

class Article: Mappable {
    var title: TextElement?
    var asset: AssetElement?
    var postDate: DateTimeElement?
    
    required init?(map: Map){
        let mapper = MapElement.init(map: map)
        title = mapper.map(elementName: "title", elementType: TextElement.self)
        asset = mapper.map(elementName: "teaser_image", elementType: AssetElement.self)
        postDate = mapper.map(elementName: "post_date", elementType: DateTimeElement.self)
    }
    
    func mapping(map: Map) {

    }

自定义映射

import ObjectMapper

public class Cafe: Mappable {
    public var city: String?
    public var street: String?
    public var country: String?
    
    public required init?(map: Map){
        
    }
    
    public func mapping(map: Map) {
        city <- map["elements.city.value"]
        street <- map["elements.street.value"]
        country <- map["elements.country.value"]
    }

基本项查询

一旦您有一个 DeliveryClient 实例，您可以通过对实例调用方法来开始查询您的项目仓库。您需要传递您的项目模型和查询。您可以通过两种方式为列表创建查询

创建自定义字符串查询

let customQuery = "items?system.type=article&order=elements.post_date[desc]"
client.getItems(modelType: Article.self, customQuery: customQuery) { (isSuccess, itemsResponse, error) in ...

使用查询参数数组

let coffeesQueryParameters = QueryBuilder.params().type(contentType).language("es-ES")
client.getItems(modelType: Coffee.self, queryParameters: coffeesQueryParameters) { (isSuccess, itemsResponse, error) in ...

然后您可以在完成后处理程序中使用所获得的项目。

// Retrieves a list of all content items of certain type
let coffeesQueryParameters = QueryBuilder.params().type("coffee")
client.getItems(modelType: Coffee.self, queryParameters: coffeesQueryParameters) { (isSuccess, itemsResponse, error) in
       if isSuccess {
           if let coffees = itemsResponse?.items {
               // Use your items here
           }
       } else {
           if let error = error {
               print(error)
           }
       }

您也可以只检索单个项目。

// Retrieves a single content item
let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID")
client.getItem(modelType: Cafe.self, itemName: "boston") { (isSuccess, deliveryItem, error) in
    if isSuccess {
        if let cafe = deliveryItem.item {
            // Use your item here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
}

获取关联的条目

您可以从itemResponse或itemsResponse对象中获取关联的内容条目。

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID")
client.getItem(modelType: Article.self, itemName: "on_roasts", completionHandler: { (isSuccess, itemResponse, error) in
	if isSuccess {
		for articleCodeName in (itemResponse?.item?.relatedArticles?.value)! {
            		let relatedArticle = itemResponse?.getLinkedItems(codename: articleCodeName, type: Article.self)
        	}
	}
}

获取内容类型

获取单个内容类型

client.getContentType(name: "coffee", completionHandler: { (isSuccess, contentType, error) in
    if !isSuccess {
        fail("Response is not successful. Error: \(String(describing: error))")
    }
    
    if let type = contentType {
	// use content type here
    }
})

获取多个内容类型

client.getContentTypes(skip: 2, limit: 4, completionHandler: { (isSuccess, contentTypesResponse, error) in
    if !isSuccess {
        fail("Response is not successful. Error: \(String(describing: error))")
    }
    
    if let response = contentTypesResponse {
	// use content types here
    }
})

获取分类

获取分类组

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID")
client.getTaxonomyGroup(taxonomyGroupName: "personas", completionHandler: { (isSuccess, deliveryItem, error) in
   if isSuccess {
       if let taxonomyGroup = deliveryItems.item {
        // use your taxonomy group here
       }
    } else {
         if let error = error {
             print(error)
         }
    }
})

获取所有分类

let client = DeliveryClient.init(projectId: "YOUR_PROJECT_ID")
client.getTaxonomies(completionHandler: { (isSuccess, deliveryItems, error) in
   if isSuccess {
       if let taxonomies = deliveryItems?.items {
        // use your taxonomies here
       }
    } else {
         if let error = error {
             print(error)
         }
    }
})

使用图像转换

Kentico Cloud 通过使用 URL 参数支持图像转换。提供了一个辅助类来方便地创建 URL。然而，在使用辅助类之前，请阅读此文档了解参数的限制，因为辅助类不会验证输入参数。

以下是示例用法

let originalUrl = "https://example.com/sample-image.jpg"
let transformedUrl = ImageUrlBuilder(baseUrl: originalUrl)
                        .withWidth(300)
                        .withHeight(500)
                        .withFitMode(.Clip)
                        .withDpr(3)
                        .withBackGroundColor(rgbColor: 0x330FAA)
                        .withFormat(.png)
                        .url
// transformedUrl = https://example.com/sample-image.jpg?w=300&h=500&fit=clip&dpr=3.0&bg=330FAA&fm=png

本地开发

要本地运行 SDK 与示例应用，请按照以下步骤操作。

下载仓库。
在终端导航到 /Example。
运行 pod install （必须安装 Cocoapods）。
在 XCode 中打开 KenticoCloud.xcworkspace。
运行。

调试

如果您想从客户端查看调试信息，则设置客户端的 enableDebugLogging 属性

let deliveryClient = DeliveryClient.init(projectId: "YOUR_PROJECT_ID", enableDebugLogging = true)

发布 Cocoapod 包的新版本

当添加新标签时，Travis CI 会自动构建并发布 pod 的新版本。

文档

您可以在这里找到完整的 API 参考文档这里。

更新生成的文档

我们使用 Jazzy，这是一个用于生成 Swift 文档的命令行工具。更新文档请执行以下步骤：

安装 Jazzy [sudo] gem install jazzy
从存储库的根目录运行 jazzy。
提交来自 /Docs 目录的更改。

反馈与贡献

查看贡献页面，了解如何提交问题、开始讨论和开始贡献。

许可协议

KenticoCloud Swift SDK 在 MIT 许可协议下提供。有关更多信息，请参阅 LICENSE 文件。


依赖
AlamofireObjectMapper	~> 5.2.0
Kanna	~> 4.0.2

KenticoCloud 1.2.0

KenticoCloud 1.2.0

KenticoCloud 1.2.0

Kentico Cloud Swift SDK

总结

示例应用

快速入门

安装

CocoaPods

使用DeliveryClient

预览未发布内容

从受保护的项目获取内容

配置重试策略

获取项

使用强类型模型

基本项查询

获取关联的条目

获取内容类型

获取单个内容类型

获取多个内容类型

获取分类

获取分类组

获取所有分类

使用图像转换

本地开发

调试

发布 Cocoapod 包的新版本

文档

更新生成的文档

更多信息

反馈与贡献

许可协议