# @amboras-dev/google-ads 中文文档

规范地址：https://npmcn.com/package/%40amboras-dev/google-ads/

版本：1\.2\.1
npm 元数据更新时间：2026-11-02T15:47:37.690Z
中文译文更新时间：2026-11-06T00:09:52.645Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amboras-dev/google-ads
原文对照：https://npmcn.com/package/%40amboras-dev/google-ads/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：133 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18
- 首次发布：2026-06-24T05:30:30.792Z
- 最新版本发布：2026-11-02T15:47:37.475Z
- 近 30 天下载量：14884（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Google Ads (gtag.js 转换跟踪 + 增强转换 + 同意模式) 安博拉斯商店前端的钩子

## 安装

```sh
npm install @amboras-dev/google-ads
```

也可以使用：`pnpm add @amboras-dev/google-ads`、`yarn add @amboras-dev/google-ads`、`bun add @amboras-dev/google-ads`

## README

# @amboras-dev/google-ads (英语)

谷歌 Amboras商店前端的广告转换跟踪——Amboras等同 "Google Ads Pixel by Nabu" Shopify app. 网易新闻. 通过 Google 标签, 完全客户端 (单位:千美元)`gtag.js`: 转换跟踪, **加强转换**, (中文(简体) ), **同意模式 v2**, (中文(简体) ), 确定性去除和准确的多货币换算值.

## 安装

```bash
pnpm add @amboras-dev/google-ads
```

## 追踪到什么

| 阶段 | 活动 | 槽 | 类 |
| --- | --- | --- | --- |
| 装入标记( 在同意后) + 同意模式 | `page_view` | `rootProviders` | A级(`GoogleAdsProvider`(中文(简体) ) |
| 产品视图 | `view_item` | `pdpAnalytics` | A级(`GoogleAdsViewItem`(中文(简体) ) |
| 添加到手推车 | `add_to_cart` | `cartUpdate` | B (跟踪模板) |
| 开始离职 | `begin_checkout` | `checkoutStart` | B (跟踪模板) |
| 采购 | `purchase` | `checkoutComplete` | B (跟踪模板) |

每起转换起火 `gtag('event', 'conversion', { send_to: 'AW-XXXX/<label>', value, currency, transaction_id, items })`。 。 。 . 转换 id 和 per- action **转换标签** 从商家来的 管理员设置, 由 `GET /store/google-ads/config`。 。 。 .

## 建筑

-   **`GoogleAdsProvider`** (A类, `rootProviders`) ——自足配置和 等待着 `amboras_consent` 要给的饼干 `analytics` (重审) `amboras-consent-changed`) (中文(简体) ). 只有这样它才会设置 同意模式 v2 信号, 装入 AW 标记一次( DOM 特性), 启用增强转换并隐藏 `{conversionId, labels, enhancedConversions}` 打开 `window.__amborasGoogleAds`。 。 。 . 在同意之前,没有gtag, `dataLayer` 或AW-脚本存在于页面上.
-   **`GoogleAdsViewItem`** (A类, `pdpAnalytics`(-火灾) `view_item`。 。 。 .
-   **B级跟踪器** (加到卡/开始检查/购买)改为真实 `cart.items` 编号 : `order` 单行项目 + 来自本地反应的客户电子邮件/电话 范围,因此值和项 id 正确(仅插槽上下文仅显示) `{cartId,itemCount,total,currency}`) (中文(简体) ).

## 多种货币

每件事都背着买家的真面目 `currency_code` 并用该值缩放 货币本身的小数 `toMajorUnits(amount, currency)` (基于Intl) - **没有** 一个盲人 `/100`. JPY/KRW(0-十进制)和KW/BHD(3-十进制)是正确的.

## 加强转换和同意

-   一级数据`email`, (中文(简体) ), `phone_number`以原始方式转发至 `gtag('set','user_data',…)`; Google 的标签正常 + SHA-256 散开 客户端。 任何敏感内容都不要让浏览器损坏, 没有服务器 中继器也参与其中.
-   标签和所有转换都打开了 `amboras_consent.analytics`。 。 。 . 直到它被击倒之前,没有东西可以装载或起火 `true`: 未显示的 cookie( 未显示横幅) 计算为 **被拒绝**。安博拉斯边缘写着一个给予 在欧洲经济区、英国和瑞士以外的购物者可自动获得饼干。 一次 标记负载, 同意模式 v2 信号 (`ad_storage`, (中文(简体) ), `ad_user_data`, (中文(简体) ), `ad_personalization`, (中文(简体) ), `analytics_storage`) 反映这种同意.

## 程序化 API

```ts
import { trackPurchase, cartItemsToItems } from '@amboras-dev/google-ads'

trackPurchase({
  orderId: order.id,
  items: cartItemsToItems(order.items, order.currency_code),
  totalMinor: order.total, // minor units; converted per-currency
  currency: order.currency_code,
  email: order.email,
})
```

## 常见问题

### @amboras-dev/google-ads 是什么？

Google Ads \(gtag\.js 转换跟踪 \+ 增强转换 \+ 同意模式\) 安博拉斯商店前端的钩子

### 如何安装 @amboras-dev/google-ads？

在项目目录运行 npm install @amboras-dev/google-ads，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @amboras-dev/google-ads 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amboras-dev/google-ads 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @amboras-dev/google-ads 可以商用吗？

@amboras-dev/google-ads 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @amboras-dev/google-ads 的下载量有多少？

根据 npm 官方下载统计，@amboras-dev/google-ads 在 2026/10/06 – 2026/11/04 这 30 天内被下载 14,884 次，日均约 496 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amboras-dev/google-ads 还在维护吗？

最新版本 1\.2\.1 发布于 2026/11/02（3 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/06/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。