ChatGPT Annotationsで適切なUI部品へのフィードバックと文脈を集める方法

プレビュー画面にカードが複数あると、「このカードは少し窮屈」という感想だけでは、開発者はどれを指すのか分かりません。Browser Annotation APIを使えば、閲覧者はカード全体を選び、必要な情報を添え、希望する選択肢を指定してからChatGPTで意見を伝えられます。この手順にはHTTPSまたはlocalhostで開けるテストページと、対応するChatGPTデスクトップアプリの内蔵ブラウザーが必要です。作業の目安は約20分です。

Webサイトが文脈を用意し、送信するかどうかは利用者が決めます。 注釈エディターを開いても、チャットのメッセージは自動送信されません。文脈を取得する手段の違いは、ChatGPT Browser、拡張機能、Computer Useの解説を参照してください。この記事では自社サイトに組み込むAPIに絞ります。

準備するもの

使うのはOpenAIのBrowser Annotation APIです。公式ガイドはDevDay 2026公開版以降のChatGPTデスクトップアプリを対象としています。対応する安全な最上位ページでは、JavaScriptからdocument.oai.annotationを参照できます。通常のChromeタブ、iframe、古いアプリでも使えるとは限りません。必要なメソッドごとに存在を確認し、対象のDOM要素ができてから初期化してください。

利用可能なワークスペースを先に確認してください。 OpenAIによると、Browser Annotation APIは現在ChatGPT EnterpriseおよびEduワークスペースでは利用できません。チームがそれらだけを使っている場合、以下は設計の参考例です。実装予定を立てる前に環境を確認しましょう。

二枚のプレビューカードとフィードバック用ボタンを持つテストページを用意します。架空のデータを使い、認証情報や顧客情報をHTMLに埋め込まないでください。アプリのウィンドウを取り込んで下書きを作りたいだけなら、サイトを変更せずに使えるChatGPT DesktopとAppshotsの手順が適しています。

手順

1. カード全体を名前付きの選択対象にする

Annotation modeでは、ブラウザーは標準の動作でもDOM要素を選べます。ただし見出し、説明、ボタンを含むカードについては、閲覧者がカード全体を指して意見を述べたい場合があります。外側にoai-annotation-container、各カードにoai-annotatableを付けます。後者の値は利用者とモデルに見える名前なので、隣のカードと区別できる言葉を選びます。

<section id="preview" oai-annotation-container>
  <article id="profile-card" oai-annotatable="プロフィールカード">
    <h2>プロフィール</h2>
    <p>チームのメンバー情報と役割。</p>
  </article>
  <article id="summary-card" oai-annotatable="要約カード">
    <h2>要約</h2>
    <p>今週の重要な指標を三つ表示します。</p>
  </article>
</section>

<button id="discuss-profile" type="button" hidden>プロフィールカードに意見を伝える</button>

Annotation modeで見出しや説明にポインターを合わせると、カード全体が強調されるはずです。oai-annotatableをcontainerの外で単独使用しても、選択動作は変わりません。containerの外側は標準の動作のままです。

一文だけを指したい場合は、テキスト領域にoai-annotation-container-textを使います。閲覧者はドラッグして文字を選びます。単にクリックしただけでは注釈は作られません。同じ要素にテキスト選択とDOM選択の属性を付けると、テキスト選択が優先されます。先に利用者の操作を決めてから属性を付けてください。

2. 必要最小限の文脈を添える

「プロフィールカード」という名前だけでは、どの画面のどの案か分かりません。マークした対象にoai-annotation-metadataを付け、機密性のない情報を追加できます。

<article
  id="profile-card"
  oai-annotatable="プロフィールカード"
  oai-annotation-metadata='{"screen":"チーム画面","variant":"プレビュー"}'
>
  <h2>プロフィール</h2>
  <p>チームのメンバー情報と役割。</p>
</article>

