campaign-flow-builder

Campaign Flow Builder

用途

引导用户从业务意图（“我想要一组欢迎邮件”）开始，构建完整且经过验证的流程，包括入口细分群体、延迟、条件分支、A/B 测试和导出步骤。遵循顾问模式：了解目标、建议结构、反复调整，然后创建。

流程是 Lytics 最复杂的对象——此技能让流程更易上手。

环境

需要经过身份验证的 API 访问权限。凭据解析方式请参阅 ../references/auth.md。

Flow API 格式

流程使用节点-边图表示（TranslatedFlow 格式）：

• 节点：旅程中的步骤（触发器、延迟、导出、条件判断、A/B 测试、退出）
• 边：步骤之间的连接（可带条件或概率）

构建流程

步骤 1：了解营销活动目标

对用户意图进行分类：

• “欢迎邮件系列” -> 在进入细分群体时触发，邮件之间设置延迟
• “重新互动营销活动” -> 对沉寂用户触发，进行条件检查，然后导出
• “对两个优惠进行 A/B 测试” -> 触发、A/B 分流、两条导出路径
• “多渠道培育” -> 触发、延迟、条件判断、多个导出渠道

询问：

• 什么会触发用户进入流程？（进入某个细分群体、已属于某个细分群体）
• 有多少个步骤/触点？
• 是否有分支逻辑？（VIP 与普通用户、活跃与不活跃）
• 步骤之间的时间间隔是多少？
• 用户能否重新进入？

步骤 2：验证入口细分群体

流程需要一个触发细分群体。检查它是否存在：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

如果没有合适的细分群体，建议使用 audience-builder skill 或 audience-advisor skill 来创建。

步骤 3：设计流程结构

以文本图示展示拟议的流程：

TRIGGER: On entry to "New Signups" segment
  |
  v
[Send Welcome Email] (export)
  |
  v
[Wait 3 days] (delay)
  |
  v
[Opened Welcome?] (conditional split)
  |           |
  YES         NO
  |           |
  v           v
[Send Offer] [Send Reminder]
  |           |
  v           v
[EXIT]       [EXIT]

与用户反复调整，直到他们满意为止。

步骤 4：构建流程负载

节点类型

触发器（始终为 sequence_id: 0）：

{
  "sequence_id": 0,
  "type": "trigger",
  "entry_segment_id": "segment-uuid-here",
  "entry_condition": "on_segment_entry",
  "reentry_allowed": false,
  "reentry_delay": 86400
}

入口条件：

• "on_segment_entry" —— 用户进入细分群体时触发（基于事件，最常用）
• "in_segment" —— 对当前属于该细分群体的用户触发（快照）

重新进入延迟以秒为单位。最小值为 3600（1 小时）。

导出（发送到外部平台）：

{
  "sequence_id": 1000,
  "type": "export",
  "label": "Send Welcome Email",
  "work_config": {}
}

创建流程后，通过 work 端点单独配置 work_config。

延迟（步骤之间的等待时间）：

{
  "sequence_id": 2000,
  "type": "delay",
  "label": "Wait 3 days",
  "delay": 259200000000000
}

延迟以纳秒为单位。常用值：

• 1 小时：3600000000000
• 24 小时：86400000000000
• 3 天：259200000000000
• 7 天：604800000000000

可选：delay_condition（FilterQL）——仅在满足条件时继续。 可选：delay_until_enters（细分群体 ID 数组）——等待用户进入列出的所有细分群体。

条件分流（if/else 分支）：

{
  "sequence_id": 3000,
  "type": "conditional_split",
  "label": "Opened Welcome?"
}

条件定义在边上，而不是节点上。请参阅“边”部分。

A/B 测试（随机分流）：

{
  "sequence_id": 4000,
  "type": "ab_test",
  "label": "50/50 Test"
}

概率定义在边上。总和必须为 1.0。

退出（流程结束）：

{
  "sequence_id": 9999,
  "type": "exit"
}

边类型

简单连接：

{"id": "0-1000", "source": 0, "target": 1000, "type": "connected"}

条件分流边（带 FilterQL）：

{
  "id": "3000-4000",
  "source": 3000,
  "target": 4000,
  "type": "connected",
  "condition": {
    "definition": "FILTER AND (email_opened = true) FROM user",
    "label": "Yes",
    "priority": 2
  }
}

优先级数字越大，越先检查。默认/回退边应设置 "definition": "" 和 "priority": 1。

A/B 测试边（带概率）：

{
  "id": "4000-5000",
  "source": 4000,
  "target": 5000,
  "type": "connected",
  "probability": 0.5
}

来自同一源节点的所有概率总和必须为 1.0。

步骤 ID 分配

• 触发器始终为 sequence_id: 0
• 其他 ID 均由调用方分配为正整数（在流程中必须唯一）
• 约定：使用 1000 的倍数（1000、2000、3000），以便阅读

步骤 5：确认并创建

使用确认门模式。展示：

• 流程图（文本图示）
• 入口细分群体名称和规模
• 步骤数量和类型
• 时间安排概要
• 原始 API 负载

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... flow payload ... }'

步骤 6：配置导出步骤

在草稿状态下创建流程后，为每个导出步骤配置 work/导出：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}/step/${STEP_ID}/work" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... work configuration ... }'

然后发布 work：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}/step/${STEP_ID}/work/publish" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

步骤 7：激活流程

所有导出步骤都已发布工作后，激活流程：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "running"}'

重要：同一时间只能有一个版本的流程处于 running 状态。发布新版本会自动将旧版本设为 draining。

常见营销活动模式

欢迎系列

TRIGGER (on_segment_entry: "New Signups")
  -> [Send Welcome] -> [Wait 3d] -> [Send Tips] -> [Wait 7d] -> [Send Offer] -> EXIT

重新互动

TRIGGER (in_segment: "Lapsed 30d")
  -> [Send Win-Back] -> [Wait 7d]
  -> CONDITIONAL (opened email?)
     YES -> [Send Discount] -> EXIT
     NO  -> [Send Final Notice] -> EXIT

A/B 测试

TRIGGER (on_segment_entry: "Trial Users")
  -> [Wait 1d]
  -> A/B TEST (50/50)
     A -> [Send Offer A] -> EXIT
     B -> [Send Offer B] -> EXIT

多渠道培育

TRIGGER (on_segment_entry: "High Intent")
  -> [Send Email] -> [Wait 2d]
  -> CONDITIONAL (converted?)
     YES -> EXIT
     NO  -> [Push Notification] -> [Wait 3d]
           -> [Retarget on Facebook] -> EXIT

流程状态

状态	描述	可以编辑吗？
draft	未激活，完全可编辑	可以——添加、移除或修改步骤
running	已激活，正在处理用户	有限——可以更新 work_config、标签和条件；不能添加或移除步骤
draining	正在逐步结束，不接受新条目	与 running 相同
deleted	已永久删除	不可以

错误处理

• 条件中的 FilterQL 无效：创建流程前验证条件
• 概率总和不为 1.0：调整后重试
• 未找到入口细分：通过 audience-builder 帮助创建
• 步骤 ID 重复：重新生成唯一值
• 缺少工作配置：指导完成导出步骤配置

依赖项

• 组合使用：segment-manager skill、audience-builder skill、job-manager skill
• 参考：../references/filterql-grammar.md、../references/confirmation-gate.md、../references/auth.md、../references/api-client.md