apify-ai-search-visibility-tracker

AI 検索可視性トラッカー

AI における可視性のライフサイクル全体をカバーする 4 つのワークフローです。重要なプロンプトを発見し → 引用の機会を見つけ → サイトを監査し → 時間の経過とともに追跡します。

すべてのワークフローで、AI 検索に apify/google-search-scraper を使用します。ワークフロー C では、apify/website-content-crawler も使用します。

推奨フロー： ワークフロー A を実行してプロンプトを発見 → ワークフロー B で引用の機会を発見 → ワークフロー C でサイトを監査 → ワークフロー D でスケジュールに沿ってすべてを追跡します。

---

ワークフロー A — 競合他社のプロンプト発見

目標： AI 検索の回答で競合他社が表示される検索クエリを特定し、監視する価値のあるプロンプトを把握します。

収集する入力

#	入力	補足
1	競合他社のドメイン	例：brightdata.com、scraperapi.com
2	トピックのシードキーワード	例：「ウェブスクレイピング」、「データ抽出 API」
3	AI ソース	デフォルト：6 種すべて（AI Overviews、AI Mode、ChatGPT、Perplexity、Copilot、Gemini）

ワークフロー

1. 次のテンプレートを使い、シードキーワードから候補クエリを 15～30 件生成します。

   • best [topic]、[topic] tools、how to [topic]、[topic] for [use case]
   • [topic] vs [competitor brand]、[competitor brand] alternative
   • [topic] API、[topic] pricing、[topic] tutorial

2. 候補クエリごとに apify/google-search-scraper を実行します。各結果から次の項目を抽出します。

   • aiOverview.sources[]、aiMode.sources[]、chatGptAnswer.sources[]、perplexityAnswer.sources[]、copilotAnswer.sources[]、geminiAnswer.sources[]
   • また、競合他社のブランド名への言及があるかどうか、answer_text / aiOverview.text も確認します（単語境界で照合：\bBrand\b）。

3. 競合他社のドメインまたはブランドが表示される (クエリ、ソース) の組み合わせごとに、ヒットを記録します。

4. ヒット総数の降順で並べた、プロンプトを主軸とする表を出力します。

| Query | ChatGPT | Perplexity | AI Overviews | AI Mode | Copilot | Gemini | Total |
|-------|---------|------------|--------------|---------|---------|--------|-------|
| "best web scraping API" | ✓ | ✓ | — | ✓ | — | ✓ | 4 |
| "how to scrape Google" | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 6 |

5. 上位 N 件のクエリ（デフォルトは 10 件）を、ワークフロー D の config.json のプロンプトにそのまま貼り付けられるリストとして提示します。

---

ワークフロー B — 引用機会の検索

目標： 対象トピックについて、AI エンジンが最も頻繁に引用するドメインとコンテンツの種類を特定し、コンテンツを公開または提案すべき場所を明らかにします。

収集する入力

#	入力	補足
1	対象トピック／業界	例：「ウェブスクレイピング」、「e コマースの自動化」
2	シードクエリ	トピックの範囲を網羅する 5～20 件のクエリ
3	AI ソース	デフォルト：6 種すべて
4	引用上位ページの詳細クロール	任意：website-content-crawler で引用上位 3 ページをクロールし、構成パターンを調査します

ワークフロー

1. 選択した AI ソースを対象に、シードクエリごとに apify/google-search-scraper を実行します。

2. すべての結果から sources[] 内の URL をすべて収集します。登録可能なドメインに正規化します（blog.example.com → example.com）。

3. 次の項目を集計します。

   • ドメイン別： 引用数、引用している AI ソース、引用のきっかけとなったクエリを一覧表示
   • コンテンツの種類別： URL パスのパターンから推定（ドキュメント → /docs/、/reference/、ブログ → /blog/、ニュース → 既知のニュースドメイン）

4. 引用総数の多い順に順位付けします。次の形式で出力します。

