Recca Разработчикам
Меню

JS и виджеты

Встраиваемые компоненты и JS-клиент: как подключить их на свой сайт.

Recca отдаёт интерфейс сети кусками, которые вы ставите на свой сайт: личный код участника, баланс, заявки, дерево сети. Есть два способа. Основной — веб-компоненты (Custom Elements) без iframe. Запасной — iframe-виджеты. Оба показывают данные конкретного человека только с токеном, который выписывает ваш сервер.

Как устроен доступ

Посетитель — пользователь вашего сайта и про Recca ничего не знает. Поэтому токен для виджета выписывает ваш бэкенд методом POST /federation/v1/users/{id}/embed-session (право ключа users:impersonate), где {id} — tenant_recca_id этого человека. Ответ содержит token и expires_in (600 секунд). Токен принадлежит одной сети и одному человеку: чужой сети он не подойдёт (TENANT_MISMATCH), а чужие данные по нему не читаются.

Ключ сети в браузер не попадает никогда. Страница знает только адрес вашего собственного метода, который отдаёт токен.

// ваш сервер (Node.js), ключ из переменной окружения
app.get("/api/recca/embed-token", async (req, res) => {
  const r = await fetch(
    `https://api.recca.ru/federation/v1/users/${req.user.tenantReccaId}/embed-session`,
    { method: "POST", headers: { "X-Recca-Tenant-Key": process.env.RECCA_TENANT_KEY } }
  )
  const { data } = await r.json()           // { token, expires_in }
  res.json({ token: data.token, expires_in: data.expires_in })
})

Решайте на своей стороне, чей токен чеканить: берите человека из вашей сессии, а не из параметров запроса.

Подключение компонентов

<script type="module" src="https://api.recca.ru/cdn/embed-components/v1.js"></script>
<script type="module">
  ReccaEmbedComponents.configureRecca({ tokenUrl: "/api/recca/embed-token" })
</script>

<recca-cabinet-kpi
  tenant="my-network"
  user-id="<tenant_recca_id>"
  api-base="https://api.recca.ru"
  theme="light">
</recca-cabinet-kpi>

tenant — слаг вашей сети, user-id — суррогат участника. api-base по умолчанию https://api.recca.ru. Тема — visitka, light или dark. Вместо tokenUrl можно передать функцию: configureRecca({ getToken: async () => token }); она должна вернуть { token, expires_in }.

Клиент берёт на себя обновление токена: он живёт 10 минут, вкладка, открытая дольше, обновляет его сама; несколько виджетов на странице делают один запрос к вашему адресу; после ответа 401 клиент просит новый токен и повторяет запрос один раз.

Теги

ТегЧто показываетНужен токен
<recca-referral-input>генератор реферальной ссылкинет
<recca-referral-display>готовая ссылка, переданная атрибутомнет
<recca-cabinet-kpi>плитки: заявки, доступно, в обработке, статусда
<recca-bonus-balance>баланс и история начисленийда
<recca-recent-leads>последние заявки с пагинациейда
<recca-referral-tree>дерево сетида
<recca-promo-my-code>личный промо-код участникада
<recca-promo-assets>материалы программыда
<recca-action-button>кнопка в фирменном стиленет
<recca-login-button>вход через Recca (попап OAuth)нет

Подробные атрибуты тегов (share-text, button-label, target-type и другие) видны в исходниках пакета @recca/embed-components. Пакет публикуется и как npm-пакет, и как скрипт на CDN; на CDN всегда лежит актуальная версия v1.js.

Вход через Recca

Тег <recca-login-button> открывает попап OAuth и кладёт сессию в localStorage. Подходит сетям без собственного бэкенда. Для интеграции, где у вас есть свои пользователи, он неверен по существу: просить вашего пользователя войти в другой сервис ломает ваш продукт. Используйте путь с токеном от вашего сервера. Если выбрали попап, код авторизации меняйте на токен на своём бэкенде (POST /oauth/token с X-Recca-Tenant-Key), не в браузере.

iframe-виджеты

Запасной путь для площадок, где нельзя подключить скрипт модулем. Страницы живут по адресам https://api.recca.ru/embed/v1/…: badge/{user_id}, login-button, cabinet/{user_id}, partner-cabinet/{user_id}, lead-form, referral-tree/{user_id}, leads/{user_id}, bonuses/{user_id}. Параметры: tenant (слаг сети), theme (light или dark), для бейджа size (sm, md, lg). Страница с данными отдаёт реальные данные только запросу с токеном; простой GET без токена показывает демонстрационное содержимое.

Бейдж показывает только активное публичное партнёрство вашей сети; во всех остальных случаях (скрытое, отозванное, неизвестное) отдаётся нейтральная заглушка, существование скрытого партнёрства не раскрывается. Для встраивания есть клиент @recca/embed-sdk: он монтирует iframe, подстраивает высоту, передаёт тему и проверяет источник postMessage.

Iframe откроется только с разрешённого сайта: адреса, на которых вы встраиваете, должны быть записаны в «разрешённых origin» организации. Для адреса не из списка сервер отдаёт frame-ancestors 'none', и браузер откажется показывать фрейм. Это не обходится: обратитесь в поддержку, чтобы адрес внесли в список.

Безопасность

  • Ключ сети — только на сервере. Токен — короткоживущий, для одного человека.
  • В обработчике message всегда проверяйте event.origin === "https://api.recca.ru".
  • Сессия попапа в localStorage уязвима к XSS: держите строгий CSP на своём сайте.
  • Токен в компонентах не сохраняется в хранилище браузера.

Браузеры и пределы

Веб-компоненты: Chrome 73+, Firefox 101+, Safari 16.4+. В более старых браузерах теги рисуются, но тема не применяется. Для iframe нужна поддержка CSP frame-ancestors (Chrome 40+, Firefox 33+, Safari 15.4+, Edge 79+); в более старых браузерах фрейм не покажется — это сознательный безопасный отказ.

См. также