← всі звіти · meta-ads-library-token-howto.md

Як безпечно оформити Meta Ads Library API токен

Для: реальний колега Deltamedical з власним верифікованим FB-акаунтом Час: ~20-30 хв на перші 5 кроків + 1-2 дні очікування верифікації (якщо ще не пройдена) Ризик для колеги: мінімальний якщо дотримуватись цієї інструкції (не ділитись паролем/2FA/сесійними cookies)

Що ми просимо і чому це безпечно

  1. Ми НЕ просимо пароль FB — ніколи
  2. Ми НЕ просимо 2FA коди — ніколи
  3. Ми НЕ просимо сесійні cookies — ніколи
  4. Ми просимо тільки API токен (рядок 200+ символів) який:
    • дає тільки read-only доступ до публічної Ad Library (це та сама база яку всі бачать на facebook.com/ads/library)
    • НЕ дає доступ до особистого профілю, повідомлень, друзів, фото
    • НЕ дає права постити від імені колеги або ставити лайки
    • Може бути відкликаний в 1 клік у будь-який момент: Settings → Business Tools → Apps
    • Не перенесе на колегу жодної відповідальності — Ad Library API read-only, ми не можемо ним нашкодити

Кроки для колеги

Крок 1. Перевірити верифікацію особи у Meta

Перейти: https://www.facebook.com/id (Identity Confirmation)

Meta вимагає верифікацію особи для доступу до Ad Library API з 2023 року. Якщо ще не пройдена — треба:

Якщо верифікація вже є — одразу переходь до кроку 2.

Крок 2. Створити Meta-додаток для розробника

  1. Зайти на https://developers.facebook.com/ під власним FB-акаунтом
  2. Прийняти terms (якщо перший раз)
  3. My Apps → Create App
  4. Use case: Other
  5. App Type: Business (важливо — не Consumer!)
  6. App Name: Deltamedical Competitive Intel (або інша ідентифікована назва — не анонімна)
  7. Contact email: робочий email колеги (@deltamedical.ua якщо є)
  8. Create App → ввести пароль для підтвердження

Крок 3. Прийняти Ad Library API terms

  1. У створеному додатку: App Review → Permissions and Features
  2. Знайти ads_read → Get Advanced Access
  3. Окремо: відвідати https://www.facebook.com/ads/library/api/
  4. Прийняти Terms of Service for Ad Library API
  5. Підтвердити що запит буде використовуватись для research (не для реклами, не для скрапінгу на продаж)

Крок 4. Згенерувати System User Token (найбезпечніший спосіб)

Чому System User, а не User Token: System User — це «технічний юзер» всередині Business Manager, не прив'язаний до особистого акаунту колеги. Якщо колись треба буде відкликати доступ — один клік, особистий акаунт не постраждає.

  1. Перейти на https://business.facebook.com/
  2. Якщо Business Manager ще не створений — Create Business Portfolio → назва «Deltamedical»
  3. Business Settings → Users → System Users → Add
  4. Name: api-ads-library-claude, Role: Employee
  5. Assign Assets → вибрати створений у кроці 2 додаток → Permission: Read
  6. Generate New Token:
    • App: наш додаток
    • Token Expiration: 60 days (краще) або Never (ще краще)
    • Scopes: тільки ads_read — нічого більше не вибирати!
  7. Скопіювати токен — він з'являється 1 раз

Крок 5. Передати токен безпечно

❌ НЕ через Telegram як текст ❌ НЕ через email у plain text ❌ НЕ у файл в месенджер

✅ Як безпечно:

Сергій передасть мені токен через пасспартут (/srv/passepartout/meta/ads-library-api-token.txt) — файл буде з правами 600 (тільки root).

Що ми робимо з токеном у себе

  1. Зберігаємо у пасспартуті як всі інші секрети, меток .meta з описом (правила пам'яті)
  2. Використовуємо тільки для endpoint'ів:
    • GET /ads_archive — пошук оголошень за ключовими словами/країнами
    • GET /ads_archive?search_page_ids=... — оголошення конкретних сторінок
  3. Ніколи не зберігаємо в коді, не світимо в логах, не коммітимо
  4. Rate-limit: ~200 запитів/годину за замовчуванням — нам достатньо

Що отримує колега натомість (від нас)

  1. Ротація — щоразу як Meta вимагатиме rotate, робимо через колегу
  2. Прозорість — лог використання токена колега може запросити будь-коли
  3. Миттєвий revoke — якщо колега передумає, відкликає одним кліком у Business Settings

Відкат якщо щось піде не так

  1. Колега → Business Settings → System Users → Delete token
  2. Видалити App: developers.facebook.com → Settings → Delete
  3. Ми видаляємо /srv/passepartout/meta/ads-library-api-token.txt і записуємо в decisions_log

Альтернатива якщо FB-колеги немає

Якщо жоден колега не хоче робити — можна:

Ці варіанти не безкоштовні і не дають full-fidelity, але знімають ризик з колеги.

Питання Сергію після прочитання:

  1. Хто саме з колег буде оформляти? (важливо — вони мусять мати верифікований FB)
  2. Чи є у нас Business Manager Deltamedical, чи колега створить новий?
  3. Передача токена — через який канал (1Password / Proton / інше)?