marketing-parser/FACEBOOK_ADS_CREDENTIALS.md

Учетные данные Facebook для запуска рекламы

Обзор

Для запуска рекламных кампаний в Facebook через Marketing API (ранее Ads API) требуются специальные учетные данные, которые отличаются от простого Access Token для публикации постов.

---

Необходимые учетные данные

1. Access Token (обязательно)

Access Token с расширенными разрешениями для управления рекламой.

Требуемые разрешения (Permissions):

• ads_management - Управление рекламными кампаниями
• ads_read - Чтение данных о рекламе
• business_management - Управление бизнес-аккаунтом
• pages_read_engagement - Чтение данных страниц (опционально)

Типы токенов:

• User Access Token - краткосрочный (1-2 часа)
• Long-Lived User Access Token - долгосрочный (60 дней)
• Page Access Token - для управления страницами
• System User Access Token - для серверных приложений (рекомендуется для продакшена)

---

2. Ad Account ID (обязательно)

ID рекламного аккаунта Facebook, в котором будут создаваться кампании.

Формат: act_XXXXXXXXX (например: act_123456789)

Где найти:

1. Перейдите в Facebook Ads Manager
2. В настройках аккаунта найдите "Account ID"
3. Или используйте API: GET /me/adaccounts

---

3. App ID и App Secret (обязательно для серверных приложений)

Учетные данные Facebook приложения.

Где найти:

1. Перейдите на Facebook Developers
2. Выберите ваше приложение
3. В разделе "Settings" → "Basic" найдите:
   • App ID
   • App Secret (нажмите "Show" для отображения)

Важно: App Secret должен храниться в безопасности и никогда не передаваться на клиент.

---

4. Page ID (опционально, но рекомендуется)

ID страницы Facebook, связанной с рекламным аккаунтом.

Где найти:

1. Перейдите на вашу страницу Facebook
2. В настройках страницы найдите "Page ID"
3. Или используйте API: GET /me/accounts

---

Пошаговая инструкция получения учетных данных

Шаг 1: Создание Facebook приложения

1. Перейдите на Facebook Developers
2. Нажмите "My Apps" → "Create App"
3. Выберите тип приложения: "Business" или "Other"
4. Заполните название и контактный email
5. Нажмите "Create App"

Шаг 2: Добавление продукта "Marketing API"

1. В панели управления приложением найдите раздел "Add Products"
2. Найдите "Marketing API" и нажмите "Set Up"
3. Следуйте инструкциям для настройки

Шаг 3: Получение App ID и App Secret

1. В левом меню выберите "Settings" → "Basic"
2. Скопируйте App ID
3. Нажмите "Show" рядом с App Secret и скопируйте его
4. Сохраните эти данные в безопасном месте

Шаг 4: Настройка разрешений (Permissions)

1. В левом меню выберите "Settings" → "Advanced"
2. Добавьте в "Valid OAuth Redirect URIs" ваш callback URL
3. В разделе "Permissions and Features" запросите:
   • ads_management
   • ads_read
   • business_management
   • pages_read_engagement

Шаг 5: Получение Access Token

Вариант A: User Access Token (для тестирования)

1. Перейдите в Graph API Explorer
2. Выберите ваше приложение
3. Нажмите "Generate Access Token"
4. Выберите необходимые разрешения
5. Скопируйте полученный токен

Вариант B: Long-Lived Token (для разработки)

# Обмен краткосрочного токена на долгосрочный
curl -X GET "https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app-id}&client_secret={app-secret}&fb_exchange_token={short-lived-token}"

Вариант C: System User Token (для продакшена - рекомендуется)

1. В панели управления приложением перейдите в "Business Settings"
2. Создайте System User
3. Назначьте ему доступ к рекламному аккаунту
4. Сгенерируйте токен для System User

Шаг 6: Получение Ad Account ID

Через Ads Manager:

1. Перейдите в Facebook Ads Manager
2. В настройках аккаунта найдите "Account ID"

Через API:

curl -X GET "https://graph.facebook.com/v18.0/me/adaccounts?access_token={access-token}"

Ответ будет содержать массив с id в формате act_XXXXXXXXX.

---

Структура учетных данных для вашего API

Для интеграции с вашей системой, учетные данные Facebook для рекламы должны быть сохранены в следующем формате:

Формат JSON для сохранения credentials