Top-cited domains for "web scraping" (42 queries × 6 sources):
| Domain | Citations | AI Sources | Inferred type |
|--------|-----------|------------|--------------|
| docs.apify.com | 38 | ChatGPT, Perplexity, AI Mode | Documentation |
| scraperapi.com/blog | 21 | AI Overviews, Gemini | Long-form blog |

5. 詳細クロールが有効な場合：ドメインごとに引用上位 3 件の URL を対象に、apify/website-content-crawler を実行します。Markdown の出力から次の項目を抽出します。

   • クエリに直接回答する最初の見出し
   • 最初の 500 語にコードブロックが含まれているか
   • 単語数
   • H2／H3 にクエリの完全一致フレーズが含まれているか

6. パターンを要約します。「このトピックでは、AI エンジンは［長文のドキュメント／短く直接回答する投稿］を優先します。典型的な引用ページ：［単語数の範囲］、［直接回答する H2 の有無］、［ファーストビューにコード例があるかどうか］。」

---

ワークフロー C — GEO ウェブサイト監査

目標： 特定のウェブサイトのコンテンツが AI に引用されやすい構成になっているかを確認し、対象のプロンプトについて、AI エンジンが実際に引用する内容と比較します。

収集する入力

#	入力	補足
1	自社ウェブサイトの URL	例：https://apify.com
2	対象のプロンプト	ワークフロー A の出力を使用するか、5～10 件を直接指定します
3	AI ソース	デフォルト：6 種すべて

ワークフロー

1. 各対象プロンプトに対して apify/google-search-scraper を実行します。各（プロンプト × ソース）について、登録可能ドメインが sources[] に含まれているかを記録します。

2. 自社ドメインが引用されていないプロンプトについて、そのプロンプトで最も多く引用されている競合の URL を特定します。

3. 引用されていない各プロンプトについて、以下に対して apify/website-content-crawler を実行します。

   • 各プロンプトに対応する、自社の最も関連性の高いページ
   • 引用数が最も多い競合ページ

4. 引用されていない各プロンプトについて、ギャップカードを作成します。

Prompt: "how to scrape Google search results"
Your page: apify.com/blog/scraping-google  →  NOT cited on ChatGPT, Perplexity, AI Mode
Top-cited: docs.brightdata.com/scraping/google (cited 5/6 sources)

Structural gaps:
  ✗ Your page: answer buried after 900 words, no direct-answer H2
  ✓ Competitor: H2 "How to scrape Google in 3 steps" at word 120 + code block at word 180

Recommended actions (priority order):
  1. Add H2 that mirrors the query phrase within first 300 words
  2. Move code example above the fold
  3. Add a "Quick answer" summary box at the top

5. 提出するもの：プロンプトごとのギャップカードと、期待される影響度順に並べた統合アクションテーブル。

---

ワークフロー D — 定期的な可視性トラッカー

目標： 6 つすべての AI サーフェスにおけるブランドの引用とメンションを定期的にスナップショットし、経時的な変化を追跡します。

前提条件

（事前に確認する必要はありません）

• APIFY_TOKEN が config.json と同じ場所にある .env ファイルに保存されていること（実行スクリプトが自動的に読み込みます）。
• PATH 上に Python 3.9 以降があること。pip3 install requests（サードパーティ製依存関係はこれのみ）。複数部分からなる TLD で登録可能ドメインを正確に照合するには、pip3 install tldextract を推奨します。
• 自動で毎日実行する場合：launchd または cron が利用可能な macOS / Linux（インストーラーが両方に対応します）。Windows ユーザーには schtasks の手順が表示されます。

手順

このチェックリストをコピーして、進捗を記録します。

Task Progress:
- [ ] Step 1: Load or collect the seven required inputs
- [ ] Step 2: Confirm AI sources and cadence
- [ ] Step 3: Write config.json + .env, then install the OS schedule
- [ ] Step 4: Run a snapshot now so the user sees the first report
- [ ] Step 5: Deliver the history report (diff vs. all prior runs)

ステップ 1：必要な 7 つの入力を読み込むか、収集する

