如果您正在使用 Swift 并且想要使用 Catalyze iOS SDK，您只需遵循 本指南 即可！.
如果您从版本 2.X 升级到版本 3.X，请查看 迁移指南 了解重大变更以及如何快速上手！或者如果您是第一次开始，请继续阅读！
推荐通过 cocoapods 进行安装。只需将 pod 'catalyze-ios-sdk', '~> 3.0' 添加到您的 Podfile，运行 pod install，然后即可开始开发。如果您不使用 cocoapods 或拥有尚未集成 cocoapods 的现有项目，可以克隆此仓库到您的计算机。只需通过点击文件菜单，然后选择 "将文件添加到 'yourProjectName'..." 添加 iOS SDK 文件夹到您的项目目录中。导航到 iOS SDK 的目录并单击添加。现在您可以在应用程序中使用 iOS SDK。
如果您想了解更多关于 Catalyze 平台的信息，请务必查看我们的 资源页面。
首先，您必须在 仪表板 上设置一个应用程序。您需要关于应用程序的以下信息：API 密钥和应用程序 ID。请注意，API 密钥有三个部分：类型、标识符和 ID。一个完整的 API 密钥看起来像 ios io.catalyze.sdk 426881c0-f39b-4d52-82de-be509d5450f6 或更通用地 <type> <identifier> <id>。在您获得这些信息后，您必须调用
[Catalyze setApiKey:@"{fullApiKey}" applicationId:@"{appId}"];
在 application:didFinishLaunchingWithOptions: 中。请注意：所有需要网络请求的方法都是以异步方式运行的。不要忘记每次需要使用 iOS SDK 时都导入 #import "Catalyze.h"。
为了使SDK更便携，您可以更改变量API通信的URL。如果需要使用除公共API外的不同部署，您仍然可以使用iOS SDK。只需调用
[Catalyze setApiKey:@"{fullApiKey}" applicationId:@"{appId}" baseUrl:@"{https://myBaseUrl}"];
请注意，基础URL中不要包含API版本路径（/v2）。一个示例基础URL如下所示 https://apiv2.catalyze.io。这只能进行一次，并且不能在运行时更改。
为了调试目的，您可以启用Catalyze SDK通过的所有请求的日志记录。在您的 application:didFinishLaunchingWithOptions: 方法中调用 [Catalyze setLoggingLevel:kLoggingLevelDebug];。有关不同日志级别及其描述，请参阅 CatalyzeConstants.h。
iOS SDK在所有网络请求中大量使用了块。从3.0.0版本开始，每个请求都需要成功和失败的块。
所有遵循 CatalyzeObjectProtocol（CatalyzeEntry 和 CatalyzeUser）的类都需要 CatalyzeSuccessBlock 类型的成功块。CatalyzeSuccessBlock 包含一个 id 类型的参数。这是因为其类型基于你所处的上下文变化。如果你使用 CatalyzeEntry 类进行请求，它就是 CatalyzeEntry 类型，同样，当你使用 CatalyzeUser 类进行请求时，它就变为 CatalyzeUser 类型。这使得完成任何操作变得非常简单。
尽管对象在成功块中返回，但并不需要使用它。你仍然需要保留发起请求的原始对象的引用。所有值都更新在那个对象上，因此不需要在成功块中使用所提供的值。它只是为了方便而存在。
整个SDK只有一个失败块。它属于 CatalyzeFailureBlock 类型。它有3个参数：NSDictionary *result, int status, NSError *error。此处的 result 字典是API的JSON错误响应。现在你可以看到你得到的正是错误，而无需打开日志记录！status 和 error 与之前相同：HTTP状态码和从响应构造的 NSError 对象。
在你可以对Catalyze API执行任何操作之前，你需要进行认证。这通过CatalyzeUser登录或注册来完成。CatalyzeUser 表示任何登录应用的实体。具体数据绑定到该用户，并且在用户登录期间创建的任何 CatalyzeEntrys 都绑定到他们的账户。
与 CatalyzeEntry 类似，你可以保存任何你想要的用户信息，但这被称为 'extra'。这是因为 CatalyzeUser 中列出了许多预定义的数据元素。因此，您不会使用方法
setObject:forKey:
removeObjectForKey:
objectForKey:
你会用这些方法在一个 CatalyzeUser 的额外条目上
setExtra:forKey:
removeExtraForKey:
extraForKey:
CatalyzeUser 支持的字段完整列表如下
所有这些字段在CatalyzeUser对象上都有getter和setter。其他所有数据必须存储为“Extra”。
一些字段不是基本数据类型。上面带有*标记的是嵌套对象，带有**标记的是嵌套对象数组。这些对象及其对应的属性可以在相应的类中查看。
通过调用以下方法进行登录：
[CatalyzeUser logInWithUsernameInBackground:username password:password success:^(CatalyzeUser *result) {
//logged in, take appropriate action
} failure:^(NSDictionary *result, int status, NSError *error) {
//check the result dictionary and show an appropriate response
}];
登录用户被传递回成功块，同时也被分配给CatalyzeUser类的currentUser属性。在SDK中使用时，任何时候只能有一个用户登录，因此成功登录后可以通过以下方式访问这个用户：
[CatalyzeUser currentUser];
要登出，您需要调用：
[[CatalyzeUser currentUser] logout];
这将清除本地存储的所有关于用户的信息，包括会话信息，并告知API销毁您的会话令牌。
我们现在已登录到应用，可以将一些受支持的字段保存到我们的用户信息中。如果我们想更新我们的名字、姓氏、年龄和额外的字段
[[[CatalyzeUser currentUser] name] setFirstName:@"John"];
[[[CatalyzeUser currentUser] name] setLastName:@"Smith"];
[[CatalyzeUser currentUser] setAge:[NSNumber numberWithInt:32]];
[[CatalyzeUser currentUser] setExtra:[NSNumber numberWithBool:YES] forKey:@"on_medication"];
[[CatalyzeUser currentUser] saveInBackground];
注意：执行CRUD操作的所有相同方法都适用于保存CatalyzeUser，只是不涉及创建。如果您需要创建CatalyzeUser，请使用[CatalyzeUser signUpWithUsernameInBackground:email:name:password:success:failure:]，尝试使用CatalyzeUser的创建方法将无法编译您的代码。
CatalyzeEntry表示一个条目，可以在catalyze.io API中存储在预定义的自定义类中。这些自定义类在使用或引用在应用程序或API中使用之前必须在控制台中创建，否则API将返回4XX状态码。
CatalyzeEntry有几个属性：entryId、authorId、parentId、updatedAt、createdAt和content。以下列表简要介绍了这些属性：
要使用CatalyzeEntry，您必须使用在控制台上创建的自定义类名称初始化它。
CatalyzeEntry *myEntry = [CatalyzeEntry entryWithClassName:@"{customClassName}"];
现在您有了CatalyzeEntry，可以保存值、检索值，在catalyze.io API上创建新的条目。
[[myEntry content] setObject:@"blue" forKey:@"favorite_color"];
NSString *myColor = [[myEntry content] objectForKey:@"favorite_color"];
[myEntry createInBackground];
您还可以使用其唯一标识符初始化一个条目。当ID已知但必须从API中获取该条目的其他所有数据时，这很有用。为此，只需如下操作
CatalyzeEntry *myNewEntry = [CatalyzeEntry entryWithClassName:@"{customClassName}"];
[myNewEntry setEntryId:@"1234"];
[myNewEntry retrieveInBackgroundWithSuccess:^(id result) {
//take action here
//the object is passed back in the block, but its not needed since you have a reference to myNewEntry
} failure:^(NSDictionary *result, int status, NSError *error) {
//take appropriate action here, show a message to the user!
//you can access the error message from the server in the `result` dictionary
}];
要将更改保存到catalyze.io API上的任何数据，您有以下3种选项。不使用回调异步保存数据，使用回调异步保存数据，或者完成后在主线程上执行给定的选择器。这三个选项可用于任何符合CatalyzeObjectProtocol协议的对象，目前只是CatalyzeEntry和CatalyzeUser。它们按以下方式执行：
无回调的异步操作
[catalyzeEntryInstance saveInBackground];
具有回调的异步操作
[catalyzeEntryInstance saveInBackgroundWithSuccess:^(id result) {
//perform actions here
} failure:^(NSDictionary *result, int status, NSError *error) {
//take appropriate actions for failure here
}];
完成后在主线程上执行选择器的异步操作
[catalyzeEntryInstance saveInBackgroundWithTarget:self selector:@selector(takeAction:)];
CatalyzeQuery用于管理和自定义类的搜索。CatalyzeQuery由四个部分组成。
前两个部分是pageSize和pageNumber。pageSize表示您希望API返回的条目数。请注意，您不一定总是收到pageSize数量的条目。实际数量取决于请求的pageNumber和自定义类中的条目数量。pageNumber用于指定应该跳过的条目数。例如，如果自定义类中有50个条目，编号从0到49，那么pageNumber为1且pageSize为20将返回条目0到19。如果pageNumber为2且pageSize为20，则返回条目20到39。
剩下两个部分是queryField和queryValue。queryField是自定义类中将进行搜索的数据列，而queryValue是用来在queryField列中查找的实际值。
要使用CatalyzeQuery，您必须使用要查询的自定义类的名称初始化对象。
CatalyzeQuery *query = [CatalyzeQuery queryWithClassName:@"{myCustomClass}"];
[query setQueryValue:@"53202"];
[query setQueryField:@"zip_code"];
[query setPageNumber:1];
[query setPageSize:100];
[query retrieveInBackgroundWithSuccess:^(NSArray *result) {
//query completed successfully with an array CatalyzeEntry instances
} failure:^(NSDictionary *result, int status, NSError *error) {
//query failed
}];
如果您是管理员或主管（或拥有适当的ACL），您可以查询整个自定义类。
CatalyzeQuery *query = [CatalyzeQuery queryWithClassName:@"{myCustomClass}"];
[query setQueryValue:@"53202"];
[query setQueryField:@"zip_code"];
[query setPageNumber:1];
[query setPageSize:100];
[query retrieveAllEntriesInBackgroundWithSuccess:^(NSArray *result) {
//query completed successfully with an array CatalyzeEntry instances
} failure:^(NSDictionary *result, int status, NSError *error) {
//query failed
}];
如果您拥有适当的权限，您还可以直接查询其他用户的数据。首先您必须知道他们的usersId。
CatalyzeQuery *query = [CatalyzeQuery queryWithClassName:@"{myCustomClass}"];
[query setQueryValue:@"53202"];
[query setQueryField:@"zip_code"];
[query setPageNumber:1];
[query setPageSize:100];
[query retrieveInBackgroundForUsersId:@"{otherUsersId}" success:^(NSArray *result) {
//query completed successfully with an array CatalyzeEntry instances
} failure:^(NSDictionary *result, int status, NSError *error) {
//query failed
}];
而不是仅仅保存如字符串、数字或布尔值等简单数据类型，您还可以使用iOS SDK在Catalyze API上存储文件。所有文件管理任务都是通过CatalyzeFileManager类完成的。您可以上传文件、下载文件、列出您的文件或删除文件。当然，您还可以对其他用户使用相应的权限执行这些操作。
上传文件需要一个NSData实例以及您要上传的文件的mime-type。如果您在主捆绑包中有一个名为testFile.txt的文件，上传文件可能如下所示
NSString *path = [[NSBundle mainBundle] pathForResource:@"testFile" ofType:@"txt"];
NSData *data = [NSData dataWithContentsOfFile:path];
[CatalyzeFileManager uploadFileToUser:data phi:NO mimeType:@"text/plain" success:^(NSDictionary *result) {
NSString *filesId = [result valueForKey:@"filesId"];
//store the filesId somewhere
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
如果您想为其他用户上传文件，您必须首先知道他们的usersId
NSString *path = [[NSBundle mainBundle] pathForResource:@"testFile" ofType:@"txt"];
NSData *data = [NSData dataWithContentsOfFile:path];
[CatalyzeFileManager uploadFileToOtherUser:data usersId:@"{usersId}" phi:NO mimeType:@"text/plain" success:^(NSDictionary *result) {
NSString *filesId = [result valueForKey:@"filesId"];
//store the filesId somewhere
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
上传文件后，请记住存储filesId。filesId是您用于下载文件的标识符，它唯一标识文件。
[CatalyzeFileManager retrieveFile:filesId success:^(NSData *result) {
//save the data to disk, construct an image, etc.
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
类似地，如果您为其他用户上传了文件，您可以通过适当的权限下载该文件，如下所示
[CatalyzeFileManager retrieveFileFromUser:filesId usersId:@"{usersId}" success:^(NSData *result) {
//save the data to disk, construct an image, etc.
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
如果您没有保存filesId或您只是想让用户知道他们所有文件的列表并选择其中一个，您可以列出属于当前登录用户的所有文件。
[CatalyzeFileManager listFiles:^(NSArray *result) {
for (NSDictionary *dict in result) {
[dict valueForKey:@"filesId"];
}
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
同样地，对于其他用户，您也可以列出他们的文件，当然，需要相应的权限。
[CatalyzeFileManager listFilesForUser:@"{usersId}" success:^(NSArray *result) {
for (NSDictionary *dict in result) {
[dict valueForKey:@"filesId"];
}
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
删除文件非常直接，遵循与其他文件管理路由相同的模式。如果您知道filesId，可以像这样删除文件
[CatalyzeFileManager deleteFile:filesId success:^(id result) {
//the files has been deleted
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
同样地，对于其他用户，您可以通过适当的权限删除他们的文件，如下所示
[CatalyzeFileManager deleteFileFromUser:filesId usersId:@"{usersId}" success:^(id result) {
//the files has been deleted
} failure:^(NSDictionary *result, int status, NSError *error) {
//something went wrong, check the result dictionary
}];
Copyright 2014 catalyze.io, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://apache.ac.cn/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.