Подключение аккаунтов Яндекс.Директ и Метрики

Документ описывает процесс подготовки OAuth-приложения, подключения рекламных и аналитических аккаунтов, а также требования, которые необходимо выполнить агентству и конечным пользователям (клиентам).

1. Что нужно заранее

1. Яндекс ID с правами:
   • для Директа — права администратора рекламного кабинета или агентский логин;
   • для Метрики — права «Полный доступ» к счётчикам.
2. Зарегистрированное OAuth‑приложение в кабинете разработчика Яндекса (https://oauth.yandex.ru/client/new).
3. Хостинг приложения (ваш сервер или сервер клиента), доступный по HTTPS.

2. Создание OAuth‑приложения

1. Перейдите в кабинет разработчика Яндекса под нужным Яндекс ID.
2. Заполните:
   • Название, контактный email.
   • Тип приложения: Веб-сервисы.
   • Redirect URI:
     • для продакшн‑установки: https://<ваш-домен>/direct/callback
     • для разработки локально: http://localhost:8000/direct/callback
   • Разрешения:
     • Яндекс.Директ → выбрать «JSON API». Это добавит необходимые scope direct:campaigns, direct:reports, direct:ads, direct:keywords.
     • Яндекс.Метрика → metrika:read, metrika:write, analytics:read_apps.
3. После сохранения скопируйте ID приложения (client_id) и Пароль приложения (client_secret) — они понадобятся для конфигурации.
4. Ознакомьтесь и примите условия использования API Яндекс.Директ и Метрики (для агентств — условия партнёрской программы).

3. Настройка параметров приложения

В файле .env (или в системе окружения) задайте:

YANDEX_CLIENT_ID=<ID приложения>
YANDEX_CLIENT_SECRET=<Пароль приложения>
OAUTH_AUTHORIZE_URL=https://oauth.yandex.ru/authorize
OAUTH_TOKEN_URL=https://oauth.yandex.ru/token

Важно: храните секреты в защищённом месте, используйте менеджер секретов или переменные окружения сервера. Не коммитите их в репозиторий.

4. Подключение аккаунта Яндекс.Директ

1. Войдите в Yandex Audit Platform под своей учётной записью.
2. Откройте раздел «Интеграция с Яндексом» на главной странице и нажмите «Подключить Директ».
3. В открывшемся окне авторизации Яндекса убедитесь, что выбрано нужное Яндекс ID, и предоставьте разрешения приложению.
4. После успешного ввода кода приложение:
   • получает access_token и refresh_token,
   • шифрует и сохраняет их в БД,
   • записывает дату истечения (обычно 365 дней).
5. Проверьте, что в разделе «Аккаунты» появился нужный логин, и выполните пробную синхронизацию кампаний.

5. Подключение счётчиков Метрики

Метрика и Директ используют общий OAuth‑токен. После первого подключения:

1. Нажмите «Синхронизировать Метрику» (кнопка в UI или API /api/metrica/sync).
2. Приложение загрузит список доступных счётчиков (/api/metrica/counters) и сохранит их в БД.
3. По необходимости выберите счётчики, которые следует связать с конкретными рекламными аккаунтами (настройка сопоставления поддерживается в БД или будет добавлена в UI).

Если требуется подключить другой Яндекс ID к тому же приложению, пользователь проходит те же шаги авторизации. Токены и данные хранятся изолированно в рамках его учётной записи платформы.

6. Особенности установки «у клиента»

Если вы развёртываете платформу на сервере клиента:

1. Клиент создаёт собственное OAuth‑приложение в Яндексе (см. раздел 2) и передаёт вам client_id/client_secret.
2. Вы настраиваете переменные окружения на его сервере.
3. Клиент самостоятельно авторизуется в интерфейсе и подключает свои аккаунты.

Агентство может использовать своё OAuth‑приложение, но тогда оно несёт ответственность за хранение токенов клиентов. Для on-premise решений лучше, чтобы каждый клиент создавал приложение на свою организацию.

7. Правила и рекомендации Яндекса

• Не храните access_token в открытом виде: в платформе используется шифрование (модуль security.encryption). Убедитесь, что ключ шифрования надёжно защищён.
• Обновляйте токены через refresh_token до истечения срока. В планах — автоматический фоновой процесс.
• Передавайте данные только по защищённому HTTPS.
• Соблюдайте политики конфиденциальности Яндекса и проинформируйте клиентов о передаче данных.
• При утрате доступа немедленно отзовите токен в кабинете приложений.

8. Типичные вопросы

9. ToDo/планы автоматизации

• UI для сопоставления счётчиков Метрики и аккаунтов Direct.
• Планировщик для автопродления токенов.
• Логи проверки разрешений и уведомления при их истечении.

Если потребуется помощь на конкретном шаге — используйте инструкцию на фронтенде (раздел «Интеграция с Яндексом») или обратитесь к документации Яндекс.Директ/Метрики по ссылкам внутри приложения.