ArkWeb 第三方 Cookie 怎么管？智能防跟踪与绕过域名实践【鸿蒙心迹】

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

大家好，我是[晚风依旧似温柔]，新人一枚，欢迎大家关注~

本文目录：

• • 前言
  • 一、先分清两个问题：第三方 Cookie 和智能防跟踪不是一回事
  • 二、HarmonyOS 7 下先确认开发基线
  • 三、搭一个最小测试场景
  • 四、开启第三方 Cookie，再打开智能防跟踪
  • 五、怎么观察请求变化
  • 六、业务确实依赖这个域名怎么办
  • 七、业务恢复以后，别忘了删除绕过域名
  • 八、几个特别容易理解错的地方
  • • 1. ITP 不是“禁用 Cookie”
    • 2. 第三方域名不一定就是跟踪型网站
    • 3. 没有 Cookie，就观察不到“Cookie 被禁止携带”的差异
    • 4. 绕过列表不是当前 Web 组件的局部变量
  • 九、实际项目中怎么排查
  • 十、隐私功能不能替代隐私合规说明
  • 开发经验总结

前言

H5 页面接入统计、登录、内容分发等第三方服务后，经常会出现第三方 Cookie。真正麻烦的地方不只是“Cookie 能不能用”，而是如何在业务兼容与隐私保护之间建立清晰边界。

ArkWeb 提供了智能防跟踪（Intelligent Tracking Prevention，下面简称 ITP）能力。按照华为官方文档的定义，当跟踪型网站作为第三方插入到其他网页时，其发送的网络请求将禁止携带 Cookie。同时，应用还能获得拦截结果，并为确有业务需要的域名配置绕过列表。该能力默认没有开启。

这次我们不讨论一整套 Web 隐私体系，只做一个最小实践：在 HarmonyOS 7 的 ArkWeb 页面中开启智能防跟踪，观察被识别的跟踪域名，再通过绕过域名列表验证策略变化。

本文代码依据当前华为官方公开文档整理，没有声称已经在具体工程或真机上编译、运行。实际项目仍应使用自己的 H5、SDK 与目标设备完成验证。

一、先分清两个问题：第三方 Cookie 和智能防跟踪不是一回事

在一个典型 H5 页面里，可以先用一个简单结构理解请求关系：

https://www.example-a.com/index.html
│
├── example-a.com 自己的资源
│
└── tracker.example-b.com 的脚本 / 图片 / iframe

本文把顶层页面所在的 example-a.com 看作当前页面上下文，把页面中另外加载的 example-b.com 作为第三方资源来观察。

这里比较容易出现一个理解偏差：ArkWeb 的智能防跟踪并不等于“关闭所有第三方 Cookie”。

华为官方对 ITP 的描述有两个限定词：一是“跟踪型网站”，二是“作为第三方插入其他网页”。也就是说，开启 ITP 后需要关注的是被 ArkWeb 识别为跟踪型网站的第三方请求，而不能简单理解成所有跨域请求都会失去 Cookie。

ArkWeb 另外还有 WebCookieManager.putAcceptThirdPartyCookieEnabled()，用于设置是否允许发送和接收第三方 Cookie。华为官方 ArkWeb FAQ 在处理依赖第三方 Cookie 的 H5 页面时，也给出了这个接口的使用示例。

因此可以把两个控制层次分开：

这也是本文实践最核心的思路：测试时先明确允许第三方 Cookie，再开启 ITP，这样才容易把“第三方 Cookie 总开关”和“智能防跟踪策略”区分开。

二、HarmonyOS 7 下先确认开发基线

华为当前的 HarmonyOS 升级适配指南明确说明：HarmonyOS 7.0 对应 API 26.0.0，并建议开发者升级到对应开发套件完成应用适配。

本文因此按下面的开发基线组织代码：

• 系统背景：HarmonyOS 7.0
• API 基线：API 26.0.0
• Web 能力：ArkWeb
• ArkTS 导入：@kit.ArkWeb
• Web 控制对象：webview.WebviewController
• Cookie 管理：webview.WebCookieManager
• 在线 H5 所需权限：ohos.permission.INTERNET

需要特别说明一个版本问题：当前能够直接核验的华为“使用智能防跟踪功能”指南确认了本文所使用的 ITP 接口，但该指南正文没有展示这些接口各自的历史首发 API Level。因此本文只把 HarmonyOS 7 / API 26.0.0 当前可使用作为兼容性基线，不把第三方资料中的历史首发版本数字写进结论。

