164 lines
8.5 KiB
Markdown
164 lines
8.5 KiB
Markdown
# **Микросервис "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. **Клонируйте репозиторий:**
|
||
```bash
|
||
git clone [адрес_вашего_репозитория]
|
||
cd marquiz-metrics
|
||
```
|
||
2. **Настройте переменные окружения:**
|
||
Проверьте файл .env и вернитесь к нему с реальными данными после шага 4 - Регистрация приложения.
|
||
|
||
3. **Соберите и запустите контейнер:**
|
||
```bash
|
||
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/](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):**
|
||
```json
|
||
{
|
||
"counters": [
|
||
{
|
||
"id": 123456,
|
||
"name": "Мой сайт",
|
||
"site": "example.com"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### **2. Создание нового счетчика**
|
||
* **Метод:** `POST`
|
||
* **URL:** `/api/v1/counters/`
|
||
* **Описание:** Создает новый счетчик для указанного сайта.
|
||
* **Тело запроса:**
|
||
```json
|
||
{
|
||
"site_url": "https://new-quiz.com"
|
||
}
|
||
```
|
||
* **Успешный ответ (201 Created):**
|
||
```json
|
||
{
|
||
"id": 98765432,
|
||
"name": "new-quiz.com",
|
||
"code_status": "CS_NOT_FOUND"
|
||
}
|
||
```
|
||
|
||
#### **3. Создание стандартных целей**
|
||
* **Метод:** `POST`
|
||
* **URL:** `/api/v1/counters/{counter_id}/goals`
|
||
* **Описание:** Создает стандартный набор целей Marquiz в указанном счетчике.
|
||
* **Параметр пути `counter_id`:** ID счетчика, в котором нужно создать цели.
|
||
* **Тело запроса:**
|
||
```json
|
||
{
|
||
"goal_identifiers": [
|
||
"Marquiz-start",
|
||
"Marquiz-startquiz",
|
||
"Marquiz-form",
|
||
"Marquiz-result",
|
||
"Marquiz-contacts1"
|
||
]
|
||
}
|
||
```
|
||
* **Успешный ответ (201 Created):**
|
||
```json
|
||
{
|
||
"created_goals": [
|
||
{
|
||
"id": 460587013,
|
||
"name": "Посетитель открыл квиз"
|
||
},
|
||
{
|
||
"id": 460587014,
|
||
"name": "Посетитель нажал на кнопку стартовой страницы"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
--- |