Docsbook
概要

追跡されたイベント

ページビューからは、どのページが開かれたかがわかります。しかし、読者がスニペットをコピーしたか、アシスタントに質問したか、イントロダクションをスクロールして通り過ぎたか、サインアップページに移動したかまではわかりません。このページには、その他に記録されるすべての内容がフィールドごとに一覧されています。そのため、目標やファネルを作成する前に、測定したい対象がすでに測定されているかどうかを確認できます。

得られるもの#

7つのカテゴリに分類された36種類の名前付き docs.* イベントが、設定やタグマネージャーなしで、すべての ドキュメントサイトに記録されます。それぞれをFeedsでフィルタリングしたり、目標と 照合したり、アナリティクス概要で順位付けしたり、MCP経由で訪問者ごとに 読み返したりできます。

これらの記録によってプロジェクトの残高が消費されることはなく、プランによって リストの内容が変わることもありません。

カタログ#

すべてのイベントには、プロジェクトの完全な名前（owner/repo）が含まれます。追加で含まれるもの列には、それに加えて追加される内容が示されます。ビーコンとマークされたイベントは、読者がページを離れる瞬間にnavigator.sendBeaconによって送信されます。それ以外のイベントは、2秒間まとめて送信する通常のログ転送を使用します。

AIアシスタント#

イベント 発生条件 併せて送信される情報
docs.ai_open 閲覧者がアシスタントパネルを開いたとき conversation_id
docs.ai_query 質問が送信されたとき question, answer, conversation_id, turn
docs.ai_like / docs.ai_dislike 回答に対してサムズアップまたはサムズダウンが付けられたとき path, conversation_id, question
docs.ai_copy 回答がコピーされたとき conversation_id
docs.ai_navigate 回答が引用したリンクがクリックされたとき query, path, conversation_id, source (badge または sources) — ビーコン
docs.ai_outbound 回答内のリンクによって閲覧者がサイト外へ移動するとき href, host, conversation_id, question — ビーコン
docs.ai_conversation 会話ごとに1回、最初の成功した回答にタイトルが付けられたとき topic, intent, competitor, question, answer_completeness, gap_type
docs.ask_ai_outline ページのアウトラインから「AIに質問」が押されたとき —

docs.ai_navigate と docs.ai_outbound は、意図的に1つではなく2つのイベントです。 前者は、閲覧者が回答を信頼し、回答が引用したページを開くほど十分に納得したことを示します。 後者は、アシスタントが閲覧者をあなたのアプリ、リポジトリ、またはまったく別の場所へ引き渡したことを示します。 これは理解度に関する質問ではなく、商業的な質問です。

イベント 発生条件 併せて渡される情報
docs.search_open ページ上の検索ボックスが開かれたとき —
docs.search_navigate 検索結果がクリックされたとき query, path
docs.search_no_result クエリに一致する結果がなかったとき query

閲覧とエンゲージメント#

イベント 発生条件 併せて送信される情報
docs.pageview ページが配信されたとき path、lang、trafficType、referrer、userAgent、source、およびエッジが解決した国/地域/都市/座標
docs.read_time 読者がページを離れたとき path、seconds — ビーコン
docs.heading_view 見出しが表示領域にスクロールされたとき path、heading（#anchorとして） — ビーコン
docs.scroll_to_top ページ上部へ戻るコントロールが使用されたとき —
docs.widget_toggle コンテンツウィジェットが開閉されたとき widget、enabled
docs.theme_toggle ライト/ダークが切り替えられたとき theme
docs.language_switch 言語ピッカーが使用されたとき from、to

docs.pageviewは、ブラウザーが送信しない唯一のイベントです。これは サーバー側で記録されるため、JavaScriptを無効にしている読者にも存在します。これが、 ページビューだけで構成される訪問がクローラーとして扱われる理由でもあります。キャッシュから 配信されるページでは、代わりにブラウザーからページビューのビーコンが送信され、取り込みエンドポイントが 同じIPと地理情報を補完するため、どちらの経路でも同じ行が生成されます。

secondsは生のまま発行され、レポートで合計される前に300秒で切り詰められます。 この切り詰め処理とその理由については、読了時間で説明しています。

コンテンツ操作#

イベント 発生するタイミング 併せて渡される情報
docs.copy_code コードブロックがコピーされたとき —
docs.copy_page ページ全体がコピーされたとき —
docs.copy_markdown ページがMarkdownとしてコピーされたとき —
docs.copy_dropdown コピー メニューが使用されたとき action
docs.edit_on_github 「GitHubで編集」がクリックされたとき path
イベント 発生するタイミング 併せて渡されるもの
docs.sidebar_nav サイドバーの項目がクリックされたとき path
docs.heading_nav ページ内アウトラインの項目がクリックされたとき heading, path
docs.page_nav 前へ／次へが使用されたとき direction（prev または next）、path
docs.internal_link 別のページへのページ内リンクがクリックされたとき href

