creating-surveys

アンケートの作成

ユーザーの目的に沿った有用な下書きを作成し、公開前に対象者と配信方法を確認します。 このワークフローは、アンケートエディターを開かずに MCP 経由で実行できます。

配信方法と質問を選ぶ

依頼内容から名前、目的、質問を推測します。アンケートの配信先や配信方法を左右する情報が不足している場合に限り、確認してください。

ユーザーの目的	アンケートの種類	配信要件
アプリ内でのフィードバック	popover	アンケートが有効になっている、サポート対象の PostHog SDK
常時表示されるフィードバックボタン	widget	SDK のサポートとウィジェットの設定
共有可能なホスト型フォーム	external_survey	ホスト型アンケートのリンク。アプリ内ターゲティングは不要
アプリケーションコードで作成するカスタムフォーム	api	アプリで質問を表示し、アンケートイベントを記録する

質問の種類、評価尺度、分岐、翻訳については、推測で JSON の形式を決めず、現在のツールスキーマを確認してください。最小限の出発点は例にあります。

回答を促す設計

アプリ内アンケートでは、次の選択が回答率の向上につながります。質問に関するアドバイスはデフォルトで適用してください。トリガーと対象者については推奨を伝え、ユーザーが依頼していないトリガーや対象者を追加する前に確認してください。どちらもアンケートを受け取る人を変えるためです。根拠とその限界については、回答率を参照してください。

• 尋ねている出来事が起きたタイミングでトリガーします。 購入手続きの完了や機能の利用など、その出来事を示すイベントの後に conditions.events を使ってアンケートを表示することを推奨してください。イベントをトリガーとするアンケートは、ページベースのものと比べて回答数が約2倍になります。URL 条件だけの場合は、すべてのページでアンケートを表示する場合とほぼ同じです。イベントを使う前に、そのイベントがプロジェクトに存在することを確認してください。
• 最初の質問はワンクリックで答えられるものにします。 単一選択または短い評価から始めてください。自由記述の質問で始まるアンケートは、回答数が約5分の1になります。その後に、任意回答の自由記述で「なぜ」を尋ねてください。
• 短く保ちます。 2～3問のアンケートを始めた人の約10人中4人は、最後まで回答せずに離脱します。ユーザーが追加の質問を希望しない限り、1～3問にしてください。
• enable_partial_responses: true を設定して部分回答を有効にし、回答者が途中でやめても最初の回答を保存します。API 経由でアンケートを作成する場合、デフォルトでは無効です。
• 対象を絞ったオーディエンスを推奨します。 全員に表示するアンケートよりも、特定の人物やコホートを対象とするアンケートのほうが回答数が増えます。
• ポップアップの表示遅延は15秒未満にします。 遅延が長いほど回答数は減ります。

アンケート名、質問、外観に関するテキストは公開コンテンツです。公開されることを事前に明確に伝えずに、顧客の非公開情報を含めないでください。

対象者と表示を確認する

• URL、イベント、デバイス、リンクされたフラグバリアントの条件には conditions を使用します。使用する前に、既存のイベントIDとフラグIDを解決してください。URL 条件では、個人やコホートの対象者は定義されません。
• 個人、グループ、コホートのターゲティングには targeting_flag_filters.groups[].properties[] を使用します。グループは代替ルールであり、グループ内のプロパティはすべて一致する必要があります。リクエストの対象者を翻訳する際は、意図された対象者を維持してください。
• 行動フィルターを含むコホートは、アンケートのターゲティングに直接使用できません。この制限を説明し、サポートされている静的スナップショット、または同等の別の対象者定義を提示してください。スナップショットは元のコホートに合わせて更新されません。この変更について合意を得てください。リクエストを通すためにルールを削除したり、対象者を広げたりしてはいけません。
• ホスト型フォーム（external_survey）では、アプリ内表示条件やターゲティングフラグを使用しません。これらのフィールドをホスト型フォームに追加しないでください。
• カスタマイズが必要でない限り、appearance は省略してください。whiteLabel: true には、組織がホワイトラベリングの権利（Enterprise）を有している必要があります。カスタムカラーのリクエストから権利の保有を推測しないでください。設定する前に権利を確認してください。surveyPopupDelaySeconds は 0 以上でなければなりません。
• 使用しないオプションフィールドは未設定のままにしてください。省略の代わりに null を設定しないでください。質問フィールドとネストされたオブジェクトでは、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 に従ってください。

エラーからの復旧

再試行する前に、validation フィールドと理由を確認してください。外観に関するエラーの場合は、ブランディングの利用権限と指定した外観フィールドを確認してください。ターゲティングに関するエラーの場合は、コホートがサポートされているか、ルールの構造に問題がないかを確認してください。入力を修正する際は、依頼された動作を維持してください。対象ユーザーやブランディングに影響する変更がある場合は、その変更について説明してください。

作成処理は冪等ではありません。タイムアウトした場合や結果が不確かな場合は、作成を再試行する前に posthog:surveys-get-all を使って、既存の下書きがないか確認し、内容を調べてください。名前が一致するだけでは、同じアンケートであるとは限りません。