ユーザーの作業ディレクトリに config.json がある場合は読み込み、ユーザーが再設定を求めない限り、ステップ 4 に進みます。初回実行時は、Actor を呼び出す前に 7 つの入力をすべて確認します。

#	入力	重要な理由
1	ブランド URL	プライマリドメインです。登録可能ドメインによる引用の照合に使います（blog.apify.com → apify.com）。
2	ブランド名	テキストメンション照合に使う表記です（例：Apify、apify.com、@apify）。URL のみの照合では、リンクのないメンションを見逃します。
3	競合ブランド	明示的に確認します。「自社ブランドとあわせて追跡したい競合はありますか？」 名前 + ドメイン の組み合わせを受け付けます。競合がゼロでも構いませんが、初回実行時には必ず質問します。
4	監視するプロンプト	1 つ以上の検索クエリです。有効になっているすべての AI ソースで、それぞれのクエリを実行します。まだ使用するプロンプトがわからない場合は、まずワークフロー A を実行してください。競合他社が表示されるプロンプトを見つけ、ここに貼り付けられます。
5	実行頻度	daily / weekly / monthly。install_cron.sh が書き込むスケジュール設定に反映されます。
6	使用する AI ソース	6 つ（AI Overviews、AI Mode、ChatGPT、Perplexity、Copilot、Gemini）を提示します。デフォルトではすべて有効です。それぞれのソースで結果ごとのコストが発生します。現在の料金は Actor ページ（https://apify.com/apify/google-search-scraper）を参照してください。
7	Apify Dataset 名	追記先の名前付きデータセットです。指定がない場合は初回実行時に作成され、名前は config.json に記録されます。

この 7 項目を確認した後、任意の追加項目として countryCode、languageCode、location（UULE）、希望する実行時刻（デフォルトは現地時間の 09:00）を確認します。

次に、回答の詳細度について質問し、config.json:include_full_answers に保存します。

• on_demand（デフォルト）：レポートには、各サーフェス形式の一致箇所の前後にある短い引用文を表示します。LLM の回答全文は名前付き KV ストアに保存されるため、ユーザーは後で確認できます。
• always：エンティティが言及されている場合は、LLM の回答全文をそのままレポートに埋め込みます。プロンプトが 1 つの場合に便利ですが、5 つ以上のプロンプトでは扱いにくくなります。

ステップ 2：AI ソースと実行頻度を確認する

ユーザーが選択した 7 項目を 1 つの段落にまとめ、確認のために提示します。ユーザーがソースを切り替えた場合は、書き込み前にメモリ上の設定を更新します。

ステップ 3：config.json と .env を作成し、OS のスケジュールを設定する

レポートの保存先としてユーザーが指定した場所の隣に、次のディレクトリ構成を作成します。

working-dir/
  config.json     # copied from the skill's config.example.json, edited with collected values
  .env            # APIFY_TOKEN=apify_api_xxx   (chmod 600)

cp ${CLAUDE_PLUGIN_ROOT}/reference/scripts/config.example.json ./config.json
# then edit with the collected values, save

echo 'APIFY_TOKEN=your_token_here' > ./.env
chmod 600 ./.env

次に、OS のスケジュールを設定します。

bash ${CLAUDE_PLUGIN_ROOT}/reference/scripts/install_cron.sh --cadence daily --hour 9

Cron 式の対応表：

頻度	Cron 式	実行時刻
daily	0 H * * *	現地時間の毎日 H:00
weekly	0 H * * 1	毎週月曜日の H:00
monthly	0 H 1 * *	毎月 1 日の H:00

ステップ 4：今すぐスナップショットを実行する

macOS：

launchctl kickstart "gui/$(id -u)/com.apify.ai-visibility-tracker"
tail -f ~/Library/Logs/ai-visibility-tracker.log

Linux／汎用：

python3 ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_snapshot.py --config ./config.json

どちらの方法でも、次の処理を行います。

