creating-surveys

创建调查

根据用户的目标创建实用的草稿，然后在发布前确认受众和投放方式。 整个工作流都可以通过 MCP 完成，无需打开调查编辑器。

选择投放方式和问题

根据请求推断调查名称、目的和问题。只有当缺失的信息会影响调查接收者或投放方式时，才询问用户。

用户目标	调查类型	投放要求
在应用内收集反馈	popover	支持调查功能的 PostHog SDK
始终显示的反馈按钮	widget	SDK 支持和小组件配置
可分享的托管表单	external_survey	托管调查链接；不进行应用内定向
在应用代码中构建自定义表单	api	应用渲染问题并捕获调查事件

请检查当前工具架构，确认问题类型、评分量表、分支逻辑和翻译方式，而不要猜测其 JSON 格式。最简起步示例见示例。

提高回复率的设计

这些做法有助于提高应用内调查的回复率。默认采用问题设计方面的建议。推荐触发条件和受众设置；如果用户没有提出要求，添加触发条件或受众前请先征得同意，因为两者都会改变调查的接收者。证据及其局限详见回复率。

• 在用户体验相关时刻触发。 建议在标志该时刻的事件发生后显示调查，例如完成结账或使用某项功能时，通过 conditions.events 设置。事件触发的调查获得的回复约为基于页面的调查的两倍。仅设置 URL 条件的效果，与在每个页面上显示调查差不多。使用某个事件前，请确认该事件已在项目中存在。
• 让第一题只需点击一次即可作答。 从单选题或简短评分题开始。以开放文本题开头的调查只能获得约五分之一的回复。之后再添加可选的开放式问题，询问原因。
• 保持简短。 开始回答两到三题调查的人中，约有 10 人里的 4 人会在完成前退出。除非用户要求更多问题，否则建议设置一到三题。
• 启用部分回复，设置 enable_partial_responses: true，这样用户中途退出时，第一条答案仍会保留。通过 API 创建调查时，该选项默认关闭。
• 建议选择定向受众。 向个人或群组受众展示的调查，比向所有人展示的调查获得更多回复。
• 弹窗延迟保持在 15 秒以内。 延迟越长，回复越少。

调查名称、问题和外观文案都属于公开内容。未经说明其公开可见性，不要将客户隐私信息复制到这些内容中。

验证受众和外观

• 对于 URL、事件、设备和关联的标记变体条件，请使用 conditions。 使用前，先解析现有事件和标记标识符。URL 条件不会定义个人或群组受众。
• 对于个人、群组或队列定位，请使用 targeting_flag_filters.groups[].properties[]。 群组是备选规则；组内的属性必须全部匹配。翻译请求时，保留预期受众。
• 包含行为筛选条件的队列不能直接用于问卷定位。请说明此限制，并提供受支持的静态快照或其他等效的受众定义。快照不会随原队列更新。接受此权衡前，先征得同意；如果请求无法实现，绝不能删除规则或扩大受众范围来满足请求。
• 托管表单（external_survey）不使用应用内显示条件或定位标记。不要为托管表单附加这些字段。
• 除非需要自定义，否则省略 appearance。whiteLabel: true 需要组织拥有白标权益（Enterprise）。不要根据用户要求自定义颜色推断其拥有该权益。设置此项前，先核实权益。surveyPopupDelaySeconds 必须为非负数。
• 不使用可选字段时，将其留空。不要用 null 代替省略；问题字段和嵌套对象的可空规则各不相同。

创建并审核草稿

使用已解析的配置调用 posthog:survey-create。创建草稿时省略 start_date。如果用户已要求立即发布，请继续完成就绪检查并发布，无需再次征求同一项批准。

保留返回的问卷 id。后续问卷工具使用 id，而不是问题 ID、功能标记 ID 或问卷名称。

使用 posthog:survey-get 读取已保存的问卷。与用户一起审核问题、类型、受众、时间安排、响应上限和品牌设置。如果客户端支持，请显示 MCP 问卷应用；否则提供简明的文字审核结果。始终包含返回的 _posthogUrl。已保存配置并不能证明应用内弹窗已成功显示。

如需修改，请先获取已保存的问卷，再调用 posthog:survey-update。问题、条件、外观、定位和翻译可能会替换嵌套值。保留未更改的字段和现有问题 ID，因为这些 ID 会将问题与已收集的响应关联起来。仅对新问题省略 ID。

发布并验证送达情况

在调用 posthog:survey-launch 前，确认：

• 用户已授权面向已审核的受众和配置发布问卷。
• 问卷未归档，且 end_date 不在过去。如果要重新启用现有问卷，请仅在获得授权后取消归档，或清除／延长结束日期。
• 对于应用内投放，项目已启用问卷，且应用的 SDK 支持所请求的功能。事件触发型问卷需要应用中存在实际触发事件。在配置中创建事件名称不会对该事件进行埋点。
• 对于 api 问卷，应用实现需负责显示问卷并捕获事件。创建并发布定义并不会实现相应代码。

使用 id 调用 posthog:survey-launch，然后验证返回状态。报告问卷处于草稿、已发布还是正在等待 SDK／配置步骤。对于托管表单，如果有可验证的公开表单 URL，请将其返回；_posthogUrl 是管理页面，并非答卷者链接。

使用 posthog:survey-stats 或 posthog:surveys-responses-list 检查后续活动。发布后立即显示零条响应，并不能证明投放失败。对于本应已展示的问卷，请参阅 debugging-surveys。

从错误中恢复

重试前，请先阅读验证字段并分析原因。如果外观验证失败，请检查品牌使用权限和提供的外观字段。如果目标定位验证失败，请确认是否支持相应群组，以及规则结构是否正确。修正输入时，请保留所需行为；如果更改会影响受众或品牌，请说明。

创建操作不是幂等的。超时或结果不确定后，请使用 posthog:surveys-get-all 查找并检查可能已存在的草稿，然后再重试创建。名称匹配本身并不能证明它就是同一份调查。