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+); в более старых браузерах фрейм не покажется — это сознательный безопасный отказ.
См. также
- Ключи, права и лимиты — публикуемый ключ и права
- Федерация (tenant API) — данные для виджетов
- Tilda — подключение сайта на Tilda
- Creatium — подключение сайта на Creatium
- Быстрый старт — первый вызов API