本文介绍如何在 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 协议的加速。
本节介绍如何创建项目,将声网 Unity SDK 集成进你的项目中。你的 Unity 需要是 2017 或更高版本。目前 FPA Unity SDK 仅支持移动端。
参考以下步骤或 Unity 官方操作指南创建一个 Unity 项目。若已有 Unity 项目,可以直接查看集成 SDK。
开始前确保你已安装 Unity。若未安装,点击此处下载。
打开 Unity,点击 New。
依次填入以下内容后,点击 Create project。 - Project name:项目名称 - Location:项目存储路径 - Organization:组织名称 - Template:项目类型。选择 3D。
通过以下步骤将声网 FPA Unity SDK 集成到你的项目中。
你必须初始化 SDK 并开启 FPA 服务之后才能实现 SDK 的全链路加速功能。声网 FPA Unity SDK 提供了 C# API,你可以通过 Unity script 的方式实现接入。
确保在项目中 import 以下命名空间。
using agora.fpa;
using agora.util;
创建一个 FpaProxyServiceConfig
对象,设置 App ID、token、日志等相关参数。
FpaProxyServiceConfig config = new FpaProxyServiceConfig();
// 设置 App ID
config.app_id = “<Your App ID>”;
// 设置 token。如果不开启 Token 鉴权,可不设置 token
config.token = “<Your Token>”;
通过 InitEventHandler
设置代理回调监听器并通过 Start
开启 FPA 服务。
internal IAgoraFpaProxyService _mFpaProxyService = null;
_mFpaProxyService = AgoraFpaProxyService.CreateAgoraFpaProxyService();
// 设置代理事件回调监听器
_mFpaProxyService.InitEventHandler(new UserEventHandler(this));
// 开启 FPA 服务
var ret = _mFpaProxyService.Start(config);
通过 OnAccelerationSuccess
回调、OnConnected
回调、OnDisconnectedAndFallback
回调、或 OnConnectionFailed
回调获取 FPA 服务状态。
internal class UserEventHandler : IAgoraFpaProxyServiceEventHandler
{
private readonly FpaServiceSample _serviceSample;
internal UserEventHandler(FpaServiceSample serviceSample)
{
_serviceSample = serviceSample;
}
// 在 FPA 代理加速成功时触发。你可以在回调中添加逻辑判断 FPA 服务状态并执行对应操作
public override void OnAccelerationSuccess(FpaProxyConnectionInfo info)
{
_serviceSample.Logger.UpdateLog(string.Format("OnAccelerationSuccess FpaProxyConnectionInfo connection_id: {0}, dst_ip_or_domain: {1}, dst_port: {2}, local_port: {3}, proxy_type: {4}",
connection_info.connection_id, connection_info.dst_ip_or_domain, connection_info.dst_port, connection_info.local_port, connection_info.proxy_type));
}
// 在成功连接 FPA 代理时触发。你可以在回调中添加逻辑判断 FPA 服务状态并执行对应操作
public override void OnConnected(FpaProxyConnectionInfo info)
{
_serviceSample.Logger.UpdateLog(string.Format("OnConnected FpaProxyConnectionInfo connection_id: {0}, dst_ip_or_domain: {1}, dst_port: {2}, local_port: {3}, proxy_type: {4}",
connection_info.connection_id, connection_info.dst_ip_or_domain, connection_info.dst_port, connection_info.local_port, connection_info.proxy_type));
}
// 在连接 FPA 代理失败且回退至本地连接时触发。你可以在回调中添加逻辑判断 FPA 服务状态并执行对应操作
public override void OnDisconnectedAndFallback(FpaProxyConnectionInfo info, FPA_FAILED_REASON_CODE reason)
{
_serviceSample.Logger.UpdateLog(string.Format("OnDisconnectedAndFallback FpaProxyConnectionInfo connection_id: {0}, dst_ip_or_domain: {1}, dst_port: {2}, local_port: {3}, proxy_type: {4} FPA_FAILED_REASON_CODE: {5}",
connection_info.connection_id, connection_info.dst_ip_or_domain, connection_info.dst_port, connection_info.local_port, connection_info.proxy_type, FPA_FAILED_REASON_CODE));
}
// 在连接 FPA 代理失败且连接未回退时触发。你可以在回调中添加逻辑判断 FPA 服务状态并执行对应操作
public override void OnConnectionFailed(FpaProxyConnectionInfo info, FPA_FAILED_REASON_CODE reason)
{
_serviceSample.Logger.UpdateLog(string.Format("OnConnectionFailed FpaProxyConnectionInfo connection_id: {0}, dst_ip_or_domain: {1}, dst_port: {2}, local_port: {3}, proxy_type: {4} FPA_FAILED_REASON_CODE: {5}",
connection_info.connection_id, connection_info.dst_ip_or_domain, connection_info.dst_port, connection_info.local_port, connection_info.proxy_type, FPA_FAILED_REASON_CODE));
}
}
本文以 System.Net
命名空间中的 HttpWebRequest
和 WebProxy
为例,通过 SDK 处理 HTTP 请求与响应。你也可以使用其他支持设置修改 HTTP 代理发送请求的 HTTP 库。
System.Net
。 Unity 原生的网络库 UnityWebRequest
不支持设置代理,因此无法与 FPA Unity SDK 配套使用。通过 setOrUpdateHttpProxyChainConfig
方法设置源站 IP 地址或域名与 chain ID 的映射表。
// 设置 FPA 服务的 chain ID,例如 123
// 设置源站 IP 地址或域名
// 设置源站端口,例如 80
// 设置是否允许此加速通道在 FPA 代理连接失败时回退到本地连接
private FpaChainInfo _fpaChainInfo = new FpaChainInfo("<Your IP or domain>", 80, 123, true);
FpaHttpProxyChainConfig http_config = new FpaHttpProxyChainConfig();
http_config.chain_array = new FpaChainInfo[1]{_fpaChainInfo};
http_config.chain_array_size = 1;
// 设置是否在 HTTP 本地代理在 FPA SDK 找不到源站对应的 chain ID 时回退到本地连接
http_config.fallback_when_no_chain_available = true;
ret = _mFpaProxyService.SetOrUpdateHttpProxyChainConfig(http_config);
通过 GetHttpProxyPort
方法获取 HTTP 代理端口。
// 初始化 HTTP 代理端口变量
ushort http_proxy_port = 0;
// 通过 GetHttpProxyPort 方法为 http_proxy_port 变量通过 reference 传值
_mFpaProxyService.GetHttpProxyPort(ref http_proxy_port);
新建一个 WebProxy
对象。将 port 设置为 HTTP 代理端口。
int32_http_proxy_port = Convert.ToInt32(http_proxy_port);
WebProxy proxyObject = new WebProxy("127.0.0.1", int32_http_proxy_port);
HttpWebRequest request = WebRequest.Create(url) as HttpWebRequest;
request.Proxy = proxyObject;
本文以 System.Net.Sockets
命名空间中的 TcpClient
为例,通过 SDK 处理 socket 请求与响应。你也可以使用其他 socket 库实现透明代理功能。
你已经完成了 SDK 初始化并开启了 FPA 服务。详见初始化 SDK 并开启 FPA 服务。
通过 getTransparentProxyPort
方法获取透明代理端口。
// 初始化 TCP 透明代理端口变量
ushort tcp_proxy_port = 0;
// 设置 FPA 服务的 chain ID,例如 123
// 设置源站 IP 地址或域名
// 设置源站端口,例如 80
// 设置是否允许此加速通道在 FPA 代理连接失败时回退到本地连接
private FpaChainInfo _fpaChainInfo = new FpaChainInfo("<Your IP or domain>", 80, 123, true);
// 通过 GetTransparentProxyPort 方法为 tcp_proxy_port 变量通过 reference 传值
// 在生产环境下,此处建议增加判断逻辑,在 ret < 0 时不使用 FPA 代理
var ret = _mFpaProxyService.GetTransparentProxyPort(ref tcp_proxy_port, _fpaChainInfo);
通过获取的端口连接透明代理。
int32_tcp_proxy_port = Convert.ToInt32(tcp_proxy_port);
TcpClient client = new TcpClient("127.0.0.1", int32_tcp_proxy_port);
成功连接之后,即可通过透明代理进行 socket 数据发送和接收。
GetHttpProxyPort
或 GetTransparentProxyPort
获取最新的端口。FpaProxyServiceConfig.logFilePath
属性设置。各平台的默认值如下:/storage/emulated/0/Android/data/<package name>/files/agora_fpa_sdk.log
App Sandbox/Library/caches/agora_fpa_sdk.log
详见 Unity 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;
}