# @adkit\.so/meta-pixel 中文文档

规范地址：https://npmcn.com/package/%40adkit.so/meta-pixel/

版本：1\.1\.5
npm 元数据更新时间：2026-07-30T04:03:48.083Z
中文译文更新时间：2026-11-06T15:23:16.976Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adkit.so/meta-pixel
原文对照：https://npmcn.com/package/%40adkit.so/meta-pixel/?lang=original

弃用说明：Renamed to @adkit/meta-pixel\. Install that instead; the API is unchanged\.

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

- 包体积（解压后）：27 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-11-07T03:22:02.687Z
- 最新版本发布：2025-11-26T06:32:12.956Z
- 近 30 天下载量：2919（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 5 个）

## 中文简介

有类型Script支持的平台不可知的Meta像素跟踪包

## 安装

```sh
npm install @adkit.so/meta-pixel
```

也可以使用：`pnpm add @adkit.so/meta-pixel`、`yarn add @adkit.so/meta-pixel`、`bun add @adkit.so/meta-pixel`

## README

# Meta 像素( JS/ TS)

[![npm version](https://img.shields.io/npm/v/@adkit.so/meta-pixel.svg)](https://www.npmjs.com/package/@adkit.so/meta-pixel) [![npm downloads](https://img.shields.io/npm/dm/@adkit.so/meta-pixel.svg)](https://www.npmjs.com/package/@adkit.so/meta-pixel) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> 为JavaScript和TypeScript应用程序提供最强大和最方便开发者的Meta像素集成.

为Meta Pixel提供无缝,类型安全体验的平台-可知包装器,具有事件分解等先进特性,多像素支持,以及美丽的调试记录.

## 目录

-   [特征](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--features)
-   [快速启动](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--quick-start)
-   [安装](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--installation)
-   [使用量](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--usage)
-   [配置](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme-%EF%B8%8F-configuration)
-   [标准事件](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--standard-events)
-   [事件数据参数](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--event-data-parameters)
-   [高级使用](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--advanced-usage)
-   [类型脚本支持](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--typescript-support)
-   [解决问题](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--troubleshooting)
-   [正式文件](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--official-documentation)
-   [许可证](https://npmcn.com/package/%40adkit.so/meta-pixel/#readme--license)

## \* 特性

-   ✅ **键入符支持** - 对所有正式事件和参数进行自动完成的完整类型脚本支持
-   🎯 **自定义事件支持** - 跟踪具有完整类型安全和灵活数据结构的自定义事件
-   🚦 **事件重复** - 支持防止事件重复和事件标识
-   🔌 **多像素支持** - 不加努力地装入和管理多个像素标识
-   🐛 **调试模式** - 用于开发和调试的漂亮的有风格的控制台日志
-   🏠 **本地主机支持** - 方便配置,以便在本地主机上启用/无法跟踪

## QQ 快速启动

```bash
npm install @adkit.so/meta-pixel
```

```typescript
import META from '@adkit.so/meta-pixel';

// 1. Initialize
META.init({ pixelIds: 'YOUR_PIXEL_ID' });

// 2. Track events
META.track('Purchase', { value: 99.99, currency: 'USD' });
```

就这样

## \* 安装

```bash
npm install @adkit.so/meta-pixel
```

## 使用量

### 基本初始化

在应用程序入口处尽早初始化像素(例如, `main.ts`, (中文(简体) ), `App.jsx`, (中文(简体) ), `index.js`) (中文(简体) ).

```typescript
import META from '@adkit.so/meta-pixel';

META.init({
    pixelIds: '1234567890',
    autoTrackPageView: true, // default: true
});
```

### 跟踪事件

```typescript
// Track standard events
META.track('AddToCart', {
    value: 29.99,
    currency: 'USD',
    content_ids: ['SKU_123'],
    content_type: 'product',
});

// Track custom events
META.trackCustom('MyCustomEvent', {
    custom_param: 'value',
});
```

### 多个实例

如果应用程序的不同部分需要单独实例( 罕见) :

```typescript
import { createMetaPixel } from '@adkit.so/meta-pixel';

const marketingPixel = createMetaPixel();
marketingPixel.init({ pixelIds: 'MARKETING_ID' });

const productPixel = createMetaPixel();
productPixel.init({ pixelIds: 'PRODUCT_ID' });
```

## QQ 配置

### 配置选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `pixelIds` | `string | string[]` | `''` | **要求.** 单个像素ID或像素ID阵列 |
| `autoTrackPageView` | `boolean` | `true` | 初始化时自动跟踪页面 |
| `debug` | `boolean` | `false` | 启用带有背景颜色的样式控制台日志 |
| `enableLocalhost` | `boolean` | `false` | 启用本地主机跟踪( 用于测试) |

### 多像素示例

```typescript
META.init({
    pixelIds: ['PIXEL_ID_1', 'PIXEL_ID_2', 'PIXEL_ID_3'],
    debug: true,
});
```

## 标准事件

所有Meta像素标准事件都以完整的TypeScript自动完成支持. 这些事件帮助您追踪您网站上的重要动作,并优化您的广告宣传.

| 活动 | 说明 | 常用案例 |
| --- | --- | --- |
| `AddPaymentInfo` | 加了付款信息 | 检查流程 |
| `AddToCart` | 列入购物车的项目 | 电子商务 |
| `AddToWishlist` | 添加到希望列表的项目 | 电子商务 |
| `CompleteRegistration` | 用户完成登记 | 签名、 账户创建 |
| `Contact` | 用户联系业务 | 联系表 |
| `CustomizeProduct` | 开始产品定制 | 产品配置器 |
| `Donate` | 捐款 | 非营利 |
| `FindLocation` | 使用的位置查找器 | 存储定位器 |
| `InitiateCheckout` | 退出进程已启动 | 电子商务漏斗 |
| `Lead` | 提交的铅 | 铅生成表 |
| `Purchase` | 完成采购 | 交易确认 |
| `Schedule` | 任命计划 | 预订系统 |
| `Search` | 进行搜索 | 现场搜索 |
| `StartTrial` | 审判已经开始 | SaaS 应用程序 |
| `SubmitApplication` | 提交的申请 | 工作委员会、贷款申请 |
| `Subscribe` | 开始订阅 | 通讯、订阅 |
| `ViewContent` | 查看的内容 | 产品页面,博客文章 |

您可以找到标准事件的官方列表 [这里](https://developers.facebook.com/docs/meta-pixel/reference/#standard-events)。 。 。 .

## 事件数据参数

所有事件参数都是可选的,但有助于改进广告的定位和转换跟踪.

| 参数 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `value` | `number` | 事件的货币价值 | `99.99` |
| `currency` | `string` | ISO 4217 货币编码 | `'USD'`, (中文(简体) ), `'EUR'`, (中文(简体) ), `'GBP'` |
| `content_ids` | `string[]` | 产品标识或 SKU | `['SKU_123', 'SKU_456']` |
| `content_type` | `string` | 内容类型 | `'product'`, (中文(简体) ), `'product_group'` |
| `content_name` | `string` | 页面名称/产品 | `'Blue T-Shirt'` |
| `content_category` | `string` | 页面/产品类别 | `'Apparel'`, (中文(简体) ), `'Electronics'` |
| `contents` | `Array<{id, quantity}>` | 详细产品信息 | `[{id: 'SKU_123', quantity: 2}]` |
| `num_items` | `number` | 项目数 | `3` |
| `search_string` | `string` | 搜索查询 | `'running shoes'` |
| `status` | `boolean` | 登记/登记地位 | `true` |
| `predicted_ltv` | `number` | 客户预计寿命价值 | `450.00` |

您可以找到属性列表 [这里](https://developers.facebook.com/docs/meta-pixel/reference/#object-properties)

## 高级用途

### 事件重复

通过使用独特的事件ID来防止重复事件跟踪. 在从客户端和服务器(CAPI)跟踪转换时,这一点至关重要.

```typescript
const orderId = '12345';

META.track(
    'Purchase',
    {
        value: 299.99,
        currency: 'USD',
        content_ids: ['SKU_123'],
    },
    {
        eventID: `order-${orderId}`, // Unique Event ID
    },
);
```

### 检查像素是否已装入

如果您需要基于像素脚本是否已加载而有条件运行逻辑,则有用 .

```typescript
if (META.isLoaded()) {
    META.track('Purchase', { value: 99.99, currency: 'USD' });
} else {
    console.log('Pixel not loaded yet');
}
```

### 调试模式

何时 `debug: true` 转至 `init()`,你会看到美丽的 风格控制台日志:

-   🔵 **\[Meta像素\]** 信息消息( 蓝色背景)
-   ✅ **\[Meta像素\]** 成功信息( 绿色背景)
-   ⚠️ **\[Meta像素\]** 警告信息( 橙色背景)

```typescript
META.init({
    pixelIds: 'YOUR_ID',
    debug: true,
});
```

## QQ 类型脚本支持

此软件包以TypeScript和捆绑类型定义来写出.

```typescript
import type { StandardEvent, EventData, MetaPixelConfig } from '@adkit.so/meta-pixel';

const config: MetaPixelConfig = {
    pixelIds: '123',
};

const eventData: EventData = {
    value: 100,
    currency: 'USD',
};
```

## \* 解决问题

### 像素没有加载?

1.  **检查您的像素标识** - 确保你的配置正确
2.  **启用调试模式** - 准备 `debug: true` 内 `init()` 查看详细的日志
3.  **检查浏览器控制台** - 查找错误或警告
4.  **检查 Ad 屏蔽器** - 阿德阻断器经常阻断Meta像素脚本
5.  **启用本地主机** - 准备 `enableLocalhost: true` 如果本地测试

### Meta Eventure 管理器中未显示的事件 ?

-   **等一会儿** - 事件需要5-20分钟才能出现
-   **检查测试事件** - 在元事件管理器中使用测试事件工具
-   **校验事件名称** - 标准事件对案件有敏感认识

## \* 正式文件

从官方Facebook资源了解更多Meta像素:

-   **[Meta 像素参考](https://developers.facebook.com/docs/meta-pixel/reference/)** - 完整的API参考文献
-   **[标准事件指南](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking#standard-events)** - 详细事件文件
-   **[对象属性](https://developers.facebook.com/docs/meta-pixel/reference/#object-properties)** - 所有可用的事件参数
-   **[转换 API](https://developers.facebook.com/docs/marketing-api/conversions-api)** - 服务器侧事件跟踪
-   **[事件管理器](https://www.facebook.com/events_manager2)** - 监视您的像素事件

## 平台软件包

使用框架? 看看我们的专用包:

-   [**坚果**](https://www.npmjs.com/package/@adkit.so/meta-pixel-nuxt) - 说吧 `@adkit.so/meta-pixel-nuxt`
-   [**反应**](https://www.npmjs.com/package/@adkit.so/meta-pixel-react) - 说吧 `@adkit.so/meta-pixel-react`
-   [**下一个.js**](https://www.npmjs.com/package/@adkit.so/meta-pixel-next) - 说吧 `@adkit.so/meta-pixel-next`

## QQ 完整指南

关于安装和配置Meta像素的完整分步指南,请检查我们的详细教程:

**[如何安装元像素](https://adkit.so/resources/how-to-install-meta-pixel)**

## 捐款

欢迎捐款! 请随意提交拉力请求 对于重大变动,请先开出一个问题来讨论你想要改变什么.

## 许可证

麻省理工学院

* * *

**由 Q 制作 [阿德基特语Name](https://adkit.so/)**

如果这个软件包帮助你,请考虑给它一个 \\ \\ 上 [GitHub 图像](https://github.com/AdKit-so/meta-pixel-js)来啊!

## 常见问题

### @adkit\.so/meta-pixel 是什么？

有类型Script支持的平台不可知的Meta像素跟踪包注意：该包已被作者标记为弃用——Renamed to @adkit/meta-pixel\. Install that instead; the API is unchanged\.

### 如何安装 @adkit\.so/meta-pixel？

在项目目录运行 npm install @adkit\.so/meta-pixel，或使用 pnpm add / yarn add / bun add。

### @adkit\.so/meta-pixel 支持 TypeScript 吗？

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

### @adkit\.so/meta-pixel 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adkit\.so/meta-pixel 可以商用吗？

@adkit\.so/meta-pixel 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adkit\.so/meta-pixel 的下载量有多少？

根据 npm 官方下载统计，@adkit\.so/meta-pixel 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,919 次，日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adkit\.so/meta-pixel 还在维护吗？

最新版本 1\.1\.5 发布于 2025/11/26（11 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/11/07。作者已将其标记为弃用，新项目建议寻找替代方案。