Embed SDK (виджеты)
Встраиваемые виджеты кабинета инфлюенсера MeerPartners: дашборд, ссылки, сеть, выплаты — внутри вашего продукта через scoped-токен из token-exchange. Концепция и связь с SSO.
Embed SDK — это способ встроить кабинет инфлюенсера прямо в ваш продукт: пользователь видит свою партнёрскую статистику, ссылки и выплаты, не уходя на портал MeerPartners. Виджеты работают на коротком scoped-токене, который вы получаете через token-exchange.
Статус и детали реализации
Концепция embed-виджетов и scoped-токен affiliate:embed уже поддержаны на стороне API. Конкретная поставка SDK (имя npm-пакета, точные имена компонентов и параметры инициализации) может уточняться — ориентируйтесь на актуальную инструкцию, которую выдаёт оператор платформы вместе с доступом. Ниже описана концепция и контракт, на который SDK опирается, без выдуманных деталей пакета.
Идея
Вместо того чтобы вести пользователя на отдельный сайт партнёрки и заставлять логиниться, вы:
- на своём бэкенде обмениваете идентификатор пользователя на scoped-токен;
- передаёте токен во фронтенд;
- инициализируете виджет — он сам ходит в API партнёрки с этим токеном.
Пользователь остаётся в вашем интерфейсе и под вашим аккаунтом — повторная регистрация не нужна.
Какие виджеты
Виджеты соответствуют разделам кабинета инфлюенсера:
| Виджет | Что показывает |
|---|---|
| Дашборд | Сводные метрики партнёра: клики, конверсии, доход |
| Ссылки | Трекинг-ссылки партнёра и их создание |
| Сеть | Многоуровневая реферальная структура партнёра |
| Выплаты | Баланс, заявки на вывод и история |
Объём доступа = scope токена
Виджеты ограничены правами scoped-токена affiliate:embed. Это кабинет инфлюенсера конкретного пользователя — не админка и не кабинет бизнеса. «Опасные» действия (выход из всех сессий, онбординг ролей) для embed-токена недоступны.
Связь с token-exchange
Весь доступ виджетов завязан на scoped-токен из token-exchange. Поток:
Ваш фронтенд Ваш бэкенд MeerPartners
│ показать виджет │ │
│ ────────────────────► │ POST /api/v1/auth/token-exchange
│ │ (HMAC, scope sso) │
│ │ ────────────────────────►│
│ │ ◄── access (affiliate:embed) │
│ ◄── scoped-токен ─────│ expires_in: 600 │
│ │ │
│ init виджета с токеном ───────────────────────────► API партнёркиМинимальный практический сценарий интеграции:
Получите токен на бэкенде
Вызовите token-exchange со своим subject_token и API-ключом scope sso. В ответе придёт access_token (scope: "affiliate:embed", TTL 10 минут), refresh_token, affiliate_id и tenant_id.
Передайте токен во фронтенд
Отдайте access_token своему фронтенду по защищённому каналу. Секрет API-ключа во фронтенд не передаётся — только готовый scoped-токен.
Инициализируйте виджет
Передайте токен в SDK при инициализации нужного виджета. Дальше виджет сам обращается к API партнёрки от имени пользователя.
Обновляйте сессию
Access-токен короткий (10 минут). Используйте refresh_token для продления через POST /api/v1/auth/refresh, либо повторяйте token-exchange.
Никогда не выпускайте scoped-токен из браузера
Token-exchange подписывается секретом API-ключа и поэтому выполняется только на бэкенде. Во фронтенд попадает лишь короткоживущий scoped-токен. Если выпускать токены прямо из браузера, секрет ключа утечёт.