小米帐号开放平台 OAuth iOS SDK 使用说明

---

小米 OAuth 简介

http://dev.xiaomi.com/docs/passport/oauth2/

小米帐号开放平台文档

http://dev.xiaomi.com/docs/passport/user_guide/

概述

    本 SDK 为开发者封装了 iOS 上 OAuth 登录小米帐号的方法，并提供访问小米帐号 Open API 的必要工具。用户可以尝试 SDK 中提供的方法进行登录，并获取小米帐号提供的资料。    本文档将对使用 IOS SDK 时的参数和接口进行说明，并分析一个简单示例，帮助第三方更方便地使用 SDK（一些未使用的接口仅做简单说明）。

名词解释

• AppKey -- 分配给每个第三方应用的 app key。用于验证身份，显示来源等功能。
• Code -- 代表用户身份的 code，用于第三方的服务器向小米帐号服务器申请 Access Token。
• AccessToken -- 表示用户身份的 token，用于小米帐号 API 的调用。
• ExpirationDate -- 过期时间，用于判断登录是否过期。
• RedirectURI -- 应用的回调页面，第三方应用在小米帐号开发平台注册的 URL。
• EncryptAlgoritm -- 小米帐号 API 调用时所使用的加密算法，具体算法由 SDK 提供，第三方不用处理。
• EncryptKey -- 小米帐号 API 调用时，加密算法所使用的 key。

目录结构

• SDK 文件夹包括两个文件：    1. MiPassport.framework 包含了 iOS SDK 的头文件定义和具体实现。    2. MiPassport.bundle 包含了 iOS SDK 需要的资源文件。

• MiPassportDemo 文件夹：    MiPassportDemo 是一个示例代码，包括使用 MiPassport SDK 实现小米帐号的登录、code 获取、拉取小米用户资料以及关系、登出小米帐号等功能。可以配合本文档理解。

接口说明

• MiPassport/MiPassport.h -- 该文件提供了申请小米帐号授权所需的接口和回调协议。
• MiPassport -- 为第三方应用提供的主要接口，提供登录、获取 code 以及访问小米帐号开放 API 的方法。登录结果也会保存在该类的对象中返回给第三方应用。
• MPSessionDelegate -- 第三方应用需要实现该协议来处理登录授权的回调结果。
• MiPassport/MPReqeust.h -- 该文件提供了访问小米帐号 API 所需的接口和回调协议。
• MPRequest -- 请求小米帐号 API 的类，一个简单的 http client，封装了访问小米帐号 API 所需的方法，第三方使用该类访问小米帐号的开放 API。
• MPRequestDelegate -- 实现该协议来处理开放 API 请求的各种回调。
• MPAuthorizeDialog -- 小米帐号认证界面，用于支持 OAuth 2.0 授权。应用申请授权时，由 MiPassport 调用此类，请求用户登录小米帐号并授权应用使用，授权成功后将会通过 MPSessionDelegate 返回给应用。第三方不需要使用此类，由 MiPassport 使用并管理。
• MPConstants.h -- 该文件定义了 SDK 所用的各种常量。

使用步骤及示例

1. 添加 framework 及 bundle

• 1.1 将 SDK 中的 MiPassport.framework 和 MiPassport.bundle 文件复制到应用开发目录下。然后，将 MiPassport.framework 从 SDK 的保存目录拖拽到工程导航视图（project navigator）中的 Frameworks 虚拟目录下。
• 1.2 在 “Build Phases” 中选择展开 “Copy Bundle Resources” 一栏，并点击 “+” 图标。选择 “Add Other…”，进入 iOS SDK 文件所在目录，选择 MiPassport.bundle，点击回车或者点击 “Open”。返回后看到 MiPassport.bundle 已经在 “Copy Bundle Resources” 中出现。

2. 实现 MPSessionDelegate

    在需要使用 SDK 的地方，首先引用 MiPassport/MiPassport.h. 应用在 OAuth 2.0 授权前需要实现该协议，以处理登录授权中的各种结果。

 登录成功
