Микросервис "Marquiz Metrica Connector"

1. Введение

Marquiz Metrica Connector — это stateless-микросервис на FastAPI, предназначенный для полной автоматизации процесса настройки Яндекс.Метрики для квизов, созданных на платформе Marquiz.

Сервис выступает в роли безопасного бэкенд-посредника ("половинки" приложения) между frontend-частью личного кабинета Marquiz и Management API Яндекс.Метрики.

Ключевые возможности

• Безопасная авторизация пользователей через протокол Яндекс.OAuth 2.0.
• Получение списка счетчиков пользователя.
• Создание новых счетчиков с настройками по умолчанию.
• Автоматическое создание стандартного набора целей типа "JavaScript-событие" для квизов Marquiz.

---

2. Стек технологий

• Язык: Python 3.11
• Фреймворк: FastAPI
• Сервер: Uvicorn
• HTTP-клиент: HTTPX (для асинхронных запросов)
• Валидация: Pydantic
• Логирование: Loguru
• Окружение: Docker (образ python:3.11-slim)
• Управление: Docker Compose

---

3. Быстрый старт (для локального тестирования)

1. Клонируйте репозиторий:

   git clone [адрес_вашего_репозитория]
   cd marquiz-metrics
   

2. Настройте переменные окружения: Проверьте файл .env и вернитесь к нему с реальными данными после шага 4 - Регистрация приложения.

3. Соберите и запустите контейнер:

   docker compose up -d --build
   

4. Проверьте работоспособность:

   • Сервис будет доступен по адресу, настроенному в вашем прокси-менеджере (например, http://localhost:8000).
   • Интерактивная документация API (Swagger UI) доступна по адресу: http://localhost:8000/docs.

---

4. Руководство по интеграции для Frontend-разработчиков Marquiz

Шаг 1: Настройка приложения в Яндекс.OAuth

Для работы интеграции необходимо зарегистрировать приложение на стороне Яндекса.

• Адрес для регистрации: https://oauth.yandex.ru/
• Тип приложения: "Веб-сервисы".

Ключевые параметры при регистрации:

1. Redirect URI: Это самый важный параметр. Это URL на стороне Marquiz, куда Яндекс вернет пользователя после авторизации.

   • Для тестирования можно использовать: https://oauth.yandex.ru/verification_code
   • Для рабочей версии это должен быть специальный роут в приложении Marquiz, например: https://marquiz.ru/integration/yandex/callback

2. Права доступа (Scopes): Приложению необходимы следующие права. Чтобы их найти, начните вводить "metrika" в пустой строке выбора прав:

   • metrika:read - Получение статистики, чтение параметров своих и доверенных счётчиков.
   • metrika:write - Создание счётчиков, изменение параметров своих и доверенных счётчиков.

После регистрации вы получите ClientID и Client secret. Их необходимо будет передать backend-разработчику для внесения в .env файл на сервере.

Шаг 2: Процесс авторизации пользователя (OAuth 2.0 Flow)

Процесс полностью интерактивный и инициируется на стороне frontend.

1. Инициация: Пользователь нажимает кнопку "Подключить Яндекс.Метрику".

2. Редирект на Яндекс: Frontend Marquiz формирует ссылку и перенаправляет браузер пользователя на страницу авторизации Яндекса.

   https://oauth.yandex.ru/authorize?response_type=code&client_id=ВАШ_CLIENT_ID&redirect_uri=ВАШ_REDIRECT_URI
   

3. Согласие пользователя: Пользователь на сайте Яндекса входит в свой аккаунт и разрешает приложению Marquiz доступ к данным Метрики.

4. Возврат в Marquiz: Яндекс перенаправляет пользователя обратно на redirect_uri с временным code в параметрах URL:

   https://marquiz.ru/integration/yandex/callback?code=A1B2C3D4...
   

5. Обмен code на access_token: JavaScript-код на странице /callback извлекает code из URL и немедленно отправляет его на наш backend-сервис:

   • Эндпоинт: POST /api/v1/auth/token
   • Тело запроса: {"code": "A1B2C3D4..."}

6. Получение и сохранение токена: Наш сервис в ответ возвращает access_token. Frontend обязан сохранить этот токен (например, в localStorage или в сессии пользователя) для всех последующих запросов к API.

Шаг 3: Справка по API эндпоинтам

Для всех запросов, кроме /auth/token, требуется заголовок Authorization: Bearer <access_token>.

1. Получение списка счетчиков

• Метод: GET
• URL: /api/v1/counters/
• Описание: Возвращает список всех счетчиков, доступных пользователю.
• Успешный ответ (200 OK):

  {
    "counters": [
      {
        "id": 123456,
        "name": "Мой сайт",
        "site": "example.com"
      }
    ]
  }
  

2. Создание нового счетчика

• Метод: POST
• URL: /api/v1/counters/
• Описание: Создает новый счетчик для указанного сайта.
• Тело запроса:

  {
    "site_url": "https://new-quiz.com"
  }
  

• Успешный ответ (201 Created):

  {
    "id": 98765432,
    "name": "new-quiz.com",
    "code_status": "CS_NOT_FOUND"
  }
  

3. Создание стандартных целей

• Метод: POST
• URL: /api/v1/counters/{counter_id}/goals
• Описание: Создает стандартный набор целей Marquiz в указанном счетчике.
• Параметр пути counter_id: ID счетчика, в котором нужно создать цели.
• Тело запроса:

  {
    "goal_identifiers": [
      "Marquiz-start",
      "Marquiz-startquiz",
      "Marquiz-form",
      "Marquiz-result",
      "Marquiz-contacts1"
    ]
  }
  

• Успешный ответ (201 Created):

  {
    "created_goals": [
      {
        "id": 460587013,
        "name": "Посетитель открыл квиз"
      },
      {
        "id": 460587014,
        "name": "Посетитель нажал на кнопку стартовой страницы"
      }
    ]
  }
  

---