API REFERENCE
CTA 配置 API
通过 API 创建、管理和复用 CTA 组件，精准控制内容中的转化触点
CTA 类型与数据结构
翠鸟支持多种 CTA 类型，每种类型对应不同的转化目标。所有 CTA 都是可复用的组件，可挂载到一个或多个内容资源上。
| 类型 | 说明 | 主要字段 |
|---|---|---|
form | 留资表单，访客填写后创建线索 | fields, submit_label, success_message |
button | 跳转按钮，引导访客到指定URL | label, url, open_in_new_tab |
modal | 弹出层，包含表单或富文本内容 | trigger_on, delay_seconds, content |
banner | 顶部/底部固定横幅 | position, message, button_label, button_url |
// CTA 对象示例
{
"id": "cta_abc123",
"name": "白皮书下载留资",
"type": "form",
"status": "active",
"fields": [
{"name": "name", "label": "姓名", "type": "text", "required": true},
{"name": "email", "label": "邮箱", "type": "email", "required": true},
{"name": "company", "label": "公司名", "type": "text", "required": true},
{"name": "phone", "label": "电话", "type": "tel", "required": false}
],
"submit_label": "立即下载",
"success_message": "感谢您的下载！我们会在24小时内将文件发送至您的邮箱。",
"attached_resources": ["res_7fK2mPqLxNz", "res_9pL3nQrZwY"],
"created_at": "2024-02-20T10:00:00Z"
}
创建与管理 CTA
创建一个留资表单 CTA
curl -X POST https://api.cuiniao.com/v1/cta \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Q2 产品演示申请",
"type": "form",
"fields": [
{"name": "name", "label": "您的姓名", "type": "text", "required": true},
{"name": "email", "label": "工作邮箱", "type": "email", "required": true},
{"name": "company", "label": "公司名称", "type": "text", "required": true}
],
"submit_label": "申请演示",
"success_message": "申请已收到，我们将在1个工作日内联系您！"
}'
将 CTA 挂载到内容资源
curl -X POST https://api.cuiniao.com/v1/resources/res_7fK2mPqLxNz/cta \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"cta_id": "cta_abc123",
"display_trigger": "scroll_50", // 滚动50%时显示
"position": "inline" // inline | sticky_bottom | exit_intent
}'
一个 CTA 组件可挂载到多个内容资源，修改 CTA 配置后所有挂载点同步生效，无需逐一更新内容。
CTA 展示触发条件
通过 display_trigger 字段控制 CTA 在何时向访客展示，合理设置触发条件可显著提升转化率。
immediate— 页面加载后立即展示scroll_25/scroll_50/scroll_75— 页面滚动到指定深度时触发dwell_30s/dwell_60s— 访客停留指定时长后触发exit_intent— 鼠标移向浏览器关闭区域时触发（仅桌面端）content_end— 访客阅读至内容末尾时触发
查询 CTA 转化数据
通过 GET /v1/cta/{id}/stats 获取 CTA 的曝光、点击和提交数据。
curl "https://api.cuiniao.com/v1/cta/cta_abc123/stats?days=30" \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx"
// 响应
{
"cta_id": "cta_abc123",
"period_days": 30,
"impressions": 1248,
"clicks": 186,
"submissions": 43,
"click_rate": "14.9%",
"conversion_rate": "3.4%"
}