このコードは手順1のプロフィールカードを置き換えるものです。同じidのカードを追加しないでください。Metadataは注釈と一緒に会話へ渡されます。OpenAIが認めるのは小さなフラットJSONオブジェクトで、最大六つのプロパティ、キーは最大64文字、文字列値は最大256文字、シリアライズ後は最大2,048バイトです。入れ子のオブジェクトや配列は使えず、不正なデータは無視される場合があります。

閲覧者とChatGPTの両方に見せてよい情報だけを入れます。Metadataは意見の対象を明確にしますが、ChatGPTにデータベースの閲覧権限や変更権限を与えるものではありません。

3. サイト内のボタンから注釈を開く

対象のカードの横に専用ボタンを置けます。対象のDOM要素ができた後に次のコードを実行します。request()を使えないブラウザーではボタンを隠し、使える場合は利用者のクリック処理の中で呼び出します。

const card = document.getElementById("profile-card");
const button = document.getElementById("discuss-profile");
const annotation = document.oai?.annotation;

button.hidden = typeof annotation?.request !== "function";

button.addEventListener("click", () => {
  if (typeof annotation?.request !== "function") return;

  const result = annotation.request(card, {
    initialComment: "このプロフィールカードの分かりやすさについて意見をください。",
  });

  if (!result.accepted) {
    console.info("Annotation request was not accepted.");
  }
});

result.acceptedはブラウザーが要求を受け取り、検証したことだけを示します。エディターが開いたこと、注釈が保存されたこと、メッセージが送られたことの証明ではありません。initialCommentは編集可能で、最大240 UTF-16コード単位です。通信をawaitしてからrequest()を呼ぶと、クリックに伴う直接の利用者操作として扱われなくなる場合があります。エディターが開いているときやChatGPTがブラウザーを操作しているときも、要求が拒否されることがあります。

特定の文章を指定したい場合、request()にはDOMのRangeも渡せます。現在の文書内にある空でない可視テキストが必要で、最大20,000 UTF-16コード単位です。文字範囲には標準のテキストエディターだけが使われ、mode: "advanced"は拒否されます。ボタン名を「送信」にしないでください。実際の送信は利用者が最後に決めます。

4. 意見を述べる前に選択肢を示す

設計上の問いに明確な選択肢があるなら、selectコントロールを登録できます。次の例はプロフィールカードの情報密度を選んでもらいます。手順3のcardとannotationを宣言した後に配置してください。

let registration;

if (typeof annotation?.registerControls === "function") {
  try {
    registration = annotation.registerControls({
      targets: card,
      controlsHeading: "カードのレイアウト",
      controlsMode: "replace",
      controls: [
        {
          type: "select",
          label: "情報の密度",
          callback: "layoutDensity",
          options: [
            { label: "ゆったり", value: "relaxed" },
            { label: "コンパクト", value: "compact" },
          ],
          defaultValue: "relaxed",
        },
      ],
    });
  } catch (error) {
    console.error("Could not register annotation controls.", error);
  }
}

function cleanupAnnotationControls() {
  registration?.dispose();
}

controlsMode: "replace"では、この対象に登録したコントロールだけを表示します。"extend"なら組み込みのコントロールも併せて表示します。この例は選択を集めるだけで、ページの見た目はすぐに変わりません。currentValueを省略しているため、最初の選択肢を変えなくても、その選択が注釈に含まれます。ChatGPTと注釈履歴に選択肢の文言として渡るのは「ゆったり」「コンパクト」などの表示ラベルで、内部のvalue文字列ではありません。コードを見ない人にも分かるラベルにしましょう。

余白や色のライブプレビューにはrangeまたはcolorを使い、oaiannotationcontrolchangeを処理します。preview、preview-original、resetの各アクションで指定された値を適用し、キャンセル時には通常の表示へ戻します。プレビューは設定を自動保存しません。一つの登録に含められるコントロールは最大12個です。不正な登録は同期的に例外を投げる場合があります。部品を取り除く際はdispose()を呼び、イベントリスナーや自分で作ったプレビュー状態も消します。

5. 利用者の操作を通して確認する

