implementing-api-surveys

实现 API 调查

api 调查在 PostHog 中只是一个定义。PostHog 不会渲染它。应用负责渲染问题并捕获调查事件。如果事件或其属性有误，回复就会缺失、重复计数或无法归因。

1. 获取调查

使用 posthog:survey-get 按 id 获取调查。记录每个问题的 id、type、question、选项、评分范围和 optional，以及 current_iteration。切勿臆造问题 id。

如果调查尚不存在，请先使用 creating-surveys 技能创建调查（类型为 api）。设计指南（简短、先评分或选择题，再开放文本题）也在其中。此处不要重复说明。

2. 阅读用户的代码库

编写 UI 之前，先找到：

• 框架以及现有的组件库或设计系统。使用这些组件构建调查，而不是使用通用模态框。
• PostHog 的初始化位置，以及已安装的 SDK 和版本（package.json 或锁文件，或服务器语言的清单文件）。
• 调查应该出现的位置。由应用负责触发：将调查的事件、URL 和选择器 conditions 留空，并在调查应该出现时运行下面的查询。getActiveMatchingSurveys 只有在事件条件满足后才会返回调查，而此时不会有任何代码再次运行查询。

选择合适的路径：

• 浏览器应用，使用 posthog-js：继续阅读下文。
• 服务器渲染页面、其他 SDK（Python、Node、Go、Ruby、PHP）或自定义移动端 UI：阅读 server-and-mobile.md，然后跳至第 5 步。移动端 SDK 只能原生渲染弹出式调查，因此自定义移动端 UI 应遵循服务器端模式。

3. 浏览器端约定（posthog-js）

要求使用 posthog-js 1.249.2 或更高版本。较旧版本在捕获时不会设置用户属性和已查看状态。应告知用户升级，而不是手动添加这些属性。

只有在功能标记和调查资源包都加载完成后，查询才会生效，因为定向评估依赖功能标记，而且调查加载前 getActiveMatchingSurveys 不会执行任何操作。在启动时分别为两者注册一次重试，并避免重复渲染，因为 onFeatureFlags 每次重新加载功能标记时都会运行（在 identify 之后以及每次回复之后）。

let triggered = false
let rendered = false

function tryShowSurvey() {
  if (!triggered || rendered) return
  posthog.getActiveMatchingSurveys((surveys) => {
    const survey = surveys.find((s) => s.id === SURVEY_ID)
    if (!survey || rendered) return
    rendered = true
    renderSurvey(survey)
  })
}

// Register once at startup, not per trigger.
posthog.onFeatureFlags(tryShowSurvey)
posthog.onSurveysLoaded(tryShowSurvey)

function showSurveyIfEligible() {
  triggered = true
  tryShowSurvey()
}

// Call when the survey closes, after the final send or a dismiss.
function onSurveyClosed() {
  triggered = false
  rendered = false
}

从应用的触发点调用 showSurveyIfEligible()，例如结账完成后；如果调查应在页面加载时显示，也可以在设置完成后立即调用。调查关闭时调用 onSurveyClosed()，这样可重复的调查会在下次触发时再次显示。不可重复的调查会保持隐藏，因为 posthog-js 会将其标记为已查看。在单页应用中，应在应用初始化 PostHog 的位置注册这两个监听器；如果该代码可能卸载，则调用它们返回的函数取消订阅。SURVEY_ID 是第 1 步中的 id。renderSurvey 会挂载你使用应用自身 UI 构建的组件，该组件会调用下方的处理函数。getActiveMatchingSurveys 会根据该用户应用调查的定向规则，因此只渲染它返回的内容。

捕获三个事件。answers 将每个问题 id 映射到其答案，并包含本次提交中截至目前给出的所有答案。确切的属性名称和值格式见 event-contract.md。

function onShown(survey) {
  posthog.capture('survey shown', {
    $survey_id: survey.id,
    $survey_iteration: survey.current_iteration,
  })
  // posthog-js reads this key for the survey wait period; only its own renderer writes it.
  try {
    localStorage.setItem('lastSeenSurveyDate', new Date().toISOString())
  } catch {}
}

function onSubmit(survey, answers, submissionId, completed) {
  posthog.capture('survey sent', {
    $survey_id: survey.id,
    $survey_iteration: survey.current_iteration,
    $survey_submission_id: submissionId,
    $survey_completed: completed,
    $survey_questions: survey.questions.map(({ id, question }) => ({ id, question })),
    ...Object.fromEntries(
      Object.entries(answers).map(([questionId, value]) => [`$survey_response_${questionId}`, value])
    ),
  })
}

function onDismiss(survey) {
  posthog.capture('survey dismissed', {
    $survey_id: survey.id,
    $survey_iteration: survey.current_iteration,
  })
}

会导致数据问题但不易察觉的规则：

• 在受访者开始作答时生成一个 $survey_submission_id（crypto.randomUUID()），并在本次提交的每次发送中重复使用。PostHog 按此 id 对回复去重并计费。没有此 id 的每个事件都会被计为一条单独的回复。
• 部分发送时，$survey_completed 为 false；最终发送时为 true。
• 每次发送都要包含截至目前的所有答案，而不只是最新答案。PostHog 会保留每个提交 id 的最新事件。
• 评分以数字形式发送，与 posthog-js 的发送方式一致。多选题以字符串数组形式发送。只为已回答的问题发送 $survey_response_<question_id> 键。
• 关闭表示未作答而直接关闭。最终发送 survey sent 后，不要再发送 survey dismissed。

4. 不要在浏览器中手动设置已查看状态

posthog-js 在捕获 survey sent 或 survey dismissed 时，会设置 $survey_responded/<id>[/<iteration>] 或 $survey_dismissed/...，以及本地已查看标记。这会阻止再次向用户展示该调查。自行添加这些属性会造成重复。

5. 验证第一条回复

请用户在实际应用中触发一次调查并提交。然后：

1. 针对调查的 id 调用 posthog:surveys-responses-list。问题文本会在服务器端解析。确认答案显示在正确的问题下，并且多选答案以列表形式传入。
2. 针对调查的 id 调用 posthog:survey-stats。确认 shown 和 sent 计数有所增加，并且一次提交对应一条回复，而不是两条。
3. 如果没有收到任何内容，请检查项目令牌，并确认实时事件中出现了 survey sent，然后按照 debugging-surveys 中的步骤操作。不要猜测。

报告你实现的内容、触发器所在位置，以及已验证的回复。