Implémenter des sondages API

Un sondage api n'est qu'une définition dans PostHog. PostHog ne le rend pas. L'application rend les questions et capture les événements du sondage. Si les événements ou leurs propriétés sont incorrects, les réponses peuvent être manquantes, comptabilisées en double ou non attribuées.

1. Récupérer le sondage

Récupérez-le avec posthog:survey-get par id. Notez l'id, le type, la question, les choix, l'échelle et le caractère optional de chaque question, ainsi que current_iteration. N'inventez jamais d'ids de question.

Si le sondage n'existe pas encore, créez-le d'abord avec la skill creating-surveys (type api). Les conseils de conception (court, évaluation ou choix en premier, texte ouvert en deuxième) s'y trouvent aussi. Ne les répétez pas ici.

2. Lire la base de code de l'utilisateur

Avant d'écrire l'interface, trouvez :

Le framework et la bibliothèque de composants existante ou le système de conception. Construisez le sondage à partir de ces composants, pas à partir d'une modal générique.
Où PostHog est initialisé, et le SDK installé et sa version (package.json ou lockfile, ou le manifeste du langage serveur).
Où le sondage doit apparaître. Laissez l'app en contrôle du déclencheur : laissez vides l'événement du sondage, l'URL et les conditions du sélecteur, et exécutez la recherche ci-dessous au moment où le sondage doit apparaître. getActiveMatchingSurveys retourne un sondage avec conditions d'événement seulement après que cet événement se déclenche, et rien ne ré-exécute la recherche à ce moment-là.

Choisissez le chemin :

App navigateur avec posthog-js : continuez ci-dessous.
Pages rendues côté serveur, autres SDKs (Python, Node, Go, Ruby, PHP), ou interface mobile personnalisée : lisez server-and-mobile.md, puis retournez à l'étape 5. Les SDKs mobiles ne rendent que les sondages popover nativement, donc une interface mobile personnalisée suit le modèle serveur.

3. Contrat navigateur (posthog-js)

Exigez posthog-js 1.249.2 ou plus récent. Les versions antérieures ne définissent pas les propriétés de personne et l'état vu lors de la capture. Dites à l'utilisateur de mettre à niveau plutôt que de les ajouter manuellement.

La recherche fonctionne seulement une fois que les flags et le bundle de sondages sont chargés, car le ciblage est évalué avec les flags et getActiveMatchingSurveys ne fait rien avant que les sondages se chargent. Enregistrez une tentative pour chacun au démarrage, et gardez-vous contre un double rendu, puisque onFeatureFlags s'exécute aussi à chaque rechargement de flag (après identify, et après chaque réponse).

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)
  })
}

// Enregistrez une fois au démarrage, pas par déclencheur.
posthog.onFeatureFlags(tryShowSurvey)
posthog.onSurveysLoaded(tryShowSurvey)

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

// Appelez quand le sondage ferme, après l'envoi final ou un rejet.
function onSurveyClosed() {
  triggered = false
  rendered = false
}

Appelez showSurveyIfEligible() à partir du déclencheur de l'app, comme après la fin d'une commande, ou juste après la configuration si le sondage appartient au chargement de page. Appelez onSurveyClosed() quand le sondage ferme, afin qu'un sondage qui peut se répéter s'affiche à nouveau au prochain déclencheur. Un sondage qui ne peut pas se répéter reste caché, car posthog-js le marque comme vu. Dans une app monopage, enregistrez les deux listeners où l'app initialise PostHog, et appelez les fonctions qu'elles retournent pour vous désabonner si ce code peut se démonter. SURVEY_ID est l'id de l'étape 1. renderSurvey monte le composant que vous construisez à partir de l'interface de l'app elle-même, et ce composant appelle les gestionnaires ci-dessous. getActiveMatchingSurveys applique le ciblage du sondage pour cette personne, donc rendez seulement ce qu'il retourne.

Capturez trois événements. answers mappe chaque id de question à sa réponse, et contient chaque réponse donnée jusqu'à présent dans cette soumission. Les noms de propriétés exacts et les formes de valeurs sont dans event-contract.md.

function onShown(survey) {
  posthog.capture('survey shown', {
    $survey_id: survey.id,
    $survey_iteration: survey.current_iteration,
  })
  // posthog-js lit cette clé pour la période d'attente du sondage ; seul son propre renderer l'écrit.
  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,
  })
}

Règles qui causent des problèmes de données silencieux :

Générez un $survey_submission_id (crypto.randomUUID()) quand le répondant commence, et réutilisez-le pour chaque envoi de cette soumission. PostHog déduplique et facture les réponses par cet id. Les événements sans lui comptent chacun comme une réponse séparée.
$survey_completed est false pour un envoi partiel et true pour l'envoi final.
Envoyez chaque réponse jusqu'à présent à chaque envoi, pas seulement la plus récente. PostHog garde le dernier événement par id de soumission.
Les évaluations vont en nombre, comme posthog-js les envoie. Le choix multiple va comme un tableau de chaînes. Envoyez une clé $survey_response_<question_id> seulement pour les questions auxquelles il a été répondu.
Rejeter signifie fermer sans répondre. N'envoyez pas survey dismissed après un survey sent final.

4. Ne définissez pas l'état vu à la main dans le navigateur

posthog-js définit $survey_responded/<id>[/<iteration>] ou $survey_dismissed/... et le flag vu local quand il capture survey sent ou survey dismissed. C'est ce qui empêche le sondage d'être offert à nouveau. Ajouter ces propriétés vous-même le duplique.

5. Vérifier la première réponse

Demandez à l'utilisateur de déclencher le sondage une fois dans l'app réelle et de le soumettre. Ensuite :

Appelez posthog:surveys-responses-list pour l'id du sondage. Les lignes résolvent le texte de la question côté serveur. Confirmez que la réponse apparaît sous la bonne question, et que les réponses à choix multiple arrivent comme une liste.
Appelez posthog:survey-stats pour l'id du sondage. Confirmez que les comptes shown et sent ont bougé, et qu'une soumission est une réponse, pas deux.
Si rien n'arrive, vérifiez le jeton du projet et que survey sent apparaît dans les événements en direct, puis suivez debugging-surveys. Ne devinez pas.

Rapportez ce que vous avez implémenté, où le déclencheur se trouve, et la réponse vérifiée.

implementing-api-surveys