React Native接入指南

1.1 开通服务

请参考快速入门开通HTTPDNS。

1.2 获取配置

请参考开发配置在EMAS控制台开发配置中获取AccountId/SecretKey/AESSecretKey等信息，用于初始化SDK。

2.1 安装插件

在 React Native 项目根目录执行：

npm install @alicloud-emas/httpdns-react-native

如果使用 Yarn：

yarn add @alicloud-emas/httpdns-react-native

2.2 Android 配置

Android 端无需额外原生代码配置。

插件会通过 ContentProvider 在应用启动早期自动注入 React Native 网络模块使用的 OkHttpClient，并配置自定义 DNS 解析器。业务侧继续使用原有网络请求代码即可。

如果您的项目开启了代码混淆，请在 Android 工程的 ProGuard/R8 配置中添加：

-keep class com.alibaba.sdk.android.**{*;}

2.3 iOS 配置

source 'https://github.com/aliyun/aliyun-specs.git'
source 'https://github.com/CocoaPods/Specs.git'

cd ios
pod install

#import <httpdns-react-native/AliyunHttpDnsRN.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [AliyunHttpDnsRN install];

  // 其他 React Native 初始化代码
  return YES;
}

3.1 初始化前配置

插件采用“先配置，后初始化”的模式。以下配置建议在调用 init 前设置，init 内部会统一应用这些配置并构建 HTTPDNS 服务实例。

import * as AliyunHttpDns from '@alicloud-emas/httpdns-react-native';

AliyunHttpDns.setHttpsRequestEnabled(true);
AliyunHttpDns.setReuseExpiredIPEnabled(true);

await AliyunHttpDns.init({
  accountId: 123456,
  secretKey: 'your_secret_key',
});

3.2 配置预解析域名

初始化完成后，可以配置热点域名预解析，减少后续请求的解析时延。

AliyunHttpDns.setPreResolveHosts(['www.aliyun.com'], 'auto');

3.3 发起网络请求

初始化完成后，插件会自动完成 React Native 网络请求链路的 DNS 接入。业务侧使用 fetch、XMLHttpRequest、Axios 等基于 React Native 网络模块的请求时，无需手动调用解析接口，继续使用原有 React Native 网络请求方式即可：

import axios from 'axios';

// 使用 fetch
const response = await fetch('https://www.aliyun.com');

// 使用 Axios
const axiosResponse = await axios.get('https://www.aliyun.com');

5.1 init

通过此接口构建 HTTPDNS 服务实例。请确保在使用 HTTPDNS 解析能力前完成初始化，建议在应用启动阶段调用。React Native 插件会在初始化时将已设置的配置项统一应用到底层 Android/iOS HTTPDNS SDK。

const success = await AliyunHttpDns.init({
  accountId: 123456,
  secretKey: 'your_secret_key', // 可选，开启鉴权解析时配置
  aesSecretKey: 'your_aes_secret_key', // 可选，开启加密解析时配置
});

参数：

返回值：

5.2 setLogEnabled

本地调试日志开关。可以开启调试日志排查解析相关问题，上线时建议关闭。

AliyunHttpDns.setLogEnabled(true);

5.3 setHttpsRequestEnabled

设置 SDK 内部向服务端发起解析请求时，是否使用 HTTPS 协议。若不调用该接口，默认使用 HTTP 协议。

AliyunHttpDns.setHttpsRequestEnabled(true);

5.4 setPersistentCacheIPEnabled

设置是否启用持久化缓存。持久化缓存功能用于优化启动后的域名解析环节耗时，进而提升首屏加载速度。

开启后，HTTPDNS 会将上一次解析到的结果保存到本地持久层。App 重启后，每个域名首次解析会优先从持久层获取缓存结果，以实现更快的解析效率。

AliyunHttpDns.setPersistentCacheIPEnabled(true);
AliyunHttpDns.setPersistentCacheIPEnabled(true, 86400);

参数：

5.5 setReuseExpiredIPEnabled

设置是否允许解析接口返回 TTL 过期的缓存解析结果。

开启后，SDK 在缓存过期时可以先返回已过期的缓存 IP，以减少 DNS 环节处理时间，并刷新该域名的解析结果。

AliyunHttpDns.setReuseExpiredIPEnabled(true);

5.6 setPreResolveAfterNetworkChanged

设置网络环境变化后，是否自动刷新域名解析结果。

当设备网络变化时，SDK 会监听网络变化事件并根据策略处理缓存。开启该功能后，SDK 会在网络切换后自动刷新解析结果，降低域名解析环节耗时，进而提升请求性能。

AliyunHttpDns.setPreResolveAfterNetworkChanged(true);

5.7 setRegion

设置 HTTPDNS 启动服务节点。如果 App 需要在海外环境使用 HTTPDNS，可以主动设置启动服务节点。设置后，SDK 会使用该节点进行域名解析和后续调度节点列表更新。

AliyunHttpDns.setRegion('cn');

取值包括：cn、hk、sg、de、us。默认无需设置，SDK 内部会根据客户端网络进行调度。

5.8 setTimeoutInterval

设置域名解析请求超时时间，单位为秒。该配置只影响 HTTPDNS SDK 向服务端发起的解析请求，不影响业务网络请求的超时时间。

AliyunHttpDns.setTimeoutInterval(2);

5.9 setIPRankingList

启用 IP 优选。指定域名对应服务的探测端口后，SDK 会对相应域名解析返回的 IP 列表进行 TCP 建连测速，并根据测速结果对 IP 列表进行动态排序。

首次触发 HTTPDNS 解析后立即获得的 IP 列表可能未经排序。该能力适用于对连接时延敏感的域名，启用前建议结合业务流量和服务端负载情况评估。

AliyunHttpDns.setIPRankingList({'www.aliyun.com': 443,});

5.10 configCacheTtlChanger

自定义解析结果 TTL。HTTPDNS SDK 默认使用域名解析结果中携带的 TTL 值作为缓存时间。通过该接口可以根据不同域名指定 TTL，从而改变 SDK 对解析结果的缓存时间。

AliyunHttpDns.configCacheTtlChanger({'www.aliyun.com': 300,});

5.11 setPreResolveHosts

设置预解析域名列表。在 App 启动并完成 SDK 初始化后，可以调用此接口设置后续可能会使用到的热点域名，以便 SDK 提前解析，减少后续域名解析时请求的时延。

如果在运行过程中调用，SDK 也会立即解析设置的域名列表，从而刷新这些域名的解析结果并记录到缓存中。

AliyunHttpDns.setPreResolveHosts(['www.aliyun.com'], 'auto');

参数：

5.12 getSessionId

获取当前 HTTPDNS 会话 ID。该 ID 可用于问题排查和日志关联。

const sessionId = await AliyunHttpDns.getSessionId();

返回值：

5.13 cleanHostCache

清除域名缓存。传入域名列表时，清除指定域名的缓存；不传参数或传入空数组时，清除全部域名缓存。

// 清除全部缓存
AliyunHttpDns.cleanHostCache();
// 清除指定域名缓存
AliyunHttpDns.cleanHostCache(['www.aliyun.com']);

5.14 setAuthCurrentTime

校正 App 签名时间。鉴权模式下，如果设备时间不准确，可能导致鉴权校验不通过。调用该接口后，SDK 会根据传入时间校正后续请求的签名时间。

校正操作在 App 的一个生命周期内生效，App 重启后需要重新设置。

const currentTime = Math.floor(Date.now() / 1000);
AliyunHttpDns.setAuthCurrentTime(currentTime);

参数 time 为 Unix 时间戳，单位为秒。