{
  "platform": "facebook_ads",
  "credentials": {
    "accessToken": "EAABwzLix...",
    "adAccountId": "act_123456789",
    "appId": "1234567890123456",
    "appSecret": "your-app-secret-here",
    "pageId": "1234567890123456",
    "tokenType": "LONG_LIVED",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}

Пример сохранения через API

const facebookAdsCredentials = {
  platform: 'facebook_ads',
  credentials: JSON.stringify({
    accessToken: 'EAABwzLix...',
    adAccountId: 'act_123456789',
    appId: '1234567890123456',
    appSecret: 'your-app-secret-here',
    pageId: '1234567890123456',
    tokenType: 'LONG_LIVED',
    expiresAt: '2024-12-31T23:59:59Z',
  }),
};

// Сохранение через ваш API
const response = await fetch('/api/social-media/credentials', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(facebookAdsCredentials),
});

---

Требования и ограничения

Ограничения Facebook Marketing API

1. Rate Limits:

   • 200 вызовов в час на пользователя
   • 4800 вызовов в час на приложение

2. Минимальные требования:

   • Рекламный аккаунт должен быть активен
   • У пользователя должны быть права администратора на аккаунте
   • Приложение должно пройти ревью Facebook (для продакшена)

3. Версия API:

   • Текущая версия: v18.0
   • Facebook регулярно обновляет API, следите за изменениями

Безопасность

1. Никогда не храните App Secret в открытом виде
2. Используйте шифрование для хранения credentials (ваша система уже использует шифрование)
3. Регулярно обновляйте токены (Long-Lived токены истекают через 60 дней)
4. Используйте System User Token для продакшена вместо User Token

---

Проверка учетных данных

Проверка Access Token

curl -X GET "https://graph.facebook.com/v18.0/me?access_token={access-token}"

Если токен валиден, вы получите информацию о пользователе.

Проверка доступа к Ad Account

curl -X GET "https://graph.facebook.com/v18.0/{ad-account-id}?access_token={access-token}&fields=id,name,account_id"

Если доступ есть, вы получите информацию об аккаунте.

Проверка разрешений

curl -X GET "https://graph.facebook.com/v18.0/me/permissions?access_token={access-token}"

Проверьте, что в ответе есть:

• ads_management со статусом granted
• ads_read со статусом granted
• business_management со статусом granted

---

Примеры использования для создания рекламной кампании

Создание кампании

curl -X POST "https://graph.facebook.com/v18.0/{ad-account-id}/campaigns" \
  -d "name=Test Campaign" \
  -d "objective=OUTCOME_TRAFFIC" \
  -d "status=PAUSED" \
  -d "access_token={access-token}"

Создание Ad Set

curl -X POST "https://graph.facebook.com/v18.0/{ad-account-id}/adsets" \
  -d "name=Test Ad Set" \
  -d "campaign_id={campaign-id}" \
  -d "billing_event=IMPRESSIONS" \
  -d "optimization_goal=REACH" \
  -d "bid_amount=100" \
  -d "daily_budget=1000" \
  -d "targeting={'geo_locations':{'countries':['KZ']}}" \
  -d "access_token={access-token}"

---

Обновление токенов

Access Token имеет срок действия. Для автоматического обновления:

1. Отслеживайте срок действия токена (expiresAt)
2. Используйте refresh token (если доступен)
3. Или запросите новый токен перед истечением старого

Обмен краткосрочного токена на долгосрочный

async function exchangeToken(shortLivedToken, appId, appSecret) {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id=${appId}&client_secret=${appSecret}&fb_exchange_token=${shortLivedToken}`
  );

  const data = await response.json();
  return {
    accessToken: data.access_token,
    expiresIn: data.expires_in, // в секундах
    expiresAt: new Date(Date.now() + data.expires_in * 1000).toISOString(),
  };
}

---

Рекомендации

1. Для разработки: Используйте Long-Lived User Access Token
2. Для продакшена: Используйте System User Access Token
3. Храните credentials в зашифрованном виде (ваша система уже это делает)
4. Реализуйте автоматическое обновление токенов
5. Логируйте все операции с рекламой для отладки
6. Обрабатывайте ошибки API (rate limits, invalid tokens, etc.)

---

Полезные ссылки

• Facebook Marketing API Documentation
• Facebook Graph API Explorer
• Facebook Business Settings
• Facebook Ads Manager
• Access Token Debugger

---

Поддержка

При возникновении проблем с получением или использованием учетных данных:

1. Проверьте документацию Facebook Marketing API
2. Используйте Access Token Debugger для проверки токена
3. Убедитесь, что все разрешения запрошены и одобрены
4. Проверьте, что рекламный аккаунт активен и имеет необходимые права