docs.heading_nav と docs.heading_view は意図的に #anchor 形式を共有しているため、読者がそのセクションに移動した場合でも、そこまでスクロールした場合でも、同じように集計されます。

離脱と流入元#

イベント 発生するタイミング 併せて含まれる情報
docs.outbound_link ドキュメント内のリンクが外部へ遷移するとき href、host、path — ビーコン
docs.header_link サイトヘッダーのリンクがクリックされたとき label、href
docs.utm キャンペーンタグ付きで訪問が到着したとき 指定されたutm_*パラメータ
docs.page_exit 読者がサイトを離れるか、再読み込みするとき path — ビーコン
docs.claim_banner_seen 公開/クレームバナーが表示されたとき claim_token
docs.claim_click 公開/クレームバナーがクリックされたとき claim_token — ビーコン

docs.page_exitは、実際の離脱または再読み込みが発生した場合にのみ発火します。サイト内ナビゲーションでは発生しないため、訪問における最後のdocs.page_exitが、読者が実際に離脱したページになります。

フィードバック#

イベント 発生するタイミング 追加で含まれる情報
docs.page_feedback_up ページが役に立ったと投票されたとき path、国
docs.page_feedback_down ページが役に立たなかったと投票されたとき path、国

方向は vote フィールドではなく、イベントの名前に含まれます。イベント ストアのスキーマはフィールド名の固定セットであり、認識されないフィールドは 破棄されるのではなく、そのまま拒否されます。投票はサーバールートを通じて記録されるため、 Webhookを発火させることができます。そのリクエストが失敗した場合は、ブラウザが 同じイベントを直接記録するため、カウントは保持されます。

自動、または機能の利用状況に依存#

Docsbook のどこにもトラッキングの切り替えはなく、どのイベントにも enabled フラグはありません。上記の各イベントは、それを生成するものが存在する場合に必ず発生するため、一覧は次の 2 つに分かれます。

常に 機能の利用開始後のみ
ページビュー、閲覧時間、見出しの表示、離脱、コピー、内部リンクと外部リンク、サイドバーおよび前後ナビゲーション、検索、テーマ、トップへスクロール すべての docs.ai_* イベント（読者向けアシスタントが必要です。これは有料機能です — 料金をご覧ください）、docs.language_switch（2 つ目の言語が必要）、docs.edit_on_github（リンクされたリポジトリが必要）、docs.utm（自分でタグ付けしたリンクが必要）、docs.widget_toggle（ページ上のウィジェットが必要）、フィードバックの 2 つのイベント（投票ウィジェットが必要）、2 つの docs.claim_* イベント（未クレームのサイトでのみ）

したがって、レポートにおける「空の」イベントには 2 通りの解釈があり、それぞれ意味が異なります。誰も実行しなかったか、まだ実行できるものがないかのどちらかです。

配信方法#

通常のイベントは、2秒間まとめてバッチ処理し、fetch 経由で送信するトランスポートを通ります。ページを離れてもページが表示されたままになるクリックにはこれで問題ありませんが、そうでないクリックではすべて失われます。そのため、離脱に関連するイベントは別の経路を取ります:

  1. コンポーネントは離脱コレクターを登録します。pagehide では、すべてのコレクターの内容を1つのビーコンにまとめ、最大100件に制限して同一オリジンのエンドポイントに送信します。
  2. iOSでは、visibilitychange → hidden が同じフラッシュをトリガーします。pagehide はiOSでは信頼性が低いためです。
  3. コレクターはまだ送信していないものだけを返すため、iOSでのフラッシュ後に実際の離脱が続いても二重計上されず、戻る/進むキャッシュから復元されたページでは再度フラッシュできます。

見出しの表示は、しきい値0の IntersectionObserver と -15% の下部マージンを使って収集され、各見出しは一度確認されると監視を解除されます。見出しはページビューごとに1回だけカウントされ、ビューポートの下端を通過した後にのみカウントされます。見出しが少しでも表示された瞬間ではありません。

なぜこれが正しい方法なのか#