1. 設定済みのプロンプトと AI ソースの有効化設定を使って、apify/google-search-scraper を呼び出します。
2. 各（プロンプト x ソース）のセルを解析し、引用とブランド／競合への言及を抽出します。
3. 名前を指定した Apify Dataset に行を追加します（スキーマは reference/output-schema.md を参照）。
4. 生のアイテムを名前を指定した KV ストアに書き込みます（長期アーカイブ）。
5. これまでのすべての実行結果と比較して履歴を計算します。
6. config.json の隣に reports/snapshot-<ISO-date>.md を書き込みます。

ステップ 5：履歴レポートを提示する

reports/snapshot-<ISO-date>.md を開き、主な調査結果をチャットで提示します。次の内容から始めます。

• 今日初めての引用／言及 -- エンティティ x ソースの組み合わせが初めてしきい値を超えたもの。
• 減少 -- 直近の前回実行ではエンティティが引用されていたものの、今日は引用されていないもの。
• 引用されたすべてのエンティティについて、一致した正確な URL。

出力形式

スナップショットの要約はエンティティを主軸とします。追跡対象のエンティティ（ブランド、その後に競合）ごとに Markdown テーブルを 1 つ作成し、AI ソースごとに 1 行を設けます。列は Source | Cited | Mentioned | SoV% | Matched URLs | History です。

---

実行主体

実行主体	使用箇所	主な入力フィールド
apify/google-search-scraper	A、B、C、D	queries[]、aiOverview、chatGptSearch、perplexitySearch、googleAiMode、bingCopilotSearch、googleGeminiSearch
apify/website-content-crawler	B（任意）、C	startUrls[]、maxCrawlPages、outputMarkdown: true

料金は変更されるため、数値を提示する前に料金タブを確認してください。コストを抑えるには、使用しない AI ソースを無効にします。

テレメトリー。 ワークフロー D は reference/scripts/run_snapshot.py を通じて実行されます。このスクリプトは、すべての Apify API 呼び出しに User-Agent: apify-awesome-skills/ai-search-visibility-tracker-... をすでに設定しています。ワークフロー A～C でこれらの実行主体を個別に呼び出す場合は、使用状況が正しく集計されるよう、対応するフラグを渡します。--user-agent apify-awesome-skills/apify-ai-search-visibility-tracker と --json を指定し（apify datasets get-items には --format json を使用）、2>/dev/null を追加します。例：

apify actors call apify/google-search-scraper \
  --user-agent apify-awesome-skills/apify-ai-search-visibility-tracker \
  --json 2>/dev/null

品質ルール

• 非対話型。 run_snapshot.py では stdin を読み取りません。launchd／cron には stdin がありません。
• 単語境界によるブランド照合（\bbrand\b、大文字と小文字を区別しません）。reference/citation-matching.md を参照してください。
• 登録可能ドメインによる引用照合（blog.apify.com は apify.com として扱います）。reference/citation-matching.md を参照してください。
• 行を省略しない。 AI ソースから何も返されない場合も、cited: false, mentioned: false, answer_text: "[no answer returned]" の行を書き込みます。
• **すべての行に Apify の実行 ID を含めます。**これにより、あらゆる調査結果を再検証できます。

エラー処理

APIFY_TOKEN not found — .env を config.json と同じディレクトリに配置するようユーザーに案内します（echo 'APIFY_TOKEN=...' > .env && chmod 600 .env）。トークンは https://console.apify.com/account/integrations で取得できます。 config.json not found — まずステップ 3 を実行して、テンプレートから作成するよう案内します。 Dataset name not set — ユーザーに名前を尋ねます。ランナーが初回の追加時にデータセットを作成します。 Actor run FAILED — ランナーの出力に含まれるコンソールへのリンクを表示し、確認するようユーザーに案内します。 AI source returned no answer — [no answer returned] と記録して行が書き込まれます。エラーではありません。 website-content-crawler returns no markdown — ページで JavaScript が多用されている可能性があります。useBrowserCrawler: true を試してください。 Schedule not firing — reference/scheduling.md のトラブルシューティングのセクションを参照してください。 No previous run to diff against — 初回実行時のみ発生します。レポートには履歴セクションなしでスナップショットが表示されます。