尧图网站建设 
Cloudflare Zaraz Web API 实战指南事件追踪、用户属性、电商漏斗与隐私同意完整实现【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsZaraz Web API 是 Cloudflare Zaraz 暴露在浏览器端的zaraz全局 JavaScript 接口用于上报自定义事件、写入用户属性、驱动电商漏斗事件以及管理隐私同意状态。本文以仓库中的 api.md 为骨架结合 README.md、configuration.md、patterns.md 与 gotchas.md 中的配套实现细节展开读完你将掌握zaraz.track()、zaraz.set()、zaraz.ecommerce()、zaraz.consent等全部核心方法的调用方式、底层异步行为、类型定义以及在 SPA、电商和 GDPR 场景下的最佳实践。一、认识 Zaraz Web API浏览器端的唯一入口Cloudflare Zaraz 是运行在边缘节点的服务端标签管理器第三方脚本分析、广告、聊天、营销工具在 Cloudflare 边缘执行而非用户浏览器页面只需加载一个端点客户端 JS 开销趋近于零见 README.md 中 Single HTTP request 与 No client-side JS overhead 两大核心概念。而zaraz全局对象正是页面侧与该边缘体系通信的桥梁。按照 api.md 的定义它是一个Client-side JavaScript API负责三类工作追踪事件tracking events——zaraz.track()设置属性setting properties——zaraz.set()管理同意managing consent——zaraz.consent。所有方法均为异步 fire-and-forget 风格调用后立即返回事件由 Zaraz 批量异步发送不会阻塞页面主线程。该参考文档位于仓库 api.md与其配套的配置说明见 configuration.md。二、zaraz.track()上报自定义事件zaraz.track()是使用频率最高的方法用于在页面中上报任意事件。它接受两个参数参数类型必填说明eventNamestring是事件名称如button_click、purchase、pageviewpropertiesobject否事件附带属性键值对形式后续可在工具端读取基础用法zaraz.track(button_click); zaraz.track(purchase, { value: 99.99, currency: USD, item_id: 12345 });第一个调用只上报事件名第二个调用额外携带了金额、币种、商品 ID 三个属性。事件名与属性命名需与 configuration.md 中配置的工具如 GA4、Facebook Pixel期望的事件保持一致例如 GA4 默认监听page_view、purchase、user_engagement。SPA 场景手动上报 pageview在单页应用中路由切换不会触发浏览器原生页面加载因此需要结合路由变化手动上报zaraz.track(pageview, { page_path: /products, page_title: Products }); // SPApatterns.md 给出了 React 中的完整实现在路由变化时调用zaraz.track(pageview, { page_path: pathname, page_title: document.title })。需要特别注意的是gotchas.md 提醒使用useEffect时必须把路由对象放入依赖数组否则路由变化不会重新触发上报const location useLocation(); useEffect(() { zaraz.track(pageview, { page_path: location.pathname }); }, [location]); // 必须包含依赖否则路由变化不触发对于 hash 路由#/pathZaraz 的 History Change 触发器无法自动捕获需要监听hashchange事件手动上报window.addEventListener(hashchange, () { zaraz.track(pageview, { page_path: location.pathname location.hash }); });三、zaraz.set()写入用户属性与会话级状态zaraz.set()用于设置用户级属性典型用途是用户识别与用户分群。它支持两种调用形式// 形式一单个键值对 zaraz.set(userId, user_12345); // 形式二批量对象 zaraz.set({ email: userexample.com, plan: premium, country: US });生命周期仅对当前页面会话生效按 api.md 的说明属性persist for page session在页面会话期间持续存在。gotchas.md 进一步强调属性仅按页面持久化每个页面加载都需要重新设置。因此建议把用户信息设置在页面加载后尽早执行确保后续事件都能携带上下文。登录 / 登出流程patterns.md 给出了标准的用户识别流程// 登录成功后 zaraz.set({ userId: user.id, email: user.email, plan: user.plan }); zaraz.track(login, { method: oauth }); // 登出时——设为 null无法真正清除 zaraz.set(userId, null);注意Zaraz 不支持真正删除已设置的属性登出时只能将值置为null。在工具端读取写入的属性会出现在 Zaraz 的数据上下文Data Layer中可在工具配置里通过嵌套路径读取。例如 gotchas.md 展示的{{client.__zarazTrack.user.plan}}四、zaraz.ecommerce()电商漏斗事件zaraz.ecommerce()是面向电商场景的专用事件方法第一个参数为事件类型第二个参数为商品/订单属性对象// 浏览商品 zaraz.ecommerce(Product Viewed, { product_id: SKU123, name: Widget, price: 49.99 }); // 加入购物车 zaraz.ecommerce(Product Added, { product_id: SKU123, quantity: 2, price: 49.99 }); // 完成下单 zaraz.ecommerce(Order Completed, { order_id: ORD-789, total: 149.98, currency: USD, products: [{ product_id: SKU123, quantity: 2, price: 49.99 }] });支持的标准事件按 api.md 的定义内置标准事件共 6 个覆盖从浏览到下单的完整漏斗事件名阶段Product Viewed商品浏览Product Added加入购物车Product Removed移除商品Cart Viewed查看购物车Checkout Started开始结算Order Completed完成下单patterns.md 给出了完整的漏斗映射表其中Checkout Started建议携带cart_id与products数组Order Completed建议携带order_id、total与products。自动映射到下游工具按 api.md 的说明这些标准电商事件会被Tools auto-map to GA4, Facebook CAPI, etc.自动映射到 GA4、Facebook CAPI 等工具。也就是说只要你在 configuration.md 中配置了 GA4Measurement ID: G-XXXXXXXXXX或 Facebook PixelPixel ID调用zaraz.ecommerce(Order Completed, ...)后Zaraz 会自动翻译成下游工具的对应转换事件如 GA4 的purchase、Facebook 的Purchase无需为每个工具单独写适配代码。这正是 Zaraz 相比手动埋点的核心价值——一处埋点多渠道分发。GTM 迁移对照如果是从 Google Tag Manager 迁移patterns.md 提供了逐行对照GTM 的dataLayer.push({event: purchase})对应zaraz.ecommerce(Order Completed, {...})GTM 的{{Page URL}}/{{Page Title}}对应{{system.page.url}}/{{system.page.title}}点击触发器对应 CSS selector 点击触发器。五、System Properties触发器可用的系统属性除自定义属性外Zaraz 内置了一套系统属性System Properties可在触发器、工具配置与数据层中直接引用。按 api.md 的列表{{system.page.url}} {{system.page.title}} {{system.page.referrer}} {{system.device.ip}} {{system.device.userAgent}} {{system.device.language}} {{system.cookies.name}} {{client.__zarazTrack.userId}}这些模板变量的作用场景包括触发器条件configuration.md 中的 Variable Match 触发器可按系统属性做条件判断例如按页面 URL 决定是否触发事件属性补充点击触发器可通过{{system.clickElement.text}}动态采集被点击元素的文本Type: Click CSS Selector: .buy-button Event: purchase_intent Properties: button_text: {{system.clickElement.text}}与zaraz.set()的数据打通{{client.__zarazTrack.userId}}说明客户端通过zaraz.set(userId, ...)写入的属性同样能进入系统属性命名空间供触发器读取。六、zaraz.consent隐私同意管理GDPR/CCPA 合规是 Zaraz 的核心卖点之一。zaraz.consent对象提供了同意状态的查询、设置与监听能力。完整 API 一览// 查询全部用途的同意状态 const purposes zaraz.consent.getAll(); // { analytics: true, marketing: false } // 展示同意弹窗 zaraz.consent.modal true; // Show modal // 批量设置同意 zaraz.consent.setAll({ analytics: true, marketing: false }); // 设置单个用途 zaraz.consent.set(marketing, true); // 监听同意变更 zaraz.consent.addEventListener(consentChanged, () { if (zaraz.consent.getAll().marketing) zaraz.track(marketing_consent_granted); });标准工作流按 api.md 定义的流程完整的同意管理分为四步Configure purposes in dashboard——在控制台Domain → Zaraz → Settings → Consent创建用途purpose如analytics、marketingMap tools to purposes——把各工具映射到对应用途Show modal / set programmatically——通过zaraz.consent.modal true展示弹窗或通过setAll()/set()编程式设置Tools fire when allowed——仅当用户同意后映射到该用途的工具才会触发。configuration.md 补充了关键配置项设置用途行为为 Do not load until consent granted未同意前不加载工具这是防止工具在授权前提前触发的关键开关。控制台默认的隐私特性包括IP AnonymizationIP 匿名化默认启用与Cookie Control通过同意用途控制。同意排查gotchas.md 提供了两个高频问题解法弹窗不出现手动清除同意 Cookie 后刷新页面document.cookie zaraz-consent; expiresThu, 01 Jan 1970 00:00:00 UTC; path/;; location.reload();工具在同意前触发把工具映射到同意用途并启用 Do not load until consent granted。七、zaraz.debug实时调试模式排查埋点问题时开启调试模式可以实时观察事件处理过程zaraz.debug true; zaraz.track(test_event); console.log(zaraz.tools); // 查看已加载的工具列表启用后zaraz.tools会暴露当前已加载的工具数组zaraz.consent.getAll()可打印同意状态。配合 configuration.md 的测试工作流效果最佳Preview Mode预览模式——不发布即可测试配置变更Debug Mode调试模式——zaraz.debug trueNetwork tab网络面板——过滤关键字 zaraz 观察请求。gotchas.md 还给出了完整的事件不触发排查清单检查工具是否启用绿色圆点、触发器条件是否满足、同意是否授予、凭据是否正确GA4 为G-XXXXXXXXXXFacebook Pixel 仅数字不能带fbpx_前缀。八、Cookie 方法读取浏览器 CookieZaraz 提供两个 Cookie 读取方法区别在于命名空间zaraz.getCookie(session_id); // 仅读取 Zaraz 命名空间下的 Cookie zaraz.readCookie(_ga); // 读取任意 Cookie如 GA 的 _gazaraz.getCookie(name)读取Zaraz namespaceZaraz 自身管理的 Cookiezaraz.readCookie(name)读取任意 Cookie可用于获取_ga等第三方分析 Cookie。九、异步行为批处理与 fire-and-forgetapi.md 明确All methods fire-and-forget——所有方法都是即发即忘的调用后立即返回不返回 Promise也不阻塞页面。事件会被**批量batched并异步asynchronously**发送zaraz.track(event1); zaraz.set(prop, value); zaraz.track(event2); // 三个调用会被一起批量发送这带来两个工程启示不要依赖返回值zaraz.track()没有回调或 Promise无法在其返回后同步确认发送成功验证应借助zaraz.debug或网络面板无需关心调用顺序同批次内的 set 与 track 会被合并处理因此可以放心地把属性设置和事件上报写在一起如登录后zaraz.set(...)zaraz.track(login, ...)连写。十、TypeScript 类型定义api.md 提供了完整的 TypeScript 类型声明可在项目中直接使用interface Zaraz { track(event: string, properties?: Recordstring, unknown): void; set(key: string, value: unknown): void; set(properties: Recordstring, unknown): void; ecommerce(event: string, properties: Recordstring, unknown): void; consent: { getAll(): Recordstring, boolean; setAll(purposes: Recordstring, boolean): void; set(purpose: string, value: boolean): void; addEventListener(event: consentChanged, callback: () void): void; modal: boolean; }; debug: boolean; tools?: string[]; getCookie(name: string): string | undefined; readCookie(name: string): string | undefined; } declare global { interface Window { zaraz: Zaraz; } }类型定义要点track()的属性参数是可选的properties?而ecommerce()的属性参数是必填的Recordstring, unknownset()通过函数重载同时支持键值对与批量对象两种形式tools声明为可选数组string[]对应调试模式下暴露的已加载工具列表通过declare global把zaraz挂到window上便于在任意 TS 文件中直接以window.zaraz访问同时也可将声明文件共享给团队复用。十一、综合实战把整套 API 用在一个页面里将以上 API 组合起来一个典型的电商页面初始化逻辑如下// 1. 初始化同意状态提前防止工具提前加载 zaraz.consent.setAll({ analytics: true, marketing: false }); // 2. 设置用户属性页面会话内持久 zaraz.set({ userId: user_12345, plan: premium, country: US }); // 3. SPA 路由变化上报 pageview zaraz.track(pageview, { page_path: /checkout, page_title: Checkout }); // 4. 电商漏斗事件自动映射到 GA4 / Facebook CAPI zaraz.ecommerce(Checkout Started, { cart_id: CART-456, total: 149.98, currency: USD, products: [{ product_id: SKU123, quantity: 2, price: 49.99 }] }); // 5. 用户同意营销用途后触发营销事件 zaraz.consent.addEventListener(consentChanged, () { if (zaraz.consent.getAll().marketing) zaraz.track(marketing_consent_granted); }); // 6. 出问题打开调试 zaraz.debug true;十二、使用限制与边界硬性限制configuration.md 与 gotchas.md 给出了两组限制数据资源限制事件属性 / 请求大小100KB同意用途Consent purposes20 个API 速率1000 req/sec性能注意gotchas.md 提醒页面加载变慢时优先检查工具数量超过 50 个工具会明显影响性能、禁用非必要的阻塞触发器、并将事件负载控制在 100KB 以内。不适合使用 Zaraz Web API 的场景gotchas.md 明确列出以下场景不应使用 Zaraz应改用 Cloudflare Workers 等方案服务端到服务端的追踪server-to-server tracking实时双向通信real-time bidirectional communication二进制数据传输binary data transmission认证流程authentication flows。这些场景需要完全控制数据处理的逻辑适合直接使用 Workers 实现README.md 中 Use Workers directly when 一节有更完整的判断标准。参考文件导航本文内容在仓库中对应的完整参考文档如下Zaraz Web API 参考本文主体track / set / ecommerce / consent / debug / Cookie / 类型定义Zaraz 概览与决策树Zaraz 是什么、何时使用、任务导向阅读顺序Zaraz 配置指南控制台配置、触发器、工具凭据、同意用途、限制Zaraz 实战模式SPA 追踪、用户识别、电商漏斗、A/B 测试、Worker 集成、GTM 迁移Zaraz 踩坑排查事件不触发、同意问题、工具特有问题、性能与限制Zaraz 参考实现摘要文档体系结构与改进说明cloudflare-deploy Skill 入口Zaraz 在整个 Cloudflare 部署技能树中的定位【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Zaraz Web API 实战指南：事件追踪、用户属性、电商漏斗与隐私同意完整实现
Cloudflare Zaraz Web API 实战指南事件追踪、用户属性、电商漏斗与隐私同意完整实现【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsZaraz Web API 是 Cloudflare Zaraz 暴露在浏览器端的zaraz全局 JavaScript 接口用于上报自定义事件、写入用户属性、驱动电商漏斗事件以及管理隐私同意状态。本文以仓库中的 api.md 为骨架结合 README.md、configuration.md、patterns.md 与 gotchas.md 中的配套实现细节展开读完你将掌握zaraz.track()、zaraz.set()、zaraz.ecommerce()、zaraz.consent等全部核心方法的调用方式、底层异步行为、类型定义以及在 SPA、电商和 GDPR 场景下的最佳实践。一、认识 Zaraz Web API浏览器端的唯一入口Cloudflare Zaraz 是运行在边缘节点的服务端标签管理器第三方脚本分析、广告、聊天、营销工具在 Cloudflare 边缘执行而非用户浏览器页面只需加载一个端点客户端 JS 开销趋近于零见 README.md 中 Single HTTP request 与 No client-side JS overhead 两大核心概念。而zaraz全局对象正是页面侧与该边缘体系通信的桥梁。按照 api.md 的定义它是一个Client-side JavaScript API负责三类工作追踪事件tracking events——zaraz.track()设置属性setting properties——zaraz.set()管理同意managing consent——zaraz.consent。所有方法均为异步 fire-and-forget 风格调用后立即返回事件由 Zaraz 批量异步发送不会阻塞页面主线程。该参考文档位于仓库 api.md与其配套的配置说明见 configuration.md。二、zaraz.track()上报自定义事件zaraz.track()是使用频率最高的方法用于在页面中上报任意事件。它接受两个参数参数类型必填说明eventNamestring是事件名称如button_click、purchase、pageviewpropertiesobject否事件附带属性键值对形式后续可在工具端读取基础用法zaraz.track(button_click); zaraz.track(purchase, { value: 99.99, currency: USD, item_id: 12345 });第一个调用只上报事件名第二个调用额外携带了金额、币种、商品 ID 三个属性。事件名与属性命名需与 configuration.md 中配置的工具如 GA4、Facebook Pixel期望的事件保持一致例如 GA4 默认监听page_view、purchase、user_engagement。SPA 场景手动上报 pageview在单页应用中路由切换不会触发浏览器原生页面加载因此需要结合路由变化手动上报zaraz.track(pageview, { page_path: /products, page_title: Products }); // SPApatterns.md 给出了 React 中的完整实现在路由变化时调用zaraz.track(pageview, { page_path: pathname, page_title: document.title })。需要特别注意的是gotchas.md 提醒使用useEffect时必须把路由对象放入依赖数组否则路由变化不会重新触发上报const location useLocation(); useEffect(() { zaraz.track(pageview, { page_path: location.pathname }); }, [location]); // 必须包含依赖否则路由变化不触发对于 hash 路由#/pathZaraz 的 History Change 触发器无法自动捕获需要监听hashchange事件手动上报window.addEventListener(hashchange, () { zaraz.track(pageview, { page_path: location.pathname location.hash }); });三、zaraz.set()写入用户属性与会话级状态zaraz.set()用于设置用户级属性典型用途是用户识别与用户分群。它支持两种调用形式// 形式一单个键值对 zaraz.set(userId, user_12345); // 形式二批量对象 zaraz.set({ email: userexample.com, plan: premium, country: US });生命周期仅对当前页面会话生效按 api.md 的说明属性persist for page session在页面会话期间持续存在。gotchas.md 进一步强调属性仅按页面持久化每个页面加载都需要重新设置。因此建议把用户信息设置在页面加载后尽早执行确保后续事件都能携带上下文。登录 / 登出流程patterns.md 给出了标准的用户识别流程// 登录成功后 zaraz.set({ userId: user.id, email: user.email, plan: user.plan }); zaraz.track(login, { method: oauth }); // 登出时——设为 null无法真正清除 zaraz.set(userId, null);注意Zaraz 不支持真正删除已设置的属性登出时只能将值置为null。在工具端读取写入的属性会出现在 Zaraz 的数据上下文Data Layer中可在工具配置里通过嵌套路径读取。例如 gotchas.md 展示的{{client.__zarazTrack.user.plan}}四、zaraz.ecommerce()电商漏斗事件zaraz.ecommerce()是面向电商场景的专用事件方法第一个参数为事件类型第二个参数为商品/订单属性对象// 浏览商品 zaraz.ecommerce(Product Viewed, { product_id: SKU123, name: Widget, price: 49.99 }); // 加入购物车 zaraz.ecommerce(Product Added, { product_id: SKU123, quantity: 2, price: 49.99 }); // 完成下单 zaraz.ecommerce(Order Completed, { order_id: ORD-789, total: 149.98, currency: USD, products: [{ product_id: SKU123, quantity: 2, price: 49.99 }] });支持的标准事件按 api.md 的定义内置标准事件共 6 个覆盖从浏览到下单的完整漏斗事件名阶段Product Viewed商品浏览Product Added加入购物车Product Removed移除商品Cart Viewed查看购物车Checkout Started开始结算Order Completed完成下单patterns.md 给出了完整的漏斗映射表其中Checkout Started建议携带cart_id与products数组Order Completed建议携带order_id、total与products。自动映射到下游工具按 api.md 的说明这些标准电商事件会被Tools auto-map to GA4, Facebook CAPI, etc.自动映射到 GA4、Facebook CAPI 等工具。也就是说只要你在 configuration.md 中配置了 GA4Measurement ID: G-XXXXXXXXXX或 Facebook PixelPixel ID调用zaraz.ecommerce(Order Completed, ...)后Zaraz 会自动翻译成下游工具的对应转换事件如 GA4 的purchase、Facebook 的Purchase无需为每个工具单独写适配代码。这正是 Zaraz 相比手动埋点的核心价值——一处埋点多渠道分发。GTM 迁移对照如果是从 Google Tag Manager 迁移patterns.md 提供了逐行对照GTM 的dataLayer.push({event: purchase})对应zaraz.ecommerce(Order Completed, {...})GTM 的{{Page URL}}/{{Page Title}}对应{{system.page.url}}/{{system.page.title}}点击触发器对应 CSS selector 点击触发器。五、System Properties触发器可用的系统属性除自定义属性外Zaraz 内置了一套系统属性System Properties可在触发器、工具配置与数据层中直接引用。按 api.md 的列表{{system.page.url}} {{system.page.title}} {{system.page.referrer}} {{system.device.ip}} {{system.device.userAgent}} {{system.device.language}} {{system.cookies.name}} {{client.__zarazTrack.userId}}这些模板变量的作用场景包括触发器条件configuration.md 中的 Variable Match 触发器可按系统属性做条件判断例如按页面 URL 决定是否触发事件属性补充点击触发器可通过{{system.clickElement.text}}动态采集被点击元素的文本Type: Click CSS Selector: .buy-button Event: purchase_intent Properties: button_text: {{system.clickElement.text}}与zaraz.set()的数据打通{{client.__zarazTrack.userId}}说明客户端通过zaraz.set(userId, ...)写入的属性同样能进入系统属性命名空间供触发器读取。六、zaraz.consent隐私同意管理GDPR/CCPA 合规是 Zaraz 的核心卖点之一。zaraz.consent对象提供了同意状态的查询、设置与监听能力。完整 API 一览// 查询全部用途的同意状态 const purposes zaraz.consent.getAll(); // { analytics: true, marketing: false } // 展示同意弹窗 zaraz.consent.modal true; // Show modal // 批量设置同意 zaraz.consent.setAll({ analytics: true, marketing: false }); // 设置单个用途 zaraz.consent.set(marketing, true); // 监听同意变更 zaraz.consent.addEventListener(consentChanged, () { if (zaraz.consent.getAll().marketing) zaraz.track(marketing_consent_granted); });标准工作流按 api.md 定义的流程完整的同意管理分为四步Configure purposes in dashboard——在控制台Domain → Zaraz → Settings → Consent创建用途purpose如analytics、marketingMap tools to purposes——把各工具映射到对应用途Show modal / set programmatically——通过zaraz.consent.modal true展示弹窗或通过setAll()/set()编程式设置Tools fire when allowed——仅当用户同意后映射到该用途的工具才会触发。configuration.md 补充了关键配置项设置用途行为为 Do not load until consent granted未同意前不加载工具这是防止工具在授权前提前触发的关键开关。控制台默认的隐私特性包括IP AnonymizationIP 匿名化默认启用与Cookie Control通过同意用途控制。同意排查gotchas.md 提供了两个高频问题解法弹窗不出现手动清除同意 Cookie 后刷新页面document.cookie zaraz-consent; expiresThu, 01 Jan 1970 00:00:00 UTC; path/;; location.reload();工具在同意前触发把工具映射到同意用途并启用 Do not load until consent granted。七、zaraz.debug实时调试模式排查埋点问题时开启调试模式可以实时观察事件处理过程zaraz.debug true; zaraz.track(test_event); console.log(zaraz.tools); // 查看已加载的工具列表启用后zaraz.tools会暴露当前已加载的工具数组zaraz.consent.getAll()可打印同意状态。配合 configuration.md 的测试工作流效果最佳Preview Mode预览模式——不发布即可测试配置变更Debug Mode调试模式——zaraz.debug trueNetwork tab网络面板——过滤关键字 zaraz 观察请求。gotchas.md 还给出了完整的事件不触发排查清单检查工具是否启用绿色圆点、触发器条件是否满足、同意是否授予、凭据是否正确GA4 为G-XXXXXXXXXXFacebook Pixel 仅数字不能带fbpx_前缀。八、Cookie 方法读取浏览器 CookieZaraz 提供两个 Cookie 读取方法区别在于命名空间zaraz.getCookie(session_id); // 仅读取 Zaraz 命名空间下的 Cookie zaraz.readCookie(_ga); // 读取任意 Cookie如 GA 的 _gazaraz.getCookie(name)读取Zaraz namespaceZaraz 自身管理的 Cookiezaraz.readCookie(name)读取任意 Cookie可用于获取_ga等第三方分析 Cookie。九、异步行为批处理与 fire-and-forgetapi.md 明确All methods fire-and-forget——所有方法都是即发即忘的调用后立即返回不返回 Promise也不阻塞页面。事件会被**批量batched并异步asynchronously**发送zaraz.track(event1); zaraz.set(prop, value); zaraz.track(event2); // 三个调用会被一起批量发送这带来两个工程启示不要依赖返回值zaraz.track()没有回调或 Promise无法在其返回后同步确认发送成功验证应借助zaraz.debug或网络面板无需关心调用顺序同批次内的 set 与 track 会被合并处理因此可以放心地把属性设置和事件上报写在一起如登录后zaraz.set(...)zaraz.track(login, ...)连写。十、TypeScript 类型定义api.md 提供了完整的 TypeScript 类型声明可在项目中直接使用interface Zaraz { track(event: string, properties?: Recordstring, unknown): void; set(key: string, value: unknown): void; set(properties: Recordstring, unknown): void; ecommerce(event: string, properties: Recordstring, unknown): void; consent: { getAll(): Recordstring, boolean; setAll(purposes: Recordstring, boolean): void; set(purpose: string, value: boolean): void; addEventListener(event: consentChanged, callback: () void): void; modal: boolean; }; debug: boolean; tools?: string[]; getCookie(name: string): string | undefined; readCookie(name: string): string | undefined; } declare global { interface Window { zaraz: Zaraz; } }类型定义要点track()的属性参数是可选的properties?而ecommerce()的属性参数是必填的Recordstring, unknownset()通过函数重载同时支持键值对与批量对象两种形式tools声明为可选数组string[]对应调试模式下暴露的已加载工具列表通过declare global把zaraz挂到window上便于在任意 TS 文件中直接以window.zaraz访问同时也可将声明文件共享给团队复用。十一、综合实战把整套 API 用在一个页面里将以上 API 组合起来一个典型的电商页面初始化逻辑如下// 1. 初始化同意状态提前防止工具提前加载 zaraz.consent.setAll({ analytics: true, marketing: false }); // 2. 设置用户属性页面会话内持久 zaraz.set({ userId: user_12345, plan: premium, country: US }); // 3. SPA 路由变化上报 pageview zaraz.track(pageview, { page_path: /checkout, page_title: Checkout }); // 4. 电商漏斗事件自动映射到 GA4 / Facebook CAPI zaraz.ecommerce(Checkout Started, { cart_id: CART-456, total: 149.98, currency: USD, products: [{ product_id: SKU123, quantity: 2, price: 49.99 }] }); // 5. 用户同意营销用途后触发营销事件 zaraz.consent.addEventListener(consentChanged, () { if (zaraz.consent.getAll().marketing) zaraz.track(marketing_consent_granted); }); // 6. 出问题打开调试 zaraz.debug true;十二、使用限制与边界硬性限制configuration.md 与 gotchas.md 给出了两组限制数据资源限制事件属性 / 请求大小100KB同意用途Consent purposes20 个API 速率1000 req/sec性能注意gotchas.md 提醒页面加载变慢时优先检查工具数量超过 50 个工具会明显影响性能、禁用非必要的阻塞触发器、并将事件负载控制在 100KB 以内。不适合使用 Zaraz Web API 的场景gotchas.md 明确列出以下场景不应使用 Zaraz应改用 Cloudflare Workers 等方案服务端到服务端的追踪server-to-server tracking实时双向通信real-time bidirectional communication二进制数据传输binary data transmission认证流程authentication flows。这些场景需要完全控制数据处理的逻辑适合直接使用 Workers 实现README.md 中 Use Workers directly when 一节有更完整的判断标准。参考文件导航本文内容在仓库中对应的完整参考文档如下Zaraz Web API 参考本文主体track / set / ecommerce / consent / debug / Cookie / 类型定义Zaraz 概览与决策树Zaraz 是什么、何时使用、任务导向阅读顺序Zaraz 配置指南控制台配置、触发器、工具凭据、同意用途、限制Zaraz 实战模式SPA 追踪、用户识别、电商漏斗、A/B 测试、Worker 集成、GTM 迁移Zaraz 踩坑排查事件不触发、同意问题、工具特有问题、性能与限制Zaraz 参考实现摘要文档体系结构与改进说明cloudflare-deploy Skill 入口Zaraz 在整个 Cloudflare 部署技能树中的定位【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考