341 lines
13 KiB
Markdown
341 lines
13 KiB
Markdown
# Учетные данные 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](https://business.facebook.com/adsmanager)
|
||
2. В настройках аккаунта найдите "Account ID"
|
||
3. Или используйте API: `GET /me/adaccounts`
|
||
|
||
---
|
||
|
||
### 3. **App ID и App Secret (обязательно для серверных приложений)**
|
||
|
||
Учетные данные Facebook приложения.
|
||
|
||
**Где найти:**
|
||
|
||
1. Перейдите на [Facebook Developers](https://developers.facebook.com/)
|
||
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](https://developers.facebook.com/)
|
||
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](https://developers.facebook.com/tools/explorer/)
|
||
2. Выберите ваше приложение
|
||
3. Нажмите "Generate Access Token"
|
||
4. Выберите необходимые разрешения
|
||
5. Скопируйте полученный токен
|
||
|
||
#### Вариант B: Long-Lived Token (для разработки)
|
||
|
||
```bash
|
||
# Обмен краткосрочного токена на долгосрочный
|
||
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](https://business.facebook.com/adsmanager)
|
||
2. В настройках аккаунта найдите "Account ID"
|
||
|
||
**Через API:**
|
||
|
||
```bash
|
||
curl -X GET "https://graph.facebook.com/v18.0/me/adaccounts?access_token={access-token}"
|
||
```
|
||
|
||
Ответ будет содержать массив с `id` в формате `act_XXXXXXXXX`.
|
||
|
||
---
|
||
|
||
## Структура учетных данных для вашего API
|
||
|
||
Для интеграции с вашей системой, учетные данные Facebook для рекламы должны быть сохранены в следующем формате:
|
||
|
||
### Формат JSON для сохранения credentials
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```javascript
|
||
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
|
||
|
||
```bash
|
||
curl -X GET "https://graph.facebook.com/v18.0/me?access_token={access-token}"
|
||
```
|
||
|
||
Если токен валиден, вы получите информацию о пользователе.
|
||
|
||
### Проверка доступа к Ad Account
|
||
|
||
```bash
|
||
curl -X GET "https://graph.facebook.com/v18.0/{ad-account-id}?access_token={access-token}&fields=id,name,account_id"
|
||
```
|
||
|
||
Если доступ есть, вы получите информацию об аккаунте.
|
||
|
||
### Проверка разрешений
|
||
|
||
```bash
|
||
curl -X GET "https://graph.facebook.com/v18.0/me/permissions?access_token={access-token}"
|
||
```
|
||
|
||
Проверьте, что в ответе есть:
|
||
|
||
- `ads_management` со статусом `granted`
|
||
- `ads_read` со статусом `granted`
|
||
- `business_management` со статусом `granted`
|
||
|
||
---
|
||
|
||
## Примеры использования для создания рекламной кампании
|
||
|
||
### Создание кампании
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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. **Или запросите новый токен** перед истечением старого
|
||
|
||
### Обмен краткосрочного токена на долгосрочный
|
||
|
||
```javascript
|
||
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](https://developers.facebook.com/docs/marketing-apis)
|
||
- [Facebook Graph API Explorer](https://developers.facebook.com/tools/explorer/)
|
||
- [Facebook Business Settings](https://business.facebook.com/settings)
|
||
- [Facebook Ads Manager](https://business.facebook.com/adsmanager)
|
||
- [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/)
|
||
|
||
---
|
||
|
||
## Поддержка
|
||
|
||
При возникновении проблем с получением или использованием учетных данных:
|
||
|
||
1. Проверьте документацию Facebook Marketing API
|
||
2. Используйте [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/) для проверки токена
|
||
3. Убедитесь, что все разрешения запрошены и одобрены
|
||
4. Проверьте, что рекламный аккаунт активен и имеет необходимые права
|