草地Klaviyo一体化
一个将克拉维约的电子邮件营销和客户互动平台与你的美杜莎商店整合在一起的美杜莎插件.
说明: 这是叉子 @variablevic/klaviyo-medusa(英语: 包括事件跟踪、回归管理、手推车行为跟踪、品牌支持强化产品饲料和批量订阅管理.
目录
特征
客户管理
- 创建或更新时自动同步客户端到 Klaviyo
- 处理电子邮件/短信订阅的营销协议
- 基于客户同意元数据的大量订阅管理
- 支持电子邮件和短信营销许可
- 交易短消息的同意处理
跟踪
- 排列 - 跟踪订单的完整细节
- 订购 - 跟踪编号和载体信息的跟踪实现创建
- 命令已取消 - 取消有退款数额的追踪订单
- 交付顺序 - 跟踪订单完成/交付情况
返回跟踪
- 请求返回 - 附有项目细节和理由的跟踪返回请求
- 已收到的返回 - 仓库收到报告后追踪
行为跟踪(服务器)
- 已添加到墨盒中 - 在将物品添加到推车时跟踪(包括产品细节)
- 检测出新物项并增加了数量
- 当将邮件添加到手推车时, 支持追溯跟踪
- 为登录用户和来宾提供的作品
- 说明: Cart track使用相模状态管理. 对于规模生产,考虑实施基于Redis的状态管理,以在服务器重启时坚持卡通状态.
- 开始取出 - 跟踪客户开始离职过程(在添加货运地址时触发)
产品目录
- 用于目录同步的 Klaviyo 兼容产品饲料
- 多种货币支助
- 完整的产品细节,包括库存、定价和品牌信息
- 支持计算出价格的产品变体
先决条件
- 美杜莎服务器(v 2. 4. 0 或以上)
- 具有 API 证书的 Klaviyo 账户
安装
yarn add @eancarr/klaviyo-medusa
或与 npm :
npm install @eancarr/klaviyo-medusa
然后将插件添加到您的 medusa-config.js 文件 :
const plugins = [
// ...
{
resolve: "@eancarr/klaviyo-medusa",
options: {
apiKey: process.env.KLAVIYO_API_KEY,
},
},
];
配置
配置选项
| 选项 | 类型 | 说明 | 默认 |
|---|---|---|---|
apiKey | string | 您的 Klaviyo API 密钥 | undefined |
环境变量
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的营销同意,你应该在客户的元数据中设置同意设置. 这确保只有明确表示同意的客户才遵守隐私条例.
在收集客户信息(注册、通讯注册或离职)时,用克拉维约同意旗更新客户元数据:
// 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的产品饲料:
-
访问您的产品饲料 :
https://your-medusa-url.com/feeds/products/{currencyCode}- 替换
{currencyCode}用你的商店的货币代码(例如,usd, (中文(简体) ),eur(中文(简体) )
- 替换
-
在你的克拉维约账户里:
- 转到"Content" → "出产"
- 点击“ 管理自定义目录源”
- 单击“ 添加新源”
- 输入您的产品种子 URL
- 根据需求配置同步设置
产品饲料包括综合产品数据:
- 产品标识
- 标题
- 说明
- 处理/粘贴
- 斯库
- 缩略图和图像
- 品牌 资料
- 定价信息(最低/最高价格,价格比较)
- 货币
- 产品 URL
- 类别
- 库存数量和供应状况
- 计算出价格的产品变体
扩展插件
您可以通过 :
- 在您的 Medusa 服务器中创建使用 Klaviyo 服务的自定义工作流程
- 添加额外事件订阅者以同步更多数据类型
- 增强发送给克拉维约的数据结构
在您自己的代码中使用克拉维约服务的例子 :
// Access the Klaviyo service
const klaviyoService = container.resolve("klaviyoService");
// Create an event
await klaviyoService.createEvent({
metric: {
name: "Custom Event",
},
profile: {
email: "[email protected]",
},
properties: {
// Your custom properties
},
});
// Upsert a customer profile
await klaviyoService.upsertProfile({
email: "[email protected]",
phone_number: "+1234567890",
// ... other profile attributes
});
// Bulk subscribe profiles
await klaviyoService.bulkSubscribeProfiles([
{
type: "profile",
id: "profile-id",
attributes: {
email: "[email protected]",
subscriptions: {
email: {
marketing: {
consent: "SUBSCRIBED",
},
},
},
},
},
]);
地方发展
# Clone the repository
git clone https://github.com/eancarr/klaviyo-medusa.git
# Install dependencies
cd klaviyo-medusa
yarn
# Start development server
yarn dev
许可证
麻省理工学院