В этой статье расскажем что такое Telegram Widgets, зачем они нужны и как максимально просто добавить их в своё React приложение.
Что такое Telegram Widgets?
Telegram Widgets - API от Telegram, которое позволяет быстро добавить на сайт кнопку "Поделиться", встроить посты из публичных каналов или групп. С его помощью пользователи также могут авторизоваться через Telegram или просматривать обсуждения прямо на сайте.
Проблема с использованием в React приложениях
Дело в том что Telegram Widget - это script-тег вида:
<script
async
src="https://telegram.org/js/telegram-widget.js?22"
data-telegram-post="baranov_guru/61"
data-width="100%"
></script>Он инициализируется и добавляет в родительский контейнер iframe, который рендерит контент с нужными параметрами.
Из-за этого с виджетами очень неудобно работать в декларативном стиле, присущем React-компонентам. Поэтому нам пришлось написать небольшую обёртку над скриптами, позволяющую:
- Подписываться на события загрузки;
- Отслеживать ошибки;
- В удобном декларативном стиле пробрасывать необходимые свойства виджетов;
- Корректно обрабатывать изменения свойств и перерендеры компонентов;
А так как официального React-пакета для виджетов нет и не предвиделось, поэтому мы решили оформить её в виде npm-пакета @baranov-guru/react-telegram-widgets.
Что делает пакет @baranov-guru/react-telegram-widgets?
С версии 1.1.0 пакет поддерживает:
- Комментарии (
TelegramDiscussionWidget) — обсуждение постов прямо на сайте. - Посты из ТГ-каналов (
TelegramPostWidget) — отдельный пост из публичного Telegram-канала или группы. - Кнопку «Поделиться» (
TelegramShareWidget) — шаринг ссылки в Telegram. - Вход через Telegram (
TelegramLoginWidgetи хукuseTelegramLogin) — текущий OpenID Connect-логин. - Legacy Login Widget (
TelegramLegacyLoginWidget) — старый iframe-виджет сhash; для новых интеграций лучше OIDC.
Установка
npm install @baranov-guru/react-telegram-widgetsПримеры использования
Виджет комментариев (TelegramDiscussionWidget)
import { TelegramDiscussionWidget } from "@baranov-guru/react-telegram-widgets";
function App() {
return (
<div>
<h1>Discussion</h1>
<TelegramDiscussionWidget
discussion="baranov_guru"
commentsLimit={10}
height={400}
color="#ff0000"
colorful={true}
dark={true}
onLoad={() => console.log("Comments loaded!")}
onError={(error) => console.error("Failed to load comments:", error)}
/>
</div>
);
}Этот компонент можно встроить под статьёй или любым другим контентом. Все комментарии будут сохраняться в Telegram и синхронизироваться между пользователями.
Встраивание поста (TelegramPostWidget)
import { TelegramPostWidget } from "@baranov-guru/react-telegram-widgets";
const App = () => (
<TelegramPostWidget
post="baranov_guru/61"
userpic
onLoad={() => console.log("Post loaded!")}
onError={(error) => console.error("Failed to load post:", error)}
className="w-full flex p-2"
/>
);Просто указываете название канала и ID поста — и он появляется на странице.
Кнопка «Поделиться» (TelegramShareWidget)
import { TelegramShareWidget } from "@baranov-guru/react-telegram-widgets";
function ShareSection() {
return (
<TelegramShareWidget
url="https://example.com/article"
comment="Check out this article!"
size="large"
/>
);
}Нужны абсолютный url и при желании comment и size (large | medium | small).
Вход через Telegram (TelegramLoginWidget)
Актуальный способ — OpenID Connect login. Зарегистрируйте origin сайта в @BotFather (Login Widget → Allowed URLs) и используйте числовой Client ID.
telegram-login.js открывает попап. Если сайт отдаёт заголовок Cross-Origin-Opener-Policy: same-origin, логин не сработает — нужен same-origin-allow-popups (или без этого заголовка).
import {
TelegramLoginWidget,
TelegramLoginSuccess,
} from "@baranov-guru/react-telegram-widgets";
function LoginPage() {
const handleAuth = async (result: TelegramLoginSuccess) => {
// Отправьте id_token на бэкенд и проверьте его там.
await fetch("/api/auth/telegram", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ id_token: result.id_token }),
});
};
return (
<TelegramLoginWidget
clientId={123456789}
scope={["profile", "write"]}
onAuth={handleAuth}
onError={(error) => console.error("Login failed:", error)}
/>
);
}Без готовой кнопки — хук useTelegramLogin:
import { useTelegramLogin } from "@baranov-guru/react-telegram-widgets";
function CustomLoginButton() {
const { login, isReady, isLoading, error } = useTelegramLogin({
clientId: 123456789,
scope: ["profile"],
onAuth: (result) => console.log(result.id_token, result.user),
});
return (
<button type="button" disabled={!isReady || isLoading} onClick={() => login()}>
Continue with Telegram
</button>
);
}id_token всегда проверяйте на сервере. Хелперов для верификации в пакете нет — примеры проверки есть в README на npm и в репозитории.
Legacy Login Widget (TelegramLegacyLoginWidget)
Старый iframe Login Widget с полем hash. Для новых интеграций лучше TelegramLoginWidget.
import {
TelegramLegacyLoginWidget,
TelegramLegacyLoginData,
} from "@baranov-guru/react-telegram-widgets";
function LegacyLoginPage() {
const handleAuth = async (user: TelegramLegacyLoginData) => {
await fetch("/api/auth/telegram-legacy", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(user),
});
};
return (
<TelegramLegacyLoginWidget
botName="SampleBot"
size="large"
radius={8}
requestAccess={true}
onAuth={handleAuth}
onError={(error) => console.error("Login widget error:", error)}
/>
);
}Вместо (или вместе с) onAuth можно задать authUrl для редиректа после входа.
Документация
Все доступные пропсы и примеры есть в npm-профиле пакета. Там всё кратко и по делу.
Поддержите проект ⭐️
Если вам пригодился этот пакет — будем рады, если поставите ему звёздочку на GitHub. Это поможет другим разработчикам найти его.
