PIALibrary 1.1.3

PIALibrary 1.1.3

×

由 Davide De Rosa 维护。

PIALibrary 1.1.3

  • 作者：
  • Davide De Rosa

PIA logo

Private Internet Access

Private Internet Access 是全球领先的消费者 VPN 服务提供商。Private Internet Access 相信所有人都有不受限制的访问权，作为开源生态系统的坚定支持者，我们决定开源我们的 VPN 客户端。有关 PIA 服务的更多信息，请访问我们的网站 privateinternetaccess.com 或查看 Wiki。

Apple 平台客户端库

使用这个库，消费者可以轻松启用并与 Private Internet Access 服务进行通信。它提供了用于验证、购买计划、更新服务器、获取连接更新、处理 VPN 个人资料等功能的抽象接口。您还将找到用于离线测试库的模拟对象。

入门

该库已在 iOS 和 macOS 上进行了测试，并包括以下功能：

  • 认证
    • 方便的登录/注册视图控制器（仅限 iOS）
    • 应用内计划购买
  • 服务器列表处理
  • 网络连接
  • 可扩展的 VPN 个人资料
  • 持久偏好设置
  • 用于离线测试的模拟对象
  • 主题化
  • 方便的宏

安装

要求

  • iOS 9.0+ / macOS 10.11+
  • Xcode 9+ (Swift 4)
  • Git（预安装于Xcode命令行工具）
  • Ruby（预安装于macOS）
  • CocoaPods 1.5.0
  • SwiftGen
  • jazzy（可选，用于文档，为文档）

强烈建议使用由Homebrew提供 的Git和Ruby包。

CocoaPods

使用CocoaPods时，只需将以下内容添加到Podfile中

pod 'PIALibrary'

要包含其他非默认子spec

pod 'PIALibrary'
pod 'PIALibrary/VPN' # adds support for PIATunnel
pod 'PIALibrary/Mock'

测试

在本地上下载库代码库

$ git clone https://github.com/pia-foss/client-library-apple.git

假设您有一个工作良好的CocoaPods环境，设置库的工作空间只需要安装pod依赖项

$ pod install

之后，在Xcode中打开PIALibrary.xcworkspace，并运行在PIALibraryTests目标中找到的单元测试。在PIALibrary-iOS上按CMD+U也可以这样做。

示例

有一个包含用于测试库的简单项目的Demo目录。像往常一样，为CocoaPods做准备

$ pod install

然后打开Demo.xcworkspace。您可以使用WelcomeDemo-iOS目标测试与账户相关的业务，不出所料，这个目标是针对iOS的。

我们肯定希望稍后提供更全面的应用。

说明文档

由于其复杂度，库被拆分成了几个命名模块，分别是它们的使用上下文。核心（Core）和库（Library）模块构成了库的基础，是基本所需。

公共接口的完整说明文档可用于生成，并使用 jazzy 生成。安装 jazzy Ruby 晶石之后运行

$ gem install jazzy

进入存储库的根目录并运行

$ jazzy

生成的输出存储到 docs 目录中，格式为 HTML。

核心

在这里，您可以找到库构建其上的核心组件。它包括

  • 业务接口（例如 AccountProvider）
  • 网络模型（例如 AccountInfo）
  • 持久化模型
  • 回调（例如 LibraryCallback）
  • 公共通知
  • 实用工具（宏和扩展）

库

该模块是核心（Core）的默认实现。它有一个名为 Client 的入口点，这是进入大多数可用方法和变量的门户。

Client 容器提供对这些内容的访问

  • Client.environment - 库运行的环境
  • Client.configuration - 定义默认和短暂值/行为
  • Client.database - 持久层
  • Client.daemons - 包含来自被动更新的信息
  • Client.preferences - 持久偏好模型
  • Client.providers - 核心中的 *Provider 接口的当前实现

引导

在使用库之前，需要通过调用 Client.bootstrap() 的方式执行引导阶段。在执行引导之前，您需要调整库参数。

以下是一个典型的引导代码示例。

import PIALibrary

// ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
    Client.environment = .production
    Client.providers.vpnProvider = MockVPNProvider()
    Client.configuration.enablesServerUpdates = false
    Client.configuration.verifiesServersSignature = true
    Client.configuration.enablesConnectivityUpdates = false
    Client.bootstrap()
    // ...
    return true
}

它包括

  1. 将当前环境设置为生产端点
  2. 模拟 VPN 连接（尤其在 iPhone 模拟器上非常有用）
  3. 接收有关服务器更新的通知
  4. 验证服务器列表签名与 PIA 公钥
  5. 接收有关连接性的通知（例如公共 IP 地址）

记得在消费者生命周期结束时销毁库。

func applicationWillTerminate(_ application: UIApplication) {
    Client.dispose()
}

示例

登录PIA

// pack auth request
let credentials = Credentials(username: "user", password: "pass")
let request = LoginRequest(credentials: credentials)

