本文介绍如何在 SDK 模式下实现加速。
全链路加速 SDK 的基本使用流程如下。
创建 FPA 服务并获取 FPA 服务的 chain ID、源站域名/IP 和端口。详见开通服务。
获取 App ID。详见获取 App ID。
(可选)获取 App 证书。详见获取 App 证书。
(可选)在 App 服务端生成 Token。详见生成 Token。
SDK 支持通过本地 HTTP 代理和本地 TCP 透明代理实现加速。
SDK 以本地 HTTP 代理的方式,将 app 通过 HTTP 库发出的 HTTP 请求和源站服务器返回的 HTTP 响应转化为 FPA SDK 与声网服务器之间的私有协议连接,从而实现基于 HTTP 协议的加速。
HTTP 库需要支持设置修改 HTTP 代理发送请求。
SDK 以本地 TCP 透明代理的方式,将 app 通过 socket 库建立的 TCP 连接转化为 FPA SDK 与声网服务器之间的私有协议连接,从而实现基于 TCP 协议的加速。
下文介绍如何使用 CocoaPods 集成 FPA iOS SDK。
开始前确保你已安装 CocoaPods。参考 Getting Started with CocoaPods 安装说明。
在终端里进入项目根目录,并运行 pod init
命令。项目文件夹下会生成一个 Podfile
文本文件。
打开 Podfile
文件,修改文件为如下内容。注意将 Your App
替换为你的 Target 名称。
# platform :ios, '9.0'
target 'Your App' do
pod 'AgoraFPA_iOS', '~> 1.2.1'
end
在终端内运行 pod install
命令安装 SDK。成功安装后,Terminal 中会显示 Pod installation complete!
,此时项目文件夹下会生成一个 xcworkspace
文件。
打开新生成的 xcworkspace
文件。
如果你需要使用离线 SDK 包集成,参考其它集成方式。
你必须初始化 SDK 并开启 FPA 服务之后才能实现 SDK 的全链路加速功能。
确保在项目中 import 以下类。
#import <AgoraFpaProxyService/FpaProxyService.h>
创建一个 FpaProxyServiceConfig
对象,设置 App ID、token、日志等相关参数。
FpaProxyServiceConfig *config = [[FpaProxyServiceConfig alloc] init];
// 设置 App ID
config.appId = @"<Your App ID>";
// 设置 token。如果不开启 Token 鉴权,可不设置 token 属性
config.token = @"<Your token>";
// 设置日志级别
config.logLevel = FpaLogLevelInfo;
// 设置日志文件储存地址
NSString *docDir = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *logFile = [NSString stringWithFormat:@"%@/fpa.log",docDir];
config.logFilePath = logFile;
// 设置日志文件大小
config.fileSize = 1024;
设置代理事件回调监听器并开启 FPA 服务。
// 设置代理事件回调监听器
[[FpaProxyService sharedFpaProxyService] setupDelegate:(id<FpaProxyServiceDelegate>)self];
// 开启 FPA 服务
[[FpaProxyService sharedFpaProxyService] startWithConfig:config];
通过 onAccelerationSuccess
回调、onConnected
回调、onDisconnectedAndFallback
回调、onConnectionFailed
回调获取 FPA 服务的状态。
- (void)onAccelerationSuccess:(FpaProxyServiceConnectionInfo * _Nonnull)connectionInfo {
//在 FPA 代理加速成功时触发。你可以在此处添加逻辑判断 FPA 服务状态并执行对应操作
}
- (void)onConnected:(FpaProxyServiceConnectionInfo * _Nonnull)connectionInfo {
//在成功连接 FPA 代理时触发。 你可以在此处添加逻辑判断 FPA 服务状态并执行对应操作
}
- (void)onDisconnectedAndFallback:(FpaProxyServiceConnectionInfo * _Nonnull)connectionInfo reason:(FpaFailedReason)reason {
//在连接 FPA 代理失败且回退至本地连接时触发。 你可以在此处添加逻辑判断 FPA 服务状态并执行对应操作
}
- (void)onConnectionFailed:(FpaProxyServiceConnectionInfo * _Nonnull)connectionInfo reason:(FpaFailedReason)reason {
// 在连接 FPA 代理失败且连接未回退时触发。你可以在此处添加逻辑判断 FPA 服务状态并执行对应操作
}
本文以 AFNetworking 库为例,通过 SDK 处理 HTTP 请求与响应。你也可以使用其他支持设置修改 HTTP 代理发送请求的 HTTP 库。
通过 setOrUpdateHttpProxyChainConfig
方法设置源站 IP 地址或域名与 chain ID 的映射表。
FpaHttpProxyChainConfig *httpConfig = [[FpaHttpProxyChainConfig alloc] init];
NSArray *casArray = @[@""];
NSMutableArray *array = [NSMutableArray array];
// 设置源站 IP 地址或域名与 chain ID 的映射表。
// 设置 FPA 服务的 chain ID,例如 123
FpaChainInfo *info = [FpaChainInfo fpaChainInfoWithChainId:201
// 源站 IP 地址或域名
address:@"<Your domain or IP>"
// 源站端口,例如 30113
port:30113
// 设置是否允许此加速通道在 FPA 代理连接失败时回退到本地连接
enableFallback:YES
// 是否开启加密传输回退。这里选择关闭
enableCrypto:NO
userCas:casArray
verifyHost:@""];
[array addObject:info];
httpConfig.chainArray = [array copy];
// 开启 HTTP 代理在 FPA SDK 找不到源站对应的 chain ID 时的回退机制
httpConfig.fallbackWhenNoChainAvailable = YES;
// 调用 setOrUpdateHttpProxyChainConfig 开启设置
[[FpaProxyService sharedFpaProxyService] setOrUpdateHttpProxyChainConfig:httpConfig];
创建一个 NSURLSessionConfiguration
对象并设置 connectionProxyDictionary
的属性。
// 创建 NSURLSessionConfiguration 对象
NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
// 设置 connectionProxyDictionary 属性,将 NSURLSessionConfiguration 的代理设置为 FpaProxyService 提供的内部 HTTP 代理
configuration.connectionProxyDictionary = @{
// 设置 HTTP 代理。在生产环境下,此处建议增加判断逻辑,在 httpProxyPort<=0 时不使用 FPA 代理
(id)kCFNetworkProxiesHTTPEnable:@YES,
(id)kCFNetworkProxiesHTTPProxy:@"127.0.0.1",
(id)kCFNetworkProxiesHTTPPort:@([[FpaProxyService sharedFpaProxyService] httpProxyPort]),
// 设置 HTTPS 代理。在生产环境下,此处建议增加判断逻辑,在 httpProxyPort<=0 时不使用 FPA 代理
@"HTTPSEnable":@YES,
@"HTTPSProxy":@"127.0.0.1",
@"HTTPSPort":@([[FpaProxyService sharedFpaProxyService] httpProxyPort]),
};
使用上一步创建的 NSURLSessionConfiguration
对象创建并初始化 AFHTTPSessionManager
对象。
// 创建 AFHTTPSessionManager 对象。Session 配置使用上一步创建的 NSURLSessionConfiguration 对象。
AFHTTPSessionManager *manager = [[AFHTTPSessionManager alloc] initWithSessionConfiguration:configuration];
获得 AFHTTPSessionManager
对象后,你可以使用 AFNetworking 的原生方法创建 HTTP 请求。具体参考 AFNetworking 官方文档。
本文以 CocoaAsyncSocket
库为例,通过 SDK 处理 socket 请求与响应。你也可以使用其他 socket 库实现透明代理功能。
通过 getTransparentProxyPortWithChainId
方法获取透明代理端口。
// 调用 getTransparentProxyPort 获取透明代理的端口
NSArray *casArray = @[@""];
// 设置 FPA 服务的 chain ID,例如 123
FpaChainInfo *t_info = [FpaChainInfo fpaChainInfoWithChainId:123
// 设置源站域名或 IP
address:@"<Your IP or domain>"
// 通过 port 参数设置源站端口,例如 30103
port:30103
// 设置是否允许此加速通道在 FPA 代理连接失败时回退到本地连接
enableFallback:YES
// 是否开启加密传输回退。这里选择关闭
enableCrypto:NO
userCas:casArray
verifyHost:@""];
];
// 在生产环境下,此处建议增加判断逻辑,在 t_port <=0 时不使用 FPA 代理
self.t_port = [[FpaProxyService sharedFpaProxyService] getTransparentProxyPortWithChainInfo:t_info];
通过获取的端口连接透明代理。
self.clientSocket = [[GCDAsyncSocket alloc] initWithDelegate:self delegateQueue:dispatch_get_global_queue(0, 0)];
[self.clientSocket connectToHost:@"127.0.0.1" onPort:self.t_port viaInterface:nil withTimeout:-1 error:&error];
成功连接之后,即可通过透明代理进行 socket 数据发送和接收。
在 SDK 下载 页面下载最新版本的声网 FPA SDK,并解压。将包中 ./libs
路径下的动态库复制到你的项目目录。
打开 Xcode,进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单。点击 + > Add Other… > Add Files 添加包中的 .framework
动态库,并确保添加的动态库 Embed 属性设置为 Embed & Sign。
添加完成后,项目会自动链接所需系统库。
FpaProxyServiceConfig.logFilePath
属性设置。详见 iOS SDK API 参考。
你需要自行在 app 服务端部署 Token 生成器。
Token 鉴权的基本逻辑如下图所示。
声网在 GitHub 上提供一个开源的 AgoraDynamicKey 仓库,支持在你自己的服务器上生成 Token。
语言 | 算法 | 核心类 | 生成示例 |
---|---|---|---|
C++ | HMAC-SHA256 | FpaTokenBuilder | FpaTokenBuilderSample.cpp |
Python3 | HMAC-SHA256 | FpaTokenBuilder | fpa_token_builder_sample.py |
本节介绍生成 Token 的 API 参数和描述。 以 C++ 为例:
static std::string BuildToken(
const std::string& app_id,
const std::string& app_certificate);
参数 | 描述 |
---|---|
app_id |
你在声网控制台创建项目时生成的 App ID。 |
app_certificate |
你的项目的 App 证书。 |
下面的 C++ 示例代码展示了如何使用 FpaTokenBuilder
类生成 FPA Token。
#include <iostream>
#include "../src/FpaTokenBuilder.h"
using namespace agora::tools;
int main(int argc, char const *argv[]) {
(void)argc;
(void)argv;
// 你的 App ID
std::string app_id = "970CA35de60c44645bbae8a215061b33";
// 你的 App 证书
std::string app_certificate = "5CFd2fd1755d40ecb72977518be15d3b";
std::string result;
// 生成 FPA token
result = FpaTokenBuilder::BuildToken(app_id, app_certificate);
std::cout << "Token with FPA service:" << result << std::endl;
}