# @eancarr/klaviyo-medusa 中文文档 规范地址：https://npmcn.com/package/%40eancarr/klaviyo-medusa/ 版本：0\.2\.5 npm 元数据更新时间：2025-10-31T17:32:01.525Z 中文译文更新时间：2026-11-13T03:26:20.413Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40eancarr/klaviyo-medusa 原文对照：https://npmcn.com/package/%40eancarr/klaviyo-medusa/?lang=original 项目主页：https://github.com/eancarr/klaviyo-medusa#readme 源码仓库：https://github.com/eancarr/klaviyo-medusa ## 关键信息（来自 npm 元数据） - 包体积（解压后）：117 kB，35 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - Node.js 要求：\>=20 - 运行依赖：1 个 - peer 依赖：@medusajs/admin-sdk 2\.10\.3，@medusajs/cli 2\.10\.3，@medusajs/framework 2\.10\.3，@medusajs/icons 2\.10\.3，@medusajs/medusa 2\.10\.3，@medusajs/test-utils 2\.10\.3，@medusajs/ui ^4\.0\.3，@mikro-orm/cli 6\.4\.3，@mikro-orm/core 6\.4\.3，@mikro-orm/knex 6\.4\.3，@mikro-orm/migrations 6\.4\.3，@mikro-orm/postgresql 6\.4\.3，awilix ^8\.0\.1，pg ^8\.13\.0 - 首次发布：2025-10-22T17:20:31.525Z - 最新版本发布：2025-10-31T17:32:01.327Z - 近 30 天下载量：2938（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：15（近 12 个月 0 个） ## 中文简介 美杜莎的克拉维约插件. ## 安装 ```sh npm install @eancarr/klaviyo-medusa ``` 也可以使用：`pnpm add @eancarr/klaviyo-medusa`、`yarn add @eancarr/klaviyo-medusa`、`bun add @eancarr/klaviyo-medusa` ## README # 草地Klaviyo一体化 一个将克拉维约的电子邮件营销和客户互动平台与你的美杜莎商店整合在一起的美杜莎插件. > **说明**: 这是叉子 [@variablevic/klaviyo-medusa(英语:](https://github.com/variablevic/klaviyo-medusa) 包括事件跟踪、回归管理、手推车行为跟踪、品牌支持强化产品饲料和批量订阅管理. ## 目录 - [特征](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-features) - [先决条件](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-prerequisites) - [安装](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-installation) - [配置](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-configuration) - [配置选项](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-configuration-options) - [环境变量](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-environment-variables) - [使用量](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-usage) - [客户端集成](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-client-side-integration) - [产品种子](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-product-feed) - [扩展插件](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-extending-the-plugin) - [地方发展](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-local-development) - [许可证](https://npmcn.com/package/%40eancarr/klaviyo-medusa/#readme-license) ## 特征 ### 客户管理 - 创建或更新时自动同步客户端到 Klaviyo - 处理电子邮件/短信订阅的营销协议 - 基于客户同意元数据的大量订阅管理 - 支持电子邮件和短信营销许可 - 交易短消息的同意处理 ### 跟踪 - **排列** - 跟踪订单的完整细节 - **订购** - 跟踪编号和载体信息的跟踪实现创建 - **命令已取消** - 取消有退款数额的追踪订单 - **交付顺序** - 跟踪订单完成/交付情况 ### 返回跟踪 - **请求返回** - 附有项目细节和理由的跟踪返回请求 - **已收到的返回** - 仓库收到报告后追踪 ### 行为跟踪(服务器) - **已添加到墨盒中** - 在将物品添加到推车时跟踪(包括产品细节) - 检测出新物项并增加了数量 - 当将邮件添加到手推车时, 支持追溯跟踪 - 为登录用户和来宾提供的作品 - **说明**: Cart track使用相模状态管理. 对于规模生产,考虑实施基于Redis的状态管理,以在服务器重启时坚持卡通状态. - **开始取出** - 跟踪客户开始离职过程(在添加货运地址时触发) ### 产品目录 - 用于目录同步的 Klaviyo 兼容产品饲料 - 多种货币支助 - 完整的产品细节,包括库存、定价和品牌信息 - 支持计算出价格的产品变体 ## 先决条件 - 美杜莎服务器(v 2. 4. 0 或以上) - 具有 API 证书的 Klaviyo 账户 ## 安装 ```bash yarn add @eancarr/klaviyo-medusa ``` 或与 npm : ```bash npm install @eancarr/klaviyo-medusa ``` 然后将插件添加到您的 `medusa-config.js` 文件 : ```js const plugins = [ // ... { resolve: "@eancarr/klaviyo-medusa", options: { apiKey: process.env.KLAVIYO_API_KEY, }, }, ]; ``` ## 配置 ### 配置选项 | 选项 | 类型 | 说明 | 默认 | | --- | --- | --- | --- | | `apiKey` | `string` | 您的 Klaviyo API 密钥 | `undefined` | ### 环境变量 ```bash KLAVIYO_API_KEY=your_klaviyo_api_key STOREFRONT_URL=https://your-storefront-url.com # Optional: Your actual storefront URL (where customers view products). Used for product feed links. Defaults to http://localhost:8000 ``` ## 使用量 一旦安装和配置,插件将自动跟踪以下事件: ### 自动事件跟踪 插件使用美杜莎事件订阅者来聆听事件并发送到克洛维约: #### 客户活动 - `customer.created` - 将新客户同步到克拉维约 - `customer.updated` - 更新克拉维约客户简介 #### 顺序事件 - `order.placed` - 发送“平分命令”事件,并附上命令细节 - `order.fulfillment_created` - 发送载有跟踪信息的“订单已运出”活动 - `order.canceled` - 发送带有退款细节的“命令取消”事件 - `order.completed` - 发出“命令交付”活动 #### 返回事件 - `order.return_requested` - 发送“ 要求返回” 事件 - `order.return_received` - 发送“ 返回接收” 事件 #### 单元格事件 - `cart.updated` - 跟踪“添加到墨盒”和“开始检查”事件 所有事件都是跟踪服务器侧的可靠性,并包含您美杜莎数据库的完整数据. 这些事件在克洛维约可以用来: - 建立自动电子邮件流程(废弃推车、货运通知等) - 基于行为的分部客户 - 跟踪客户寿命值 - 创建产品建议 ### 客户端集成 为了在你的店面上正确管理Klaviyo的营销同意,你应该在客户的元数据中设置同意设置. 这确保只有明确表示同意的客户才遵守隐私条例. 在收集客户信息(注册、通讯注册或离职)时,用克拉维约同意旗更新客户元数据: ```ts // Example implementation in your storefront const updateCustomerConsent = async ( customerId: string, consentSettings: { email?: boolean; sms?: boolean; transactional_sms?: boolean; consented_at?: string; // ISO date string (optional) } ) => { // Call your store API endpoint that updates customer metadata await fetch("/store/customers/me", { method: "POST", headers: { "Content-Type": "application/json", }, credentials: "include", body: JSON.stringify({ metadata: { klaviyo: consentSettings, // Can be object or JSON string }, }), }); }; // Usage example updateCustomerConsent("cus_123", { email: true, sms: false, transactional_sms: true, }); ``` 将客户数据同步到 Klaviyo 时, 插件检查这些同意设置 : - `metadata.klaviyo.email`: 设定为 `true` 选择客户进行电子邮件营销 - `metadata.klaviyo.sms`: 设定为 `true` 选择客户进行短信营销 - `metadata.klaviyo.transactional_sms`: 设定为 `true` 选择客户进入交易短消息 - `metadata.klaviyo.consented_at`: 同意时间戳的可选 ISO 日期字符串 这个 `metadata.klaviyo` 值可以是: - 同意属性的 JSON 对象 - 自动解析的 JSON 字符串 ### 产品种子 该插件提供了可兼容克拉维约的产品饲料API,允许您与克拉维约同步整个产品目录. 这使得产品推荐、废弃的带有产品细节的推车邮件,以及更多. 使用Klaviyo的产品饲料: 1. 访问您的产品饲料 : `https://your-medusa-url.com/feeds/products/{currencyCode}` - 替换 `{currencyCode}` 用你的商店的货币代码(例如, `usd`, (中文(简体) ), `eur`(中文(简体) ) 2. 在你的克拉维约账户里: - 转到"Content" → "出产" - 点击“ 管理自定义目录源” - 单击“ 添加新源” - 输入您的产品种子 URL - 根据需求配置同步设置 产品饲料包括综合产品数据: - 产品标识 - 标题 - 说明 - 处理/粘贴 - 斯库 - 缩略图和图像 - **品牌** 资料 - 定价信息(最低/最高价格,价格比较) - 货币 - 产品 URL - 类别 - 库存数量和供应状况 - 计算出价格的产品变体 ## 扩展插件 您可以通过 : 1. 在您的 Medusa 服务器中创建使用 Klaviyo 服务的自定义工作流程 2. 添加额外事件订阅者以同步更多数据类型 3. 增强发送给克拉维约的数据结构 在您自己的代码中使用克拉维约服务的例子 : ```ts // Access the Klaviyo service const klaviyoService = container.resolve("klaviyoService"); // Create an event await klaviyoService.createEvent({ metric: { name: "Custom Event", }, profile: { email: "customer@example.com", }, properties: { // Your custom properties }, }); // Upsert a customer profile await klaviyoService.upsertProfile({ email: "customer@example.com", phone_number: "+1234567890", // ... other profile attributes }); // Bulk subscribe profiles await klaviyoService.bulkSubscribeProfiles([ { type: "profile", id: "profile-id", attributes: { email: "customer@example.com", subscriptions: { email: { marketing: { consent: "SUBSCRIBED", }, }, }, }, }, ]); ``` ## 地方发展 ```bash # Clone the repository git clone https://github.com/eancarr/klaviyo-medusa.git # Install dependencies cd klaviyo-medusa yarn # Start development server yarn dev ``` ## 许可证 麻省理工学院 ## 常见问题 ### @eancarr/klaviyo-medusa 是什么？ 美杜莎的克拉维约插件\. ### 如何安装 @eancarr/klaviyo-medusa？ 在项目目录运行 npm install @eancarr/klaviyo-medusa，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@medusajs/admin-sdk（2\.10\.3）、@medusajs/cli（2\.10\.3）、@medusajs/framework（2\.10\.3）、@medusajs/icons（2\.10\.3）、@medusajs/medusa（2\.10\.3）、@medusajs/test-utils（2\.10\.3）、@medusajs/ui（^4\.0\.3）、@mikro-orm/cli（6\.4\.3）、@mikro-orm/core（6\.4\.3）、@mikro-orm/knex（6\.4\.3）、@mikro-orm/migrations（6\.4\.3）、@mikro-orm/postgresql（6\.4\.3）、awilix（^8\.0\.1）、pg（^8\.13\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @eancarr/klaviyo-medusa 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/eancarr\_\_klaviyo-medusa 是否存在。 ### @eancarr/klaviyo-medusa 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @eancarr/klaviyo-medusa 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @eancarr/klaviyo-medusa 可以商用吗？ @eancarr/klaviyo-medusa 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @eancarr/klaviyo-medusa 的下载量有多少？ 根据 npm 官方下载统计，@eancarr/klaviyo-medusa 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,938 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @eancarr/klaviyo-medusa 还在维护吗？ 最新版本 0\.2\.5 发布于 2025/11/01（1 年前）；至今共发布 15 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/10/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。