apify-ads-intelligence

広告インテリジェンスクラスター

自然言語で広告、広告ライブラリ、競合他社の広告活動について質問すると、適切な Apify Actor にルーティングし、情報を統合した回答を提供します。

CLI のルール： 常に --user-agent apify-awesome-skills/apify-ads-intelligence、--json（または datasets get-items では該当する --format フラグ）、および 2>/dev/null を指定してください。--user-agent フラグはテレメトリーに不可欠です。省略しないでください。

プラットフォームの対象範囲に関する注意

• Meta、Google、TikTok、LinkedIn：公開広告ライブラリがあり、豊富なデータ（クリエイティブ、ターゲティング、日付、公開されている場合はリーチ）を提供しています。
• X（Twitter）：公開広告ライブラリはありません。対象範囲は、ブランドのツイートをスクレイピングし、card フィールドが空でない項目、または source に「Ads」が含まれる項目を、プロモーションの可能性があるものとしてフラグ付けするベストエフォートの代替手段です。統合した回答には、必ずこの注意事項を含めてください。

apify-ecommerce との重複に関する注意

このスキルには、簡易的な Meta 広告検索のために apify/facebook-ads-scraper にルーティングする ads-intelligence インテントがあります。このスキルでは、5 つのプラットフォームすべてを詳しく調査します。e コマースに関する質問の補足情報として Meta 広告だけが必要な場合は、apify-ecommerce を使用してください。広告が主なタスクである場合は、このスキルを使用してください。

前提条件

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

• Apify CLI v1.5.0 以降（npm install -g apify-cli）
• jq（レスポンスの解析とフィルタリングに推奨。macOS では brew install jq、Linux では apt install jq）
• 次のいずれかによる認証：
  • apify login（OAuth。ブラウザーが開きます）
  • APIFY_TOKEN 環境変数（例：export APIFY_TOKEN=... または .env ファイル）
  • Apify Console → Settings → Integrations のトークン

認証を確認するには、apify info --user-agent apify-awesome-skills/apify-ads-intelligence を実行します。ユーザー名と userId が表示されるはずです。

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Task Progress:
- [ ] Step 1: Detect intent and select Actor(s)
- [ ] Step 2: Fetch Actor schema
- [ ] Step 3: Ask user preferences (output format, result count, country)
- [ ] Step 4: Run the Actor (or Actors in parallel for cross-platform-audit) and fetch results
- [ ] Step 5: Synthesize a direct answer (not a data dump)

ステップ 1：意図を検出してアクターを選択する

ユーザーのメッセージを意図に分類し、適切なアクターを選択します。

意図を示すシグナル：

ユーザーメッセージ内のシグナル	意図
"what ads is X running", "competitor [brand] ads", "[brand] FB/Google/TikTok/LinkedIn/X/Twitter ads", "show ads from [page]", "promoted tweets from [brand]"	competitor-ads
"ads about [topic]", "find [keyword] ads", "ads for [vertical]", "fitness/fintech/saas ads"	keyword-ads
"trending ads", "winning ads", "top ads", "best performing", "long-running ads", "creative inspiration"	top-creatives
"where do these ads go", "landing pages from ads", "click destinations", "ad funnels"	landing-page-audit
"compare X's ads across platforms", "all ads from [brand]", "cross-platform ad audit"	cross-platform-audit

複数の意図が検出された場合は、" [意図 A] と [意図 B] のどちらをご希望ですか？" と尋ねます。

アクターのルーティング — 必ず最初にプライマリを試し、失敗した場合、または結果が 0 件の場合に限りフォールバックに切り替えます：

