用途:这是 Klaviyo 的次级工作流,覆盖事件追踪、分群查询、营销活动创建与发送,以及基于指标的流程触发,均通过 klaviyo-api SDK 完成。
前置条件:需先完成 klaviyo-core-workflow-a(profiles/lists 已配置);API key 需具备 events:write、segments:read、campaigns:read、campaigns:write、flows:read 权限;已安装 klaviyo-api 并设置环境变量 KLAVIYO_PRIVATE_KEY。
主要能力与用法:
- 服务端事件追踪:new EventsApi(session).createEvent(...),需包含 metric.data.attributes.name(可自动创建指标)、profile、用于收入归因的 value,以及用于去重的 uniqueId。自定义指标可触发监听该指标的流程。
- 查询事件与指标:MetricsApi.getMetrics() 列出事件类型;EventsApi.getEvents({ sort: '-datetime', filter: 'equals(metric_id,"...")' }) 读取近期事件。
- 分群操作:SegmentsApi.getSegments() 列出分群,getSegmentProfiles() 读取成员,getSegment({ additionalFieldsSegment: ['profile_count'] }) 返回规模,发送前应先检查。
- 创建邮件营销活动:按顺序四步——创建模板、创建活动(含 audiences.included/excluded)、将模板分配给活动消息、创建 campaign-send-job。未分配模板即发送会返回 400。
- 查询流程(只读):FlowsApi.getFlows() 列出流程;getFlowFlowActions({ id }) 返回各流程步骤及状态。
输出:事件追踪返回 HTTP 202 Accepted(Klaviyo 异步排队),事件会出现在 profile 活动流并触发监听流程;指标/分群/流程查询返回 body.data 记录数组;活动创建返回 campaign id,发送任务排队后由应用内分析报告投递情况。
常见事件名与触发:Placed Order(购买完成,购后/交叉销售)、Started Checkout(购物车创建,弃购)、Viewed Product(商品页访问,浏览放弃)、Ordered Product(单品追踪,评价请求)、Fulfilled Order(发货,发货确认)、Cancelled Order(取消,挽回)、Subscribed to List(邮件/短信注册,欢迎系列)、Custom Event(任意 API 事件,自定义自动化)。
错误处理:指标名为空返回 400,需始终包含 metric.data.attributes.name;分群 ID 错误返回 404,用 getSegments() 核对;活动发送失败返回 400,需先分配模板并设置受众;重复事件因 uniqueId 内置去重,可安全重试。
限制:流程仅支持只读查询;完整可复制代码与场景见 references/implementation.md 与 references/examples.md;常见错误另见 klaviyo-common-errors 技能。