- (void)passportDidLogin:(MiPassport *)passport{
NSLog(@”passport login succeeded, token:%@, token type:%@, expiration date:%@, encrypt algorithm:%@,
encrypt key:%@”, passport.accessToken, passport.tokenType, passport.expirationDate,
passport.encryptAlgorithm, passport.encryptKey);
}//登录失败
- (void)passport:(MiPassport *)passport failedWithError:(NSError *)error{
NSDictionary *errorInfo = [error userInfo];
NSLog(@”passport login failed with error: %d info %@”, [error code],
[errorInfo objectForKey: @"error_description"]);
}
// 用户取消登录
- (void)passportDidCancel:(MiPassport *)passport{
NSLog(@”passport login did cancel”);
}

//登出成功
- (void)passportDidLogout:(MiPassport *)passport{
NSLog(@”passport did log out”);
}

//获取code
- (void)passport:(MiPassport *)passport didGetCode:(NSString *)code{
NSLog(@”passport did get code: %@”, code);
}

//token过期
- (void)passport:(MiPassport *)passport accessTokenInvalidOrExpired:(NSError *)error{
NSLog(@”passport accesstoken invalid or expired”);
}

3. 初始化 MiPassport 对象

    第三方 App 可以在任何地方初始化 MiPassport，但推荐由一个全局的对象来持有 passport（如 AppDelegate），以方便用户在各个界面使用 passport 的信息。将登录信息持久化，可以减少用户登录的过程。

_passport = [[MiPassport alloc] initWithAppId:@”179887661252608″
redirectUrl:@”http://xiaomi.com” andDelegate:self];

4. 实现登录操作

    应用创建 MiPassport 对象后，只需调用 loginWithPermissions 方法即可实现 Implicit Flow 登录，即直接由客户端获取 Access Token 即相关信息。

- (IBAction)loginPassport:(id)sender {
[_passport loginWithPermissions:nil];
}

5. 获取code

    如果要实现Authorization Code流程登录，可以通过MiPassport中的applyPassCodeWithPermisions方法来获取。

- (IBAction)retriveCode:(id)sender {
[_passport applyPassCodeWithPermissions:nil];
}

6. 实现MPRequestDelegate

    在调用小米帐号Open API之前，应用需要实现该协议以处理请求的不同结果。

// 请求向服务器发送
- (void)requestLoading:(MPRequest *)request{
NSLog(@”request start loading”);
}// 请求收到服务器回复，开始接受数据
- (void)request:(MPRequest *)request didReceiveResponse:(NSURLResponse *)response{
NSLog(@”request did receive response”);
}
// 请求失败， error包含错误信息
- (void)request:(MPRequest *)request didFailWithError:(NSError *)error{
NSLog(@”request did fail with error code: %d”, [error code]);
if ([request.url hasSuffix:@"user/profile"]) {
}
else if ([request.url hasSuffix:@"user/relation"]){
}
}

// 请求成功，result为处理后的请求结果
- (void)request:(MPRequest *)request didLoad:(id)result{
NSLog(@”request did load: %@”, [result JSONRepresentation]);
if ([request.url hasSuffix:@"user/profile"]) {
}
else if ([request.url hasSuffix:@"user/relation"]){
}
}

// 请求成功，data为未经处理的服务器返回数据
- (void)request:(MPRequest *)request didLoadRawResponse:(NSData *)data{
NSLog(@”request did load raw response: %@”, data);
}

7. 实现请求小米帐号Open API操作

    应用登录成功后，通过创建的MiPassport对象调用request方法来实现对小米帐号API的请求。

- (IBAction)getUserInfo:(id)sender {
[_passport requestWithURL:@"user/profile" params:[NSMutableDictionary dictionaryWithObject:_passport.appId forKey:@"clientId"]
httpMethod:@”GET” delegate:self];
}

8. 登出小米帐号

    通过调用MiPassport的logout方法即可实现登出。