規則 これを実行するブラウザーで機能する理由 出典
終了時イベントは beacon で送信し、デバウンスした fetch は決して使用しない Beacon リクエストは「ページがアンロードされる前に開始されることが保証され、ブロッキングリクエストを必要とせずに完了まで実行できる」 W3C Beacon API
イベントを送信するために終了処理をブロックしない Beacon 仕様が対処した代替手段、つまり「同期 XMLHttpRequest によるブロッキングリクエストの発行や、何もしないビジーループの挿入」は、「ユーザーエージェントによる時間的制約のある操作の実行をブロックし……ユーザー体験を損なう」 W3C Beacon API
pagehide を監視し、さらに可視性の変更も監視する unload は「依然として信頼性が低いため、絶対に必要な場合を除いて使用を避ける」べきであり、pagehide は「unload イベントが発生するすべてのケースで発生」し、さらに前後のキャッシュへの入場時にも発生する web.dev: bfcache
スクロールハンドラーではなく、IntersectionObserver で見出しの表示を検出する DOM クエリによる位置計算は「（高コストな）スタイルの再計算とレイアウトを引き起こすことが知られており」、サイトが「スクロールハンドラーを乱用」すると「スクロール時のジャンク」を引き起こす。非同期配信により「高コストな DOM およびスタイルのクエリ、継続的なポーリングが不要になる」 W3C Intersection Observer
見出しがフォールドを通過したら、rootMargin を使って一度だけカウントする rootMargin は「オフセットを適用し……交差の計算に使用するボックスを実質的に拡大または縮小する」――「技術的に重なった」のではなく「実際に到達した」と正直に言える方法 W3C Intersection Observer
非表示中もカウントし続けるページは、誤ったものを計測している Page Visibility API が存在するのは、「ウェブ開発者がウェブページは常に表示されているかのように設計してきた」ため W3C Page Visibility Level 2

1人の訪問者のイベントを読み取る#

2つのMCPツールで、匿名の1人の訪問者の経路を最初から最後まで再構成できます。どちらも 読み取り用です。get_top_visitors は期間中に最もアクティブな訪問者を一覧表示し、 get_visitor_activity は1人の訪問者のイベントを順番に返します。

get_top_visitors(period: "7d", limit: 25)
  → [{ visitor_id: "a1b2…", pageview_count: 14, first_seen, last_seen, country }, …]
 
get_visitor_activity(visitor_id: "a1b2…", period: "7d")
  → { first_seen, last_seen, country, language, pageview_count,
      events: [
        { event: "docs.pageview",           at, path: "guides/quick-start" },
        { event: "docs.page_feedback_down", at, path: "guides/quick-start" },
        { event: "docs.search_no_result",   at, query: "rotate api key" },
        … ] }

visitor_id は、プロジェクトの範囲に限定された訪問者のIPのソルト付きハッシュです。生の IPアドレスが返されることはありません。詳しくは 測定の仕組みをご覧ください。

制限と未解決の問題#

  • docs.* イベントでは、どのウェブフックも発火しません。 これらのイベントはイベント ウェアハウスに存在し、ディスパッチするものはありません。Feeds でフィルタリングして リストに保存することはできます。また、そこではそれらが not_sent として読み取られますが、 それが実際の状態だからです。読者の行動に関するアラートは、このカタログではなく、 派生したウェブフックイベント（トラフィック減少、人気の検索、結果なしの検索）を通じて行われます。 ウェブフックを参照してください。
  • イベントは訪問単位ではなく、イベント単位でカウントされます。 1人の読者が5つの スニペットをコピーすると、docs.copy_code の行が5つになります。訪問単位でカウントする必要があるもの （直帰、コンバージョン、目標）はすべて、このリストを合計するのではなく、訪問を再構築して 導出されます。
  • JavaScriptを無効にしている読者が寄与するのは docs.pageview のみです。 上記の その他すべてのイベントには実行中のスクリプトが必要であり、これはまさに行動クローラーのフィルターが 依存しているものです。
  • question と answer のフィールドには、読者が入力した内容がそのまま含まれます。 生のイベント読み取りは、 キーまたは値がトークン、キー、JWT、認証ヘッダーのように見えるフィールドをマスクする リダクターを通過します。しかし、読者があなたのアシスタントに個人的な情報を入力すれば、 それはイベントストアにも入力されます。保持期間は30日です。
  • 未解決：カタログは信頼できる情報源ですが、ストリームのすべてを網羅しているわけではありません。 確認できるのは、 この36個の名前が、パネル、Feeds、目標の検証、MCPというすべてのサーフェスが1つの共有リストから 読み取る名前であり、したがって目標を宣言できるのはその中の名前だけだということです。確認できないのは、 追加の docs.* 名が少数、未登録サイトのティーザーフローによって出力され、 そのリストには含まれていないことです。つまり、それらはストアには到達しますが、UIには表示されません。 36個を、操作できるイベントの完全なセットとして扱ってください。ストリーム内のすべての文字列を 網羅した完全な一覧として扱わないでください。

このページは役に立ちましたか？

提供： Docsbook