apify-ads-intelligence

# Ads Intelligence Cluster Answer natural language questions about ads, ad libraries, and competitor advertising activity by routing to the right Apify Actor and delivering a synthesized answer. **CLI rules:** Always pass `--user-agent apify-awesome-skills/apify-ads-intelligence`, `--json` (or the relevant `--format` flag on `datasets get-items`), and `2>/dev/null`. The `--user-agent` flag is critical for telemetry — never omit it. ## Note on platform coverage - **Meta, Google, TikTok, LinkedIn**: real public ad libraries with rich data (creatives, targeting, dates, reach where disclosed). - **X (Twitter)**: no public ad library exists. Coverage is a **best-effort workaround** that scrapes a brand's tweets and flags items with non-empty `card` field or `source` containing "Ads" as likely promoted. Always include the caveat in synthesis output. ## Note on overlap with `apify-ecommerce` That skill has an `ads-intelligence` intent that routes to `apify/facebook-ads-scraper` for shallow Meta-ad lookups. This skill is the deep dive across all five platforms. If you only need Meta ads as a side detail of an ecommerce question, stay in `apify-ecommerce`. If ads are the main task, use this skill. ## Prerequisites (No need to check it upfront) - Apify CLI v1.5.0+ (`npm install -g apify-cli`) - `jq` (recommended for response parsing and filtering; `brew install jq` on macOS, `apt install jq` on Linux) - Authentication via one of: - `apify login` (OAuth, opens browser) - `APIFY_TOKEN` env variable (e.g. `export APIFY_TOKEN=...` or `.env` file) - Token from [Apify Console → Settings → Integrations](https://console.apify.com/settings/integrations) Verify auth: `apify info --user-agent apify-awesome-skills/apify-ads-intelligence` — should show username and userId. ## Workflow Copy this checklist and track progress: ``` 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) ``` ### Step 1: Detect Intent and Select Actor Classify the user's message into an intent, then pick the right Actor. **Intent signals:** | Signals in user message | Intent | |-------------------------|--------| | "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` | If multiple intents detected, ask: *"Do you want [intent A] or [intent B]?"* **Actor routing — always try Primary first, switch to Fallback only if it fails or returns 0 results:** | Intent | Platform | Primary Actor | Fallback Actor | |--------|----------|---------------|----------------| | `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 (workaround) | `apidojo/twitter-scraper-lite` (`twitterHandles: [<brand>]`) + heuristic filter | `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 (workaround) | `apidojo/twitter-scraper-lite` (`searchTerms: [<keyword>]`) + heuristic filter | `apidojo/tweet-scraper` | | `top-creatives` | Meta | `brilliant_gum/facebook-ads-library-scraper` (rank by `daysRunning`) | — | | `top-creatives` | TikTok | `burbn/tiktok-top-ads-spy` (sort by CTR / impressions / likes) | `brilliant_gum/tiktok-ads-library-scraper` (`source: creative_center`) | | `top-creatives` | Google | n/a — fall back to `competitor-ads` route, filter to active ads | — | | `top-creatives` | LinkedIn | n/a — fall back to `competitor-ads` route, rank by `impressionsPerCountry` reach | — | | `top-creatives` | X | n/a in v1 — no reliable promoted-content signal across timelines | — | | `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 | n/a in v1 — heuristics not reliable enough for landing-page extraction | — | | `cross-platform-audit` | All five | Run Meta + Google + TikTok + LinkedIn primaries in parallel; X workaround runs separately with caveat. Merge by advertiser. | — | **X (Twitter) heuristic filter** — after scraping, flag a tweet as *likely promoted* if any of the following hold: - `card` field is non-empty (website cards / CTAs are commonly attached to promoted tweets) - `source` field contains "Ads" (e.g. "Twitter Ads") Surface results with the explicit caveat: *"X has no public ad library; results below are tweets from the brand's own timeline that match promoted-content heuristics. They will miss promoted-only ads that appear in other users' feeds."* ### Step 2: Fetch Actor Schema Fetch the Actor summary, input schema, and README: ```bash # 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 ``` Replace `ACTOR_ID` with the selected Actor (e.g., `apify/facebook-ads-scraper`). ### Step 3: Ask User Preferences Before running, ask: 1. **Output format**: - **Quick answer** (default) — synthesized answer in chat, no file saved - **CSV** — full export saved to disk - **JSON** — full export saved to disk 2. **Result count** — defaults by intent: | Intent | Default count | |--------|---------------| | `competitor-ads` | 30 | | `keyword-ads` | 30 | | `top-creatives` | 20 | | `landing-page-audit` | 50 | | `cross-platform-audit` | 15 per platform | 3. **Country** — default `US`. For TikTok library specifically, default `DE` (EU-only) and warn the user; for global TikTok use `source: creative_center`. X routes are global by handle/keyword, no country parameter. **Cost safety**: Always set a sensible result limit in the Actor input (e.g., `maxResults`, `resultsLimit`, or the equivalent field per Actor schema). Warn the user before runs of 500+ ads — `apify/facebook-ads-scraper` charges per ad and X primaries charge per tweet. ### Step 4: Run the Actor and Fetch Results Two steps: run the Actor (blocks until done), then fetch dataset items in the requested format. **Run the Actor** — returns run metadata as JSON; extract `defaultDatasetId` for the next step: ```bash apify actors call "ACTOR_ID" -i 'JSON_INPUT' \ --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null ``` From the output use `.id` (run ID), `.status` (should be `SUCCEEDED`), and `.defaultDatasetId`. **Fetch results** — pick the variant based on the user's preference: ```bash # 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 ``` Other `--format` options: `jsonl`, `xlsx`, `xml`, `rss`, `html`. Use `--offset N` to paginate large datasets. **Tip:** for anything more than a quick peek, save the dataset to a local file first (with `> file.json` / `> file.csv`) and run further analysis from disk. `apify datasets get-items` always streams over the network, so piping it straight into `jq` re-downloads the whole thing every iteration. **Cross-platform audit (parallel runs):** For `cross-platform-audit`, kick off Meta + Google + TikTok + LinkedIn primaries in parallel by backgrounding each `apify actors call ...` invocation with `&` and calling `wait` before fetching results. Example: ```bash 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. ``` **Combining with `jq` for quick extraction:** Treat `jq` as a complement to `apify datasets get-items`, not a replacement: server-side `--limit` / `--offset` / `--format` keeps cost and bandwidth down. Use `jq` on a sample item or on a file you already saved. ```bash # 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 ``` ### Step 5: Analyze Results and Deliver Answer Synthesize, don't dump. Patterns by intent: | Intent | What the synthesis surfaces | |--------|------------------------------| | `competitor-ads` | Total ads found, active vs inactive split, top creative formats, top 5 ad copy snippets, list of unique landing-page domains. For X specifically: total tweets scraped, count flagged as likely-promoted, top 5 flagged tweets with the heuristic-detection caveat. | | `keyword-ads` | Top 5 advertisers running ads on this keyword, total ads, country split | | `top-creatives` | Top 5 by `daysRunning` (Meta) or CTR (TikTok), with creative summary, link to Ad Library entry | | `landing-page-audit` | List of unique landing URLs, grouped by domain, with ad counts pointing at each | | `cross-platform-audit` | Per-platform ad count and tone summary, then a "where they're spending most" inference | **Suggested follow-ups** — keyed off the intent that just ran: | If user just ran… | Suggest next | |-------------------|--------------|