意図	プラットフォーム	プライマリアクター	フォールバックアクター
competitor-ads	Meta (FB/IG)	apify/facebook-ads-scraper	brilliant_gum/facebook-ads-library-scraper
competitor-ads	Google	dz_omar/google-ads-scraper	solidcode/ads-transparency-scraper
competitor-ads	TikTok	brilliant_gum/tiktok-ads-library-scraper (source: library)	silva95gustavo/tiktok-ads-scraper
competitor-ads	LinkedIn	silva95gustavo/linkedin-ad-library-scraper	dz_omar/linkedin-ads-scraper
competitor-ads	X (回避策)	apidojo/twitter-scraper-lite (twitterHandles: [<brand>]) + ヒューリスティックフィルター	apidojo/tweet-scraper
keyword-ads	Meta	brilliant_gum/facebook-ads-library-scraper	apify/facebook-ads-scraper
keyword-ads	Google	apify/google-search-scraper (focusOnPaidAds: true)	—
keyword-ads	TikTok	brilliant_gum/tiktok-ads-library-scraper	—
keyword-ads	LinkedIn	silva95gustavo/linkedin-ad-library-scraper	—
keyword-ads	X (回避策)	apidojo/twitter-scraper-lite (searchTerms: [<keyword>]) + ヒューリスティックフィルター	apidojo/tweet-scraper
top-creatives	Meta	brilliant_gum/facebook-ads-library-scraper (daysRunning で順位付け)	—
top-creatives	TikTok	burbn/tiktok-top-ads-spy (CTR / インプレッション / いいねで並べ替え)	brilliant_gum/tiktok-ads-library-scraper (source: creative_center)
top-creatives	Google	該当なし — competitor-ads ルートにフォールバックし、アクティブな広告に絞り込みます	—
top-creatives	LinkedIn	該当なし — competitor-ads ルートにフォールバックし、impressionsPerCountry のリーチで順位付けします	—
top-creatives	X	v1 では該当なし — タイムライン全体でプロモーションコンテンツの信頼できるシグナルがありません	—
landing-page-audit	Meta	brilliant_gum/facebook-ads-library-scraper (resolveSnapshotUrls: true)	—
landing-page-audit	Google	apify/google-search-scraper (focusOnPaidAds: true, directUrl)	dz_omar/google-ads-scraper (destinationUrl)
landing-page-audit	X	v1 では該当なし — ランディングページの抽出にはヒューリスティックの信頼性が不十分です	—
cross-platform-audit	5 つすべて	Meta、Google、TikTok、LinkedIn のプライマリを並行して実行し、X の回避策は注意書きを添えて別途実行します。広告主ごとに統合します。	—

X（Twitter）のヒューリスティックフィルター — スクレイピング後、次のいずれかに該当する場合、そのツイートにプロモーションの可能性が高いというフラグを付けます：

• card フィールドが空ではない（ウェブサイトカード／CTA は、プロモーションツイートに添付されることがよくあります）
• source フィールドに "Ads" が含まれている（例："Twitter Ads"）

次の注意書きを明記して結果を提示します："X には公開広告ライブラリがありません。以下の結果は、プロモーションコンテンツのヒューリスティックに合致した、ブランド自身のタイムライン上のツイートです。他のユーザーのフィードに表示される、プロモーション専用の広告は含まれません。"

ステップ 2：Actor のスキーマを取得する

Actor の概要、入力スキーマ、README を取得します。

# Summary (title, description, pricing, stats)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null

# Input schema (required and optional parameters; schema lives in
# .taggedBuilds.latest.build.inputSchema as an escaped JSON string)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --input --json 2>/dev/null

# README (capabilities, examples, gotchas)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --readme 2>/dev/null

ACTOR_ID を選択した Actor（例：apify/facebook-ads-scraper）に置き換えます。

ステップ 3：ユーザーの希望を確認する

実行前に、次の項目を確認します。

1. 出力形式：

   • クイック回答（デフォルト）— チャットで回答をまとめます。ファイルは保存しません
   • CSV — 全データをディスクに保存します
   • JSON — 全データをディスクに保存します

2. 結果件数 — 意図ごとのデフォルトは次のとおりです。

   意図	デフォルトの件数
   competitor-ads	30
   keyword-ads	30
   top-creatives	20
   landing-page-audit	50
   cross-platform-audit	プラットフォームごとに15件

3. 国 — デフォルトは US です。TikTok ライブラリの場合は、デフォルトを DE（EU のみ）にしてユーザーに警告します。グローバルな TikTok を使用する場合は、source: creative_center を指定します。X のルートはハンドル／キーワードを基準とするグローバルなもので、国のパラメーターはありません。

コストの安全対策：Actor の入力では、常に適切な結果件数の上限（maxResults、resultsLimit、または Actor のスキーマに応じた同等のフィールドなど）を設定します。広告が500件以上になる実行の前にはユーザーに警告します。apify/facebook-ads-scraper は広告ごとに課金され、X のプライマリはツイートごとに課金されます。

ステップ 4：Actor を実行して結果を取得する

2つの手順で行います。Actor を実行し（完了まで待機）、次に指定された形式でデータセットの項目を取得します。