// verify credentials against PIA services
Client.providers.accountProvider.login(with: request) { (user, error) in
    guard let user = user else {
        print("Login failed: \(error)")
        return
    }

    // success, print user info
    print("Account info: \(user.info)")
}

连接到VPN

// do this on simulator
Client.useMockVPNProvider()
Client.bootstrap()

// ...

// raw set VPN credentials (skip verify for this sample)
let credentials = Credentials(username: "user", password: "pass")
let user = UserAccount(credentials: credentials, info: nil)
Client.providers.accountProvider.currentUser = user

// establish VPN type (protocol)
let prefs = Client.preferences.editable()
prefs.vpnType = IPSecProfile.vpnType
prefs.commit()

// observe VPN updates
NotificationCenter.default.addObserver(forName: .PIADaemonsDidUpdateVPNStatus, object: nil, queue: nil) { (notification) in
    print("VPN status: \(Client.daemons.vpnStatus)")
}

// connect
Client.providers.vpnProvider.connect(nil)

获取公网IP通知

// enable passive connectivity updates
// ...
Client.configuration.enablesConnectivityUpdates = true
Client.bootstrap()

// observe connectivity updates
NotificationCenter.default.addObserver(forName: .PIADaemonsDidUpdateConnectivity, object: nil, queue: nil) { (notification) in
    guard let ip = Client.daemons.publicIP else {
        print("Unable to get public IP")
        return
    }
    print("Public IP: \(ip)")
}

VPN

VPN模块补充了Library模块中针对VPN配置的部分，通常基于iOS和macOS的NetworkExtension框架。

如今，它提供了PIATunnelProfile桥接功能，将我们的隧道实现集成到库中。在预引导代码中，执行以下操作以在Client.preferences.vpnType中将其启用为VPN类型。

let packetTunnelBundle = "com.example.MyApp.MyTunnel"
let group = "group.com.example"

var builder = PIATunnelProvider.ConfigurationBuilder(appGroup: group)
builder.cipher = .aes128cbc
builder.digest = .sha1
builder.handshake = .rsa2048
builder.mtu = 1350

Client.configuration.addVPNProfile(
    PIATunnelProfile(bundleIdentifier: packetTunnelBundle)
)
Client.preferences.defaults.vpnCustomConfigurations = [
    PIATunnelProfile.vpnType: builder.build()
]

to enable it as a VPN type in Client.preferences.vpnType.

Mock

使用模拟提供者，您可以在不接触真实业务的情况下模拟库的行为。例如，您可能希望在提交凭据到PIA网络服务之前测试应用中的登录代码。

库的每个区域都有一个模拟对应物

  • MockAccountProvider
  • MockServerProvider
  • MockVPNProvider
  • MockInAppProvider（内部使用）

配置完成后，在引导之前将模拟提供者放入Client.providers的适当字段中。例如

let mock = MockAccountProvider()
mock.mockPlan = .trial
mock.mockIsExpiring = true
mock.mockIsRenewable = true

Client.providers.accountProvider = mock
Client.bootstrap()

所有提供者都在Client中提供了快捷方式，因此您可以使用更简洁的方式

...
Client.useMockAccountProvider(mock)
Client.bootstrap()

对于应用程序内的模拟而言，这是唯一的方法，因为它不可定制的

Client.useMockInAppProvider()

UI

该模块的大部分内容更适用于我们自己的应用。该模块几乎只适用于iOS，包括

  • 有用的宏
  • 一些自定义视图和视图控制器
  • 表单验证
  • 主题支持
  • 欢迎视图控制器

Theme类帮助消费者应用符合一组样式。而不是显式设置颜色和字体，我们将排版定义集中到Theme.Palette（颜色）和Theme.Typeface（字体）中，然后使用Theme方法应用符号样式。

在此设置中，使用AutolayoutViewController允许在整个应用中动态更改主题。

PIAWelcomeViewController是一个快速用户界面，用于在应用程序内支持PIA服务的登录和注册。

Util

通用工具类和扩展。

已知问题

macOS支持

iOS和macOS两者键盘中存在一些被忽视的差异，这破坏了PIA公共密钥的加载，后者服务器验证所需。

贡献

通过为这个项目贡献，您同意在《贡献者许可协议》（CLA）中陈述的条款，请参阅此处。

更多详细信息请参阅CONTRIBUTING。

问题和拉取请求应使用以下模板：文件ISSUE和PULL REQUEST。

作者

许可

本项目采用MIT (Expat) 许可证，可在此处找到。

致谢

  • SwiftyBeaver - 版权所有 © 2015 Sebastian Kreutzberger
  • Gloss - 版权所有 © 2017 Harlan Kellaway
  • Alamofire - 版权所有 © 2014-2018 Alamofire Software Foundation (http://alamofire.org/)
  • ReachabilitySwift - 版权所有 © 2016 Ashley Mills