OAuth.io 1.2.4

OAuth.io 1.2.4

×

许可证 Apache-2.0
发布最新发布2019年4月

由 OAuth.io 团队 维护。

OAuth.io 1.2.4

OAuth.io iOS SDK

这是 OAuth.io 的 iOS SDK。OAuth.io 允许您轻松地将 100+ 提供商 集成到您的 Web 应用中，无需担心每个提供商的 OAuth 具体实现。

您可以通过遵循我们基于 github 的教程的简单步骤来了解如何将此框架集成到项目中：从这里开始 :)

安装

获取 SDK

要安装此 SDK 到您的 iOS 应用中，您可以

  • 从 Cocoapods 获取框架
  • 手动在 Xcode 中安装框架

两种方法都很简单。

通过 Cocoapods 安装

要使用 Cocoapods 安装 SDK，只需将此条目添加到您的 Podfile 中

pod "OAuth.io"

然后运行以下命令

$ pod update

这将为您获取框架并将其作为项目依赖项安装。一旦完成，您就可以开始编写代码了。

手动安装框架

框架作为 Dist/OAuthiOS.framework 文件存在于此仓库中。要将其作为 Xcode 中的项目依赖项添加，请按照以下步骤操作

  • 点击 Documents 浏览器中的项目名称
  • 转到 构建阶段
  • 打开 链接二进制库 部分
  • 点击 + 按钮
  • 点击 添加其他...
  • 选择 OAuthiOS.framework
  • 点击 添加

然后您就可以开始编写代码了。

使用说明

此SDK允许您弹出一个窗口，让用户以指定的OAuth提供商登录。

开始之前，请确保您在OAuth.io上有一个账户，并在您的仪表板中创建了一个配置了您所需的提供者的应用程序。要使用此SDK，您需要该应用程序的公钥。

包括的文件

使用此SDK，您只需要包含一个头文件

#import <OAuthiOS/OAuthiOS.h>

此头文件包含您将需要使用所有类的引用。

认证过程

要初始化SDK，您需要创建一个OAuthIOModal实例，并使用您的应用公钥和一个代表者来初始化它，这个代表者必须实现OAuthIODelegate协议。这个代表者将让您以请求对象的形式处理认证过程的结果，这也将允许您进行API调用。

此协议要求您的代表者实现以下方法

// Handles the results of a successful authentication
- (void)didReceiveOAuthIOResponse:(OAuthIORequest *)request;

// Handle errors in the case of an unsuccessful authentication
- (void)didFailWithOAuthIOError:(NSError *)error;

如果您正在使用UIViewController作为代表者，其头文件将如下所示

#import <UIKit/UIKit.h>
#import <OAUthiOS/OAuthiOS.h>
@interface MyViewController : UIViewController<OAuthIODelegate>
//[...]
@end

在该视图控制器中，当您需要显示弹窗时，可以使用以下方式使用公钥初始化OAuthIOModal对象

OAuthIOModal *oauthioModal = [[OAuthIOModal alloc] initWithKey:@"your_app_public_key" delegate:self];

然后您可以按照以下方式显示所需的提供者的弹窗

[oauthioModal showWithProvider:@"facebook"];

一旦用户登录到提供商并接受了您在OAuth.io仪表板中请求的权限，就会调用didReceiveOAuthIOResponse方法，您可以使用request对象使用getCredentials方法检索访问令牌并自行处理它，或使用get|post|put|patch|del|me方法执行API调用。

使用缓存

可以缓存认证步骤的结果，以防止每次用户重新启动应用程序时都显示弹窗。为此，您需要在弹窗中传递缓存选项，如下所示

NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
[options setObject:@"true" forKey:@"cache"];
[oauthioModal showWithProvider:@"facebook" options:options];

获取用户凭据

一旦您从认证过程获取了request对象，就可以像这样检索用户凭据（OAuth 2的access_token，OAuth 1的oauth_token和oauth_token_secret）

NSDictionary *credentials = [request getCredentials];

执行API调用

```request```对象允许您使用标准HTTP方法执行API调用：GET，POST，PUT，PATCH，DELETE。您还可以使用me方法获取包含用户信息（姓名、电子邮件等）的统一对象。

GET请求

假设提供商在/blogpost/:id URL上公开了一个端点，该端点返回博客文章的标题和内容。

[_request get:@"/blogpost/1" success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
     NSLog(@"%@", [output objectForKey: @"title"]);
     NSLog(@"%@", [output objectForKey: @"content"]);
 }];

POST请求

假设提供商在/comment URL上公开了一个端点，该端点等待包含字段content的POST请求，其中包含评论的内容，并返回包含新评论ID的字段id。

NSMutableDictionary *fields = [[NSMutableDictionary alloc] init];
[fields setObject: @"Nice blogpost" forKey:@"content"];

[_request post:@"/blogpost/1" withParams:fields success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
     NSLog(@"%@", [output objectForKey: @"id"]);
 }];

PUT请求

假设提供商在/comment/:id URL上公开了一个端点，该端点等待包含字段content的PUT请求，其中包含要编辑的评论内容，如果编辑成功则返回true。