Actor を実行する — 実行メタデータを JSON で返します。次の手順に使う defaultDatasetId を抽出します。

apify actors call "ACTOR_ID" -i 'JSON_INPUT' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null

出力から .id（実行 ID）、.status（SUCCEEDED である必要があります）、.defaultDatasetId を使用します。

結果を取得する — ユーザーの希望に応じて、適切な形式を選択します。

# Quick answer: total count + fields + top 5 in chat (no file)
apify datasets info DATASET_ID --json \
  --user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null \
  | jq '{itemCount, fields, consoleUrl}'
apify datasets get-items DATASET_ID --limit 5 \
  --user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null

# CSV file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ads-intelligence --format csv 2>/dev/null > YYYY-MM-DD_filename.csv

# JSON file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null > YYYY-MM-DD_filename.json

その他の --format オプション：jsonl、xlsx、xml、rss、html。大きなデータセットをページ分割するには、--offset N を使用します。

ヒント： 簡単に確認するだけの場合を除き、まずデータセットをローカルファイルに保存して（> file.json／> file.csv）、その後の分析はディスク上のファイルから行います。apify datasets get-items は常にネットワーク経由でストリーミングするため、パイプで直接 jq に渡すと、実行のたびに全データを再ダウンロードします。

クロスプラットフォーム監査（並列実行）： cross-platform-audit の場合は、各 apify actors call ... の呼び出しを & でバックグラウンド実行し、結果を取得する前に wait を呼び出して、Meta、Google、TikTok、LinkedIn のプライマリを並列で実行します。例：

apify actors call "apify/facebook-ads-scraper" -i '<META_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > meta_run.json &
apify actors call "dz_omar/google-ads-scraper" -i '<GOOGLE_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > google_run.json &
apify actors call "brilliant_gum/tiktok-ads-library-scraper" -i '<TIKTOK_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > tiktok_run.json &
apify actors call "silva95gustavo/linkedin-ad-library-scraper" -i '<LINKEDIN_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > linkedin_run.json &
wait
# Then extract each .defaultDatasetId and fetch items per platform; X workaround runs separately with caveat.

jq と組み合わせた簡単な抽出：

jq は apify datasets get-items の代わりではなく、補完として扱います。サーバー側の --limit／--offset／--format を使うと、コストと帯域幅を抑えられます。jq はサンプル項目か、すでに保存したファイルに対して使用します。

# Discover real field names from one sample item (Actor outputs vary —
# use this before composing further jq queries)
apify datasets get-items DATASET_ID --limit 1 --format json \
  --user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null \
  | jq '.[0]'

# X heuristic filter on a saved tweets file: keep items with non-empty card
# or source containing "Ads"
jq '[.[] | select((.card != null and .card != "") or (.source != null and (.source | contains("Ads"))))]' \
  YYYY-MM-DD_x_tweets.json

ステップ 5：結果を分析して回答を提示する

結果をそのまま並べるのではなく、要点をまとめます。インテントごとのパターン：

インテント	まとめで示す内容
competitor-ads	見つかった広告の総数、アクティブと非アクティブの内訳、主なクリエイティブ形式、広告コピーの抜粋上位 5 件、ランディングページの一意なドメインの一覧。X の場合は、スクレイピングしたツイートの総数、プロモーションの可能性が高いとしてフラグ付けされた件数、フラグ付きツイート上位 5 件と、ヒューリスティック検出に関する注意書き。
keyword-ads	このキーワードで広告を出している広告主上位 5 社、広告の総数、国別の内訳
top-creatives	daysRunning（Meta）または CTR（TikTok）による上位 5 件。クリエイティブの概要と Ad Library エントリーへのリンクも含めます
landing-page-audit	ドメイン別にグループ化した、一意なランディング URL の一覧と、それぞれに誘導する広告の数
cross-platform-audit	プラットフォームごとの広告数とトーンの概要、続いて「最も多く出稿している場所」についての推測

推奨される次の手順 — 直前に実行したインテントに応じて提示します：

