Mail.Ru iOS SDK

SDK 允许第三方 iOS 应用程序的用户通过 Mail.Ru 账户进行身份验证。之后，可以使用身份验证代码获取用户信息，如 OAuth 2.0 身份验证指南中所述。

项目页面和源代码：https://github.com/mailru/mail-auth-sdk-ios。

支持 iOS 9.0 及以上版本。

准备使用

在开始使用 Mail.Ru SDK 之前，您需要在 此处创建应用程序。保存您的 应用程序 ID 并填写必填字段。

在 iOS 应用程序中设置 URL 方案

为了通过 Mail.Ru SDK 进行身份验证，您需要设置您应用程序的 URL 方案。为此，请将以下代码添加到项目文件的 Info.plist 中的 URL Types → URL Schemes 部分中

• 用于从 Mail.Ru 应用程序返回结果的身份验证方案的方案。在初始化 SDK 时，需要在 returnScheme 属性中指定此方案。
• 如果您选择通过 SafariViewController 进行身份验证，那么也需要在应用程序设置中的 redirect_uri 字段添加此方案。

这些方案可以相同，此时只需在 Info.plist 中添加一个条目即可。

将 mr-mail-oauth2 方案添加到 Info.plist 文件的 LSApplicationQueriesSchemes 部分。这使得 SDK 能够判断 Mail.Ru 应用程序是否已安装在设备上，并通过它进行身份验证。

有关这些设置的更多信息，您可以在 Apple 手册中找到，请参阅 iOS 应用程序编程指南 和 信息属性列表键参考。

将 SDK 连接到应用

您可以使用 Cocoapods、Carthage 或不使用依赖关系管理器来集成库。您可以在 samples 文件夹中找到集成和使用示例。

使用 CocoaPods

CocoaPods 是一个用于 Objective-C 和 Swift 项目中的依赖关系管理器，简化了使用第三方库，如 Mail.Ru SDK 的过程。有关更多信息，请参阅《入门》指南。

将以下行添加到您的 Podfile 中：

pod 'MRMailSDK'

然后执行以下命令：

pod install

使用 Carthage

将以下行添加到您的 Cartfile 中：

github "mailru/mail-auth-sdk-ios"

然后执行以下命令：

carthage update

按照说明将构建好的框架连接到项目。

不使用依赖关系管理器

将项目 mr-mail-sdk.xcodeproj 作为子项目添加到您的项目中。然后找到您的项目属性的设置 General → Embedded Binaries，并添加 mr-mail-sdk.framework。

使用 SDK

初始化

将此代码放入 Application Delegate 类中，用您应用的配置项替换其中的行

#import <MRMailSDK/MRMailSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    MRMailSDK *mailSDK = [MRMailSDK sharedInstance];
    [mailSDK initializeWithClientID:@"bddc421472584782aacd6d7549cbc31b"
                        redirectURI:@"sample-auth-callback://"];
    mailSDK.returnScheme = @"sample-auth-callback";
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    return [[MRMailSDK sharedInstance] handleURL:url
                               sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                                      annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
}

@end

Swift 中的相同内容

import MRMailSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, MRMailSDKDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        let mailSDK = MRMailSDK.sharedInstance()
        mailSDK.initialize(withClientID: "bddc421472584782aacd6d7549cbc31b", redirectURI: "sample-auth-callback://")
        mailSDK.returnScheme = "sample-auth-callback"
        return true
    }

    func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
        let sourceApplication = options[.sourceApplication] as? String
        let annotation = options[.annotation] as? String
        return MRMailSDK.sharedInstance().handle(url, sourceApplication: sourceApplication, annotation: annotation)
    }
}

通过 Mail.Ru 账户进行身份验证

设置一个代理，身份验证的结果将被传递给它。

MRMailSDK.sharedInstance.delegate = self;

调用 authorize 方法进行身份验证

[MRMailSDK.sharedInstance authorize];

或使用现成的 MRMailSignInButton 按钮。

如果用户安装了 Mail.Ru 邮件应用程序，并在初始化时设置了 returnScheme 参数，则身份验证将直接通过它进行，无需输入用户名和密码。否则，将打开网页界面。通过设置 internalAuthMode 参数，可以指定网页界面在 SFSafariViewController 或 SDK 内置的 Web 视图中打开。

身份验证完成后，将调用代理的一个方法。在身份验证成功的情况下，SDK 将调用 -[MRMailSDKDelegate mrMailSDK:authorizationDidFinishWithCode:] 方法，并将身份验证代码传递给它。该代码可以用来交换令牌，然后可以使用令牌按照指南中的说明获取用户信息，该指南描述了 OAuth 2.0 身份验证。

身份验证错误

在发生错误的情况下，将调用方法 -[MRMailSDKDelegate mrMailSDK:authorizationDidFailWithError:]。可能出现以下错误代码

• kMRSDKUninitializedErrorCode (0) — SDK 未初始化。
• kMRSDKIncorrectClientIdErrorCode (1) — 应用程序 ID 错误。
• kMRSDKAuthorizationAlreadyInProgressErrorCode (2) — 身份验证流程已启动但尚未完成。
• kMRSDKOAuthErrorCode (3) — OAuth API 错误。
• kMRSDKNetworkErrorCode (4) — 网络错误。
• kMRSDKCanceledByUserErrorCode (5) — 身份验证流程被用户中断。
• kMRSDKUnauthorizedApplicationErrorCode (6) — 您的应用程序没有身份验证权限。
• kMRSDKExternalOAuthDisabledErrorCode (7) — OAuth 身份验证已禁用。
• kMRSDKExternalOAuthRefuseErrorCode (8) — OAuth 身份验证被拒绝。