対応するChatGPTデスクトップアプリの内蔵ブラウザーでテストページを開きます。ブラウザーのUIからAnnotation modeに入り、両方のカードの強調範囲、名前、metadataを確かめます。専用ボタンを押して初期コメントを編集し、「コンパクト」を選び、注釈を保存して添付プレビューから開き直します。最後にテストメッセージと一緒に送信し、ChatGPTが正しい対象、文脈、表示ラベルを受け取ったことを確認します。

APIのないブラウザーでも同じページを開いてください。専用ボタンは隠れ、カードは普通に使える状態であるべきです。部品を取り除いてクリーンアップ関数も呼びます。CSSプレビューを追加した場合は、変更、元の状態との比較、キャンセルを試して復元を確認します。**サンプルコードはOpenAIの文書と照合し、JavaScriptの構文検査を通していますが、実際のChatGPTデスクトップアカウントでは操作検証していません。**公開前にブラウザーでの実測が必要です。

期待できる結果の例

閲覧者が「プロフィールカード」を選び、「コンパクト」を指定して「メンバーの役割が目立たないので、もっと分かりやすくしてください」と書きます。会話にはカード名、screen: チーム画面、variant: プレビュー、表示ラベル「コンパクト」が入ります。開発者は対象の案を特定できます。これはAPI仕様から想定した結果で、動作中のデモから取得したログではありません。

うまく使うためのコツ

まずは一組のカードと一つのコントロールから始めましょう。oai-annotatableにはCardV2のような内部名ではなく、利用者が理解できる名前を使います。Metadataには画面名や案の区別を載せ、顧客記録を丸ごと入れないでください。注釈は選択内容と意見を会話へ運びます。AIにサイト上の操作をさせたい場合は、Site toolsなど別の機能が必要です。コーディングエージェントを社内ツールへ深く組み込むなら、Codex SDKとApp Serverの選び方を参照してください。

状態変更のたびにDOMノードを作り直すアプリでは、登録ハンドルを保持して対象を更新するか、部品の削除時に破棄します。登録時の対象一覧は、その時点の要素だけを保持し、後から一致した要素は自動追跡しません。将来currentValueを設定する場合、未保存の編集も含むアプリの通常の値を使い、一時的なプレビュー値を使わないでください。これで変更前後の比較が正しくなります。

知っておきたい制限

利用可否はアプリのバージョン、サイトの権限、サイトごとの設定に左右されます。サイト側から始める要求には、利用者の許可が必要な場合があります。APIは内蔵ブラウザーの安全な最上位文書を想定しており、この例をiframeで試すものではありません。権限や画面表示は変わり得るため、正式な導入前にOpenAIの最新文書を確認してください。

選択内容とmetadataは会話に渡されます。データ共有の経路として扱い、組織の規則を守ってください。この例のコントロールは議論のための選択肢を示すだけで、コードの変更、設定の保存、メール送信はしません。アクセス権、価格、法務、製品方針に関わる意見は、担当者が確認してから反映します。

よくある質問

通常のChromeタブでも使えますか？ OpenAIの文書は、対応するChatGPTデスクトップアプリの内蔵ブラウザーにあるdocument.oai.annotationを説明しています。通常のタブにもあると決めつけず、機能を検出してください。

ChatGPT EnterpriseやEduで使えますか？ OpenAIの現在の文書によると、Browser Annotation APIは両ワークスペースではまだ利用できません。提供範囲が変わったら再確認してください。

フィードバックボタンを押すとメッセージが送信されますか？ いいえ。request()は注釈を開く要求です。編集、保存、送信をするかは利用者が決めます。accepted: trueは配信完了の証拠ではありません。

カード全体ではなく一文を選べますか？ はい。Annotation modeでoai-annotation-container-textによるドラッグ選択を使うか、サイトのボタンから有効なDOMのRangeをrequest()に渡します。

カスタムコントロールはサイトの変更を自動保存しますか？ いいえ。選択を集めたりプレビューしたりできますが、実際の変更にはアプリの通常の保存フローと担当者による確認が必要です。

主な出典：Annotations Extensibility、OpenAI Learn公式文書。確認日：2026年10月5日。#ChatGPT #Annotations #Website #AI開発 #VibeCoding