如果项目的 compatibleSdkVersion 低于当前开发基线，还应在对应 SDK 的官方 API Reference 中再次确认接口起始版本，不能因为 API 26.0.0 可以调用，就反推所有历史版本都支持。

三、搭一个最小测试场景

为了加载在线测试页，应用首先需要网络权限。华为 ArkWeb FAQ 明确指出，Web 组件访问网络资源时需要在 module.json5 中声明 ohos.permission.INTERNET。

最小配置可以围绕网络权限展开：

{
"module": {
// 其他配置省略
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]
}
}

然后准备一个在线测试页面。为了避免把“任意第三方域名”错误地说成“跟踪域名”，测试页不要预设 ArkWeb 一定会拦截某个自己随便创建的域名。

更可靠的测试方法是：

测试页本身并不复杂。例如：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>ArkWeb ITP Test</title>
</head>
<body>
<h2>ArkWeb ITP Test Page</h2>

<!– 替换成测试环境中实际存在的第三方资源 –>
<img
src="https://tracker.example-b.com/pixel"
alt="third-party resource">

<p>请结合 ArkWeb 回调和服务端请求日志观察 Cookie 行为。</p>
</body>
</html>

这里的 tracker.example-b.com 只是展示测试拓扑的占位域名，不能据此认定它会被 ArkWeb 判定为跟踪网站。真正的判定结果应该看 ArkWeb 的 ITP 回调。

这点很重要。如果随便准备两个域名，发现开启 ITP 前后没有区别，并不能直接得出“智能防跟踪无效”的结论，因为第三方域名本身可能没有进入 ITP 的处理范围。

四、开启第三方 Cookie，再打开智能防跟踪

先把第三方 Cookie 的测试基线固定下来。

华为官方 FAQ 给出的方式是调用：

webview.WebCookieManager.putAcceptThirdPartyCookieEnabled(true);

官方示例把 Cookie 配置放在 aboutToAppear() 中。

接下来创建一个最小 ArkUI 页面：

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
controller: webview.WebviewController =
new webview.WebviewController();

private trackerHost: string = 'tracker.example-b.com';

aboutToAppear(): void {
// 为了观察 ITP 与普通第三方 Cookie 控制的区别，
// 测试阶段明确允许第三方 Cookie。
webview.WebCookieManager.putAcceptThirdPartyCookieEnabled(true);
}

build() {
Column({ space: 8 }) {
Button('开启智能防跟踪')
.onClick(() => {
try {
this.controller.enableIntelligentTrackingPrevention(true);
console.info('ITP enabled');
} catch (error) {
console.error(
`enable ITP failed, code: ${(error as BusinessError).code}, ` +
`message: ${(error as BusinessError).message}`
);
}
})

Button('检查智能防跟踪状态')
.onClick(() => {
try {
const enabled =
this.controller.isIntelligentTrackingPreventionEnabled();
console.info(`ITP enabled: ${enabled}`);
} catch (error) {
console.error(
`check ITP failed, code: ${(error as BusinessError).code}, ` +
`message: ${(error as BusinessError).message}`
);
}
})

Web({
src: 'https://www.example-a.com/itp-test.html',
controller: this.controller
})
.onIntelligentTrackingPreventionResult((details) => {
console.info(
`ITP result: websiteHost=${details.host}, ` +
`trackerHost=${details.trackerHost}`
);
})
.layoutWeight(1)
}
.width('100%')
.height('100%')
}
}

其中 example-a.com 和 example-b.com 都需要换成自己的测试环境。

真正需要关注的是三个接口。

enableIntelligentTrackingPrevention(true) 用来开启当前 Web 组件的智能防跟踪功能。官方说明该功能默认没有开启；isIntelligentTrackingPreventionEnabled() 可以查询当前 Web 页面是否开启；onIntelligentTrackingPreventionResult 则在 ITP 工作时把相关网站域名和跟踪型网站域名回调给应用。

这里不要只盯着页面有没有显示异常。对于 ITP 测试而言，回调里的 host 和 trackerHost 比“页面看起来有没有变化”更有定位价值。

五、怎么观察请求变化

如果只看页面 UI，很难判断 Cookie 到底发生了什么变化。

华为官方资料说明，ArkWeb 可以通过 DevTools 调试前端页面；开发者可以借助 DevTools 分析网页请求和前端行为。官方 FAQ 同样建议在 Web 页面异常定位时使用 DevTools。

测试时建议固定同一个页面和同一组请求，做三组对照：