ユーザーが直前に実行したもの…	次の提案
competitor-ads（Meta）	apify-competitor-intelligence と組み合わせて、相手の FB ページの投稿、IG プロフィール、Google Maps のレビューを追加します
landing-page-audit（任意）	apify-ecommerce（tech-stack インテント）と組み合わせてランディングページの背後にあるプラットフォームを特定するか、apify-lead-generation と組み合わせてリンク先ドメインに連絡先情報を追加します
top-creatives（TikTok／Meta）	クリエイティブにインフルエンサーとのコラボが含まれている場合は、apify-influencer-discovery と組み合わせます
keyword-ads（Google／Meta）	apify-trend-analysis と組み合わせて、Google Trends／Instagram／TikTok でキーワードが上昇傾向か下降傾向かを確認します
cross-platform-audit	apify-content-analytics と組み合わせて、ブランドのオーガニックコンテンツ側も分析します。有料とオーガニックを合わせた全体像を把握できます

注意事項

• TikTok のキーワード検索は範囲が広めです。 「Nike」を検索すると、無関係な広告主（テストでは Interactive Brokers、Shopify）の広告が返されることがあります。必ず advertiserName がユーザーの意図するブランドと一致するか事後にフィルタリングし、フィルタリング後に一致する結果が 0 件の場合はユーザーに伝えてください。
• TikTok Ads Library の対象は EU／EEA／UK のみです。 library ソースには EU の国コード（DE／FR／IT／ES／NL／PL／SE など）が必要です。米国またはグローバルを対象にする場合は、creative_center ソースに切り替えてください。フィールドが異なり、CTR とインプレッション範囲はありますが、ターゲティングデータはありません。
• dz_omar/google-ads-scraper では resultsPerQuery >= 10 が必要です。 これより小さい値では検証に失敗します。少量の結果でよいインテントでも、必ず 10 以上に設定してください。
• apify/facebook-ads-scraper が受け取るのはキーワードではなく URL です。 competitor-ads の場合は、ブランド名から https://www.facebook.com/<PageName> を組み立ててください。keyword-ads の場合は、q=<keyword>&country=<XX> を含む Meta Ad Library の URL を組み立ててください。
• apify/google-search-scraper の有料広告モードでは、有料検索結果が見つからない場合に最大 3 回の再試行が組み込まれています。検索語に有料検索結果が本当に存在しない場合もあります。paidResults が空でもエラーではなく、有効な結果として扱ってください。
• LinkedIn Ad Library の URL の組み立て： 会社 URL https://www.linkedin.com/company/<slug>/ は使用できますが、処理が遅く、フィルターも無視されます。competitor-ads では https://www.linkedin.com/ad-library/search?accountOwner=<slug>&countries=<XX> を使用してください。keyword-ads では ?keyword=<term>&countries=<XX> を使用してください。
• X には公開の広告ライブラリがありません。 対象範囲はヒューリスティックによるものに限られます。このルートでは apidojo/twitter-scraper-lite を使ってブランドの投稿（またはキーワード検索結果）をスクレイピングし、card フィールドが空でない項目、または source に "Ads" が含まれる項目を、プロモーションの 可能性が高い としてフラグ付けします。ブランド自身のタイムラインに表示されない、プロモーション専用の投稿は見逃します。
• X のセッション依存性。 プライマリの X Actor が noResults のセンチネルだけを返した場合は、結果が 0 件と判断する前にフォールバックへ切り替えてください。
• 料金。 価格設定ではほとんどのプライマリは無料です。apify/facebook-ads-scraper は広告 1 件あたり課金（$0.001～$0.0058）され、X のプライマリはツイートあたり課金（1,000 件あたり約 $0.0004）されます。デフォルト件数（30／20／50）なら費用はごくわずかです。広告 500 件以上の実行前には警告してください。

エラー処理

• 認証エラー → apify login を実行するか、APIFY_TOKEN 環境変数を設定します
• Actor not found → Actor ID がルーティングテーブルと一致するか確認します
• 実行ステータスが FAILED → コンソール URL（実行メタデータの .consoleUrl）を開いてログを確認します
• タイムアウト／実行に非常に時間がかかる → apify actors call に --timeout <seconds> を渡すか、結果数を減らします
• 結果が 0 件 → フォールバック Actor に切り替えます。それでも 0 件の場合は、別の国コードを試します
• TikTok ライブラリ：EU の国が指定されていない → デフォルトで DE を使用し、ユーザーに警告します
• dz_omar/google-ads-scraper：resultsPerQuery の検証エラー → 10 以上に増やします
• X スクレーパー：noResults のセンチネルしか返されない → フォールバックの X Actor に切り替えます
• proxy is required エラー → 入力に "proxy": {"useApifyProxy": true} を追加します