NSMutableDictionary *fields = [[NSMutableDictionary alloc] init];
[fields setObject: @"Nice blogpost" forKey:@"content"];

[_request put:@"/blogpost/1" withParams:fields success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
    //Should print "true"
     NSLog(@"%@", body);
 }];

PATCH请求

假设提供商在/comment/:id URL上公开了一个端点，该端点等待包含字段content的PATCH请求，其中包含要编辑的评论内容，如果编辑成功则返回true。

NSMutableDictionary *fields = [[NSMutableDictionary alloc] init];
[fields setObject: @"Nice blogpost" forKey:@"content"];

[_request patch:@"/blogpost/1" withParams:fields success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
    //Should print "true"
     NSLog(@"%@", body);
 }];

DELETE请求

假设提供商在/blogpost/:id URL上公开了一个端点，该端点等待DELETE请求来删除博客文章，如果删除成功则返回true。

[_request del:@"/blogpost/1" success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
     //Should print "true"
     NSLog(@"%@", body);
 }];

获取用户信息

如果需要获取包含统一字段且与提供商实现无关的用户信息字典（例如，获取firstname字段，无论提供商返回first-name，first_name还是firstName），可以像这样调用me方法。

[_request me:nil success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
     NSLog(@"name: %@", [output objectForKey:@"name"]);
 }];

未映射到统一字段的字段仍然在名为raw的参数中可用。

可以通过传递包含字段列表的NSArray来过滤此方法返回的字段。

 NSMutableArray *filter = [[NSMutableArray alloc] init];
[filter addObject:@"name"];
[filter addObject:@"email"];
[_request me:filter success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
 {
    NSLog(@"name: %@", [output objectForKey:@"name"]);
 }];

关于服务器端流程的说明

如果您计划通过我们的服务器端SDK之一使用OAuth.io您的后端，使用此SDK的方式略有不同。

首先，简要回顾一下服务器端流程，其中所有API调用和身份验证（通过在前端检索的代码）都是在服务器端执行的。服务器端流程包括以下步骤

  • 从您的后端检索到前端的状态令牌
  • 在前端启动带有状态令牌的认证弹出窗口，返回一个代码
  • 将代码发送回后端
  • 通过代码在服务器端进行认证
  • 在服务器端执行API调用

因此，在您后端，您需要两个端点

  • 一个用于状态令牌（GET）
  • 一个用于认证（POST，参数为代码）

在iOS SDK中，对这些端点的调用是自动执行的。您需要做的就是将它们的URL传递给showWithProvider方法，如下所示

[_oauthioModal showWithProvider:@"facebook" options:options stateTokenUrl:@"http://example/state/url" authUrl:@"http://example/auth/url"];

首先将调用状态URL，然后向用户显示认证弹出窗口，获取代码，最后将代码发送到认证URL。

要知道过程何时完成，您需要将以下方法添加到您的OAuthIODelegate类中

- (void)didAuthenticateServerSide:(NSString *)body andResponse:(NSURLResponse *) response;
- (void)didFailAuthenticationServerSide:(NSString *)body andResponse:(NSURLResponse *)response andError:(NSError *)error;

第一个方法将捕获成功的认证（通常意味着认证URL返回“200 OK”），并给您从那个URL获取的body和response对象。第二个方法将捕获错误（状态令牌未找到，认证失败）。

构建

有关构建/更新您的cocapod的详细信息，请参阅以下链接 https://sebastiandobrincu.com/blog/how-to-update-your-cocoapods-library-version

简而言之

  1. 更新OAuth.io.podspec文件中的'版本'。
  2. 使用以下命令标记主分支
  • `git tag {{VERSION}} -m '版本信息'
  • `git push origin --tags
  1. 检查您的Pod是否通过验证
  • pod spec lint OAuth.io.podspec
  1. 注册Trunk会话
  • pod trunk register name@company '姓名' --description='OAuth.io'
  1. 使用trunk推送新的Pod版本
  • pod trunk push OAuth.io.podspec

错误

在构建时，如果您收到

 pod spec lint OAuth.io.podspec 

 -> OAuth.io (1.2.3)
    - ERROR | [iOS] unknown: Encountered an unknown error (/usr/bin/xcrun simctl list -j devices

xcrun: error: unable to find utility "simctl", not a developer tool or in PATH
) during validation.

Analyzed 1 podspec.
  • 下载最新的XCode（不仅仅是CLI）
  • 打开XCode，转到'XCode' -> '首选项' -> '位置'

贡献

问题

如果您在使用此SDK时遇到问题，请随时发布问题。

拉取请求

欢迎fork并提交流并。我们非常感谢您在这个项目中投入的时间，并且我们很愿意审查您的代码，并在它带来良好改进的情况下合并它 :)

如果您要提交拉取请求，请注意以下简单规则

  • 每个拉取请求一个特性
  • 编写易于理解的提交消息
  • 为您的特性编写单元测试：如果您修复了一个错误，例如，编写一个测试来证明该错误存在，并且您的修复可以解决它。
  • 编写拉取请求的清晰描述

这样做，我们将能够更快地合并您的拉取请求 :)

许可协议

此SDK遵循Apache2许可协议发布。

更多详细信息请参阅oauth.io 文档