场景 A：允许第三方 Cookie，关闭 ITP
场景 B：允许第三方 Cookie，开启 ITP
场景 C：开启 ITP，同时把目标域名加入绕过列表

观察时重点看两处。

一处是 ArkWeb 的：

.onIntelligentTrackingPreventionResult((details) => {
console.info(`websiteHost=${details.host}`);
console.info(`trackerHost=${details.trackerHost}`);
})

另一处是 H5 的网络请求。对于测试环境中确认存在 Cookie 的第三方请求，可以结合 DevTools 和服务端请求日志对照请求头变化。

按照官方 ITP 定义，如果目标网站被识别为跟踪型网站，并且它以第三方形式出现在页面中，开启 ITP 后相关网络请求将禁止携带 Cookie。

这里应该记录“实际观察到什么”，而不是提前写死结果。特别是自建测试域名，如果没有触发 onIntelligentTrackingPreventionResult，应先确认它是否真的被 ArkWeb 识别为跟踪型网站。

六、业务确实依赖这个域名怎么办

隐私保护策略不能简单变成“一刀切”。

某些 H5 可能确实依赖第三方 Cookie 完成已有业务流程。华为官方 ArkWeb FAQ 也明确给出了通过 putAcceptThirdPartyCookieEnabled(true) 解决页面依赖第三方 Cookie 的场景。

对于已经开启 ITP、但经过业务和隐私评估后确实需要放行的域名，ArkWeb 提供了绕过域名列表。

官方示例使用的是静态接口：

webview.WebviewController
.addIntelligentTrackingPreventionBypassingList(hostList);

例如：

Button('加入 ITP 绕过列表')
.onClick(() => {
try {
const hostList: Array<string> = [
this.trackerHost
];

webview.WebviewController
.addIntelligentTrackingPreventionBypassingList(hostList);

console.info(`ITP bypass added: ${this.trackerHost}`);
} catch (error) {
console.error(
`add bypass failed, code: ${(error as BusinessError).code}, ` +
`message: ${(error as BusinessError).message}`
);
}
})

这里建议不要直接把一批第三方域名全部塞进去。

更稳妥的做法是先通过：

details.trackerHost

确认实际触发 ITP 的域名，再判断该域名对应的业务是否确实需要 Cookie。

另一个容易忽略的点是：官方明确说明这些绕过域名列表对整个应用生效，而不是只对某一个 Web 组件生效。

因此，一个页面为了兼容业务加入绕过列表，影响范围可能不止当前页面。实际工程最好把这类配置集中管理，而不是散落在多个页面组件中。

七、业务恢复以后，别忘了删除绕过域名

绕过列表不是只能增加。

ArkWeb 提供：

webview.WebviewController
.removeIntelligentTrackingPreventionBypassingList(hostList);

可以删除指定域名：

Button('删除 ITP 绕过域名')
.onClick(() => {
try {
const hostList: Array<string> = [
this.trackerHost
];

webview.WebviewController
.removeIntelligentTrackingPreventionBypassingList(hostList);

console.info(`ITP bypass removed: ${this.trackerHost}`);
} catch (error) {
console.error(
`remove bypass failed, code: ${(error as BusinessError).code}, ` +
`message: ${(error as BusinessError).message}`
);
}
})

如果测试结束，需要把此前通过添加接口设置的域名全部清掉，可以调用：

webview.WebviewController
.clearIntelligentTrackingPreventionBypassingList();

例如：

Button('清空 ITP 绕过列表')
.onClick(() => {
webview.WebviewController
.clearIntelligentTrackingPreventionBypassingList();

console.info('ITP bypass list cleared');
})

添加、删除和清空绕过列表都是华为官方智能防跟踪指南明确提供的能力。

从工程设计角度看，这组 API 更适合被当作隐私策略配置管理，而不是普通页面状态。特别是应用里存在多个 Web 组件时，更要记住它是应用级绕过列表。

八、几个特别容易理解错的地方

1. ITP 不是“禁用 Cookie”

enableIntelligentTrackingPrevention(true) 不能简单解释成 Cookie 总开关。

官方定义针对的是“跟踪型网站作为第三方插入其他网页”的场景。普通 Cookie 管理和 ITP 是两个不同层面的控制。

2. 第三方域名不一定就是跟踪型网站

这是测试时最容易误判的一点。

自己创建 a.example.com 和 b.example.com，让 A 请求 B，只能构造第三方请求关系，不能据此证明 B 会被 ArkWeb 的智能防跟踪能力识别为跟踪型网站。

