@ads-repo/meta-creative-buckets 1.0.0

package/scripts/optional/extract-promo-labels.cjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * Extract the promo label of every ad from the Ad Library report and write it as a
+ * plain ad_id -> label map that the buckets dashboard can join against.
+ *
+ *   research/meta-ads-library/<client>/_data/promo-labels.json   (your classifier's output)
+ *        ->  data/meta-ads/<client>/promo-labels.json
+ *
+ * The labels themselves are produced by your own creative classifier:
+ *
+ *   "Promo - main message"       the offer IS the argument of the ad
+ *   "Promo - secondary message"  carries an offer beside a different main argument
+ *   "Non-promo"                  no offer
+ *
+ * Only STATIC ads carry a label — the underlying promo classification was run over the
+ * static creatives only, so videos deliberately have none and are reported as unlabelled
+ * rather than guessed at.
+ *
+ * The map comes straight from the generator, not from parsing the rendered page. A card only
+ * shows its concept's representative creative, so scraping ad ids out of the html misses every
+ * other ad running the same picture — that is how a 208-ad dashboard once labelled only 88.
+ *
+ * Coverage is partial by nature: the Ad Library scrape is a snapshot of what was public at
+ * scrape time, while the buckets data is every ad that spent in the window. Ads missing from
+ * the map (videos, and ads created after the scrape date) are DROPPED by the dashboard rather
+ * than defaulted to Non-promo — unknown is not the same as "no offer".
+ *
+ * Usage: node extract-promo-labels.cjs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const cfg = require('../config.cjs');
+
+const SRC = path.join(process.cwd(), 'research', 'meta-ads-library', cfg.client,
+                      '_data', 'promo-labels.json');
+const OUT_DIR = cfg.dataDir;
+const OUT = path.join(OUT_DIR, 'promo-labels.json');
+const BUCKETS = cfg.latestFile;
+
+const VALID = new Set(['Promo - main message', 'Promo - secondary message', 'Non-promo']);
+
+if (!fs.existsSync(SRC)) {
+  console.error(`Error: ${SRC} not found — run your classifier first.`);
+  process.exit(1);
+}
+
+const map = JSON.parse(fs.readFileSync(SRC, 'utf-8'));
+
+const counts = {};
+for (const l of Object.values(map)) counts[l] = (counts[l] || 0) + 1;
+
+console.log(`\nPromo labels — ${cfg.client}`);
+console.log(`  source: ${path.relative(process.cwd(), SRC)}`);
+console.log(`  ads labelled          : ${Object.keys(map).length}`);
+for (const [l, n] of Object.entries(counts).sort((a, b) => b[1] - a[1])) {
+  console.log(`    ${l.padEnd(26)}: ${n}`);
+}
+
+// Report the join rate against the actual buckets data, so partial coverage is visible
+// here rather than being discovered as a puzzling gap in the dashboard.
+if (fs.existsSync(BUCKETS)) {
+  const b = JSON.parse(fs.readFileSync(BUCKETS, 'utf-8'));
+  const ads = b.ads.filter(a => a.spend > 0);
+  const hit = ads.filter(a => map[a.ad_id]);
+  const spendHit = hit.reduce((s, a) => s + a.spend, 0);
+  const spendAll = ads.reduce((s, a) => s + a.spend, 0);
+  console.log(`\n  join against buckets-latest.json:`);
+  console.log(`    ${hit.length}/${ads.length} ads matched` +
+              ` · ${(spendHit / spendAll * 100).toFixed(0)}% of spend`);
+  console.log(`    ${ads.length - hit.length} ads have no label → dropped from the dashboard`);
+}
+
+fs.mkdirSync(OUT_DIR, { recursive: true });
+fs.writeFileSync(OUT, JSON.stringify(map, null, 2));
+console.log(`\n✓ Saved ${OUT}`);

package/scripts/optional/extract-thumbs.cjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * Build ad_id -> creative thumbnail for the buckets dashboard, from the Ad Library scrape.
+ *
+ * Meta's API is the natural source for previews, but this account is permanently rate
+ * limited (code 80004) and the creative pass keeps coming back empty — every ad ends up
+ * with preview_thumb: null. The Ad Library scrape already downloaded the same creatives,
+ * so this reads them off disk instead of asking Meta again.
+ *
+ *   research/meta-ads-library/<client>/
+ *     creatives-manifest.json   ad -> downloaded files
+ *     dedupe-map.json           file -> its representative in unique/
+ *     unique/                   the actual (deduped, downscaled) images
+ *        ->  data/meta-ads/<client>/thumbs/<ad_id>.jpg   +   thumbs.json
+ *
+ * Two details that cost time when they are missed:
+ *   - manifest adId is often prefixed ("ACME_CZ_120249…"), the insights API ad_id is not.
+ *     Joining without stripping the prefix silently matches nothing.
+ *   - dedupe-map keys are the ORIGINAL filenames (.png), while unique/ holds .jpg —
+ *     hence the extension rewrite. Deduping is why coverage is high: several ads
+ *     sharing one visual all resolve to the same representative file.
+ *
+ * Two sizes are written per ad:
+ *   thumbs/<ad_id>.jpg       small, shown in the table row (default 96px)
+ *   thumbs/<ad_id>@full.jpg  bigger, shown when the row thumbnail is clicked (default 600px)
+ *
+ * The originals are 1080×1350 and the whole unique/ folder is ~66 MB, so copying it wholesale
+ * would bloat the dashboard for no gain — 600px is already sharper than any lightbox needs.
+ * Only ads that actually appear in the dashboard get exported.
+ *
+ * Images are downscaled with `sips` (built into macOS); if sips is unavailable the original
+ * file is copied as-is.
+ *
+ * Usage: node extract-thumbs.cjs [size] [fullSize]     (default 96 / 600, long edge)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const cfg = require('../config.cjs');
+
+const SRC_DIR = path.join(process.cwd(), 'research', 'meta-ads-library', cfg.client);
+const UNIQUE = path.join(SRC_DIR, 'unique');
+const OUT_DIR = cfg.dataDir;
+const THUMB_DIR = path.join(OUT_DIR, 'thumbs');
+const OUT_JSON = path.join(OUT_DIR, 'thumbs.json');
+const BUCKETS = cfg.latestFile;
+
+// Scrapers often namespace their ad ids ("ACME_CZ_120249…") while the insights API does not.
+// Derived from the client slug; override with BUCKETS_AD_ID_PREFIX if yours differs.
+const ID_PREFIX = process.env.BUCKETS_AD_ID_PREFIX != null
+  ? process.env.BUCKETS_AD_ID_PREFIX
+  : `${cfg.envSuffix}_`;
+
+const SIZE = parseInt(process.argv[2]) || 96;
+const FULL_SIZE = parseInt(process.argv[3]) || 600;
+
+for (const f of ['creatives-manifest.json', 'dedupe-map.json']) {
+  if (!fs.existsSync(path.join(SRC_DIR, f))) {
+    console.error(`Error: ${f} not found in ${SRC_DIR} — run the Ad Library scrape first.`);
+    process.exit(1);
+  }
+}
+
+const manifest = JSON.parse(fs.readFileSync(path.join(SRC_DIR, 'creatives-manifest.json'), 'utf-8'));
+const dedupe = JSON.parse(fs.readFileSync(path.join(SRC_DIR, 'dedupe-map.json'), 'utf-8'));
+
+// original filename -> representative file in unique/ (always .jpg there)
+const repOf = {};
+for (const [rep, list] of Object.entries(dedupe)) {
+  const j = rep.replace(/\.[^.]+$/, '.jpg');
+  repOf[j] = j;                     // a representative maps to itself
+  for (const f of list) repOf[f] = j;
+}
+
+// A concept can merge several takes of one visual — typically the same layout with
+// and without an offer badge burned in. The promo verdict is decided per CONCEPT, so
+// an ad labelled "secondary message" can end up showing the variant with no badge on
+// it, and the label then looks wrong to anyone comparing the two. Where the concept
+// holds both, prefer the take that actually carries the offer.
+const OFFER = /1\s*\+\s*1|2\s*\+\s*1|3\s*\+\s*3|ZDARMA|SLEVA|-\s*\d+\s*%|\d+\s*%\s*(SLEVA|OFF)|VYPRODEJ/i;
+const promoOf = {};       // representative file -> the take showing the badge
+try {
+  const ang = JSON.parse(fs.readFileSync(path.join(SRC_DIR, 'angles-static.json'), 'utf-8'));
+  const clus = JSON.parse(fs.readFileSync(
+    path.join(SRC_DIR, 'concept-clusters-ai.json'), 'utf-8')).clustery;
+  const desc = JSON.parse(fs.readFileSync(
+    path.join(SRC_DIR, 'ai-descriptions.json'), 'utf-8')).descriptions;
+  const jpg = f => f.replace(/\.[^.]+$/, '.jpg');
+
+  ang.forEach((c, i) => {
+    if (c.promo !== 'secondary') return;
+    const files = clus[i] || [];
+    if (files.length < 2) return;
+    const withBadge = files.find(f => OFFER.test((desc[f] || {}).text || ''));
+    if (!withBadge) return;                      // offer lives in the copy, not the picture
+    // cluster files are already representatives (the .jpg keys of dedupe-map),
+    // so they can be used as-is — repOf maps the other direction
+    for (const f of files) promoOf[jpg(f)] = jpg(withBadge);
+  });
+} catch (e) {
+  console.warn('  ⚠ could not read the angle files — showing each concept\'s default take');
+}
+
+// ad_id (prefix stripped) -> representative image filename
+const srcOf = {};
+let swapped = 0;
+for (const m of manifest) {
+  const id = ID_PREFIX && String(m.adId).startsWith(ID_PREFIX)
+    ? String(m.adId).slice(ID_PREFIX.length)
+    : String(m.adId);
+  const first = (m.files || []).map(x => x.file)[0];
+  if (!first) continue;
+  const rep = repOf[first] || first.replace(/\.[^.]+$/, '.jpg');
+  const better = promoOf[rep];
+  if (better && better !== rep) swapped++;
+  srcOf[id] = better || rep;
+}
+
+if (swapped) console.log(`  ${swapped} ads switched to the take carrying the offer badge`);
+
+// Only bother with ads the dashboard actually shows.
+let wanted = Object.keys(srcOf);
+if (fs.existsSync(BUCKETS)) {
+  const b = JSON.parse(fs.readFileSync(BUCKETS, 'utf-8'));
+  const spent = new Set(b.ads.filter(a => a.spend > 0).map(a => a.ad_id));
+  wanted = wanted.filter(id => spent.has(id));
+}
+
+fs.mkdirSync(THUMB_DIR, { recursive: true });
+
+let ok = 0, missing = 0, copied = 0;
+const map = {};
+let sipsWorks = true;
+
+for (const id of wanted) {
+  const src = path.join(UNIQUE, srcOf[id]);
+  if (!fs.existsSync(src)) { missing++; continue; }
+  // small (row) + full (lightbox), both derived from the same source image
+  for (const [suffix, px] of [['', SIZE], ['@full', FULL_SIZE]]) {
+    const dst = path.join(THUMB_DIR, `${id}${suffix}.jpg`);
+    if (fs.existsSync(dst)) continue;
+    let done = false;
+    if (sipsWorks) {
+      try {
+        execFileSync('sips', ['-Z', String(px), src, '--out', dst], { stdio: 'ignore' });
+        done = true;
+      } catch (e) {
+        sipsWorks = false;   // not macOS / sips missing — fall back for the rest of the run
+      }
+    }
+    if (!done) { fs.copyFileSync(src, dst); copied++; }
+  }
+  map[id] = `thumbs/${id}.jpg`;   // relative to the dashboard html; @full is derived from it
+  ok++;
+}
+
+fs.writeFileSync(OUT_JSON, JSON.stringify(map, null, 2));
+
+console.log(`\nCreative thumbnails — ${cfg.client}`);
+console.log(`  source: ${path.relative(process.cwd(), UNIQUE)}`);
+console.log(`  thumbnails ready : ${ok}`);
+if (copied) console.log(`  copied full-size : ${copied} (sips unavailable)`);
+if (missing) console.log(`  source missing   : ${missing}`);
+console.log(`  sizes            : ${SIZE}px row · ${FULL_SIZE}px lightbox`);
+console.log(`\n✓ Saved ${OUT_JSON}`);
+console.log(`  images in ${path.relative(process.cwd(), THUMB_DIR)}/`);