所以测试程序一定要保留：

onIntelligentTrackingPreventionResult

让 ArkWeb 自己告诉应用发生了什么。

3. 没有 Cookie，就观察不到“Cookie 被禁止携带”的差异

如果第三方服务本来没有建立 Cookie，或者测试开始前已经通过其他策略禁止第三方 Cookie，那么开启 ITP 后再观察请求，很可能看不到有意义的差异。

这也是本文测试阶段显式调用：

webview.WebCookieManager
.putAcceptThirdPartyCookieEnabled(true);

的原因。

它的目的不是建议所有正式应用都无条件允许第三方 Cookie，而是建立一个可比较的测试基线。生产环境应该按照业务需求和隐私要求决定 Cookie 策略。

4. 绕过列表不是当前 Web 组件的局部变量

官方明确说明绕过列表作用于整个应用。

因此不建议把：

addIntelligentTrackingPreventionBypassingList()

理解成某个页面临时的“放行按钮”。

如果业务真的需要使用，最好维护清楚域名来源、业务用途和移除条件。

九、实际项目中怎么排查

遇到“开启智能防跟踪后 H5 某个功能不正常”时，可以按下面的顺序检查：

这样的排查顺序比直接“关掉 ITP 看看能不能恢复”更容易定位问题，也能避免为了兼容一个 H5 功能，把整个应用的防跟踪能力长期关闭。

十、隐私功能不能替代隐私合规说明

最后这个边界必须单独说。

开启 ArkWeb 智能防跟踪，只代表应用使用了一项 Web 隐私保护技术能力，并不意味着应用因此自动完成隐私合规。

华为官方《应用隐私保护》明确提出，应用处理个人数据时需要遵循公开透明、数据最小化、用户选择与控制等原则；应用采集个人数据时，应告知用户个人信息的使用方式，处理个人数据还需要满足相应的用户同意要求。

华为 AppGallery Connect 的 HarmonyOS 应用隐私政策配置文档也要求开发者根据实际个人信息处理情况如实填写，并在处理场景发生变化时及时更新隐私政策。

所以不能形成这样的逻辑：

开启 ITP
↓
应用不会跟踪用户
↓
不需要再说明第三方数据处理

正确的处理方式应该是分别解决两个问题：

技术层：
ArkWeb Cookie 策略
+ 智能防跟踪
+ 必要且受控的绕过列表

合规层：
实际收集什么
+ 为什么收集
+ 谁在处理
+ 是否向第三方提供
+ 如何告知用户并取得相应授权或合法性基础

尤其是为了业务兼容把某个域名加入 ITP 绕过列表以后，更应该重新检查这个第三方服务实际处理的数据，而不是把“技术上能够绕过”理解成“合规上可以直接绕过”。

开发经验总结

ArkWeb 的智能防跟踪接口本身并不复杂，真正需要弄清楚的是它与普通第三方 Cookie 管理之间的关系。

这次最小实践可以整理成四点。

第一，第三方 Cookie 与 ITP 分层处理。 WebCookieManager.putAcceptThirdPartyCookieEnabled() 管第三方 Cookie 的发送和接收能力，ITP 则进一步针对被识别为跟踪型网站的第三方场景进行处理。

第二，不要自己猜哪个域名是 tracker。 保留 onIntelligentTrackingPreventionResult，根据 ArkWeb 返回的 host 和 trackerHost 做定位。

第三，绕过列表要谨慎使用。 addIntelligentTrackingPreventionBypassingList()、removeIntelligentTrackingPreventionBypassingList() 和 clearIntelligentTrackingPreventionBypassingList() 提供了完整的管理能力，但官方明确说明该列表是应用级的。

第四，隐私技术措施和隐私合规是两件事。 ITP 可以减少特定第三方跟踪场景中的 Cookie 携带，但应用仍然需要根据实际数据处理行为完成隐私告知、最小化处理和用户控制。

如果正在维护一个包含多个第三方 H5、统计脚本或登录服务的 HarmonyOS 应用，可以先做一件很具体的事：打开 ITP 回调，把实际出现的 trackerHost 梳理出来，再逐个判断这些第三方依赖究竟是业务必需，还是可以直接移除。相比一上来就维护一张很长的绕过名单，这种方式更容易把 Cookie 策略真正管起来。

如果觉得有帮助，别忘了点个赞+关注支持一下~ 喜欢记得关注，别让好内容被埋没～