Проект на React
Руководство по установке Bitrix24 JS SDK в приложениях React.
Эта страница ещё обновляется. Некоторые данные могут отсутствовать — мы их вскоре дополним.
Установка в проект React
Установка пакета Bitrix24 JS SDK
pnpm add @bitrix24/b24jssdk
yarn add @bitrix24/b24jssdk
npm install @bitrix24/b24jssdk
bun add @bitrix24/b24jssdk
Импорт
Импортируйте библиотеку в проект:
import { LoggerFactory } from '@bitrix24/b24jssdk'
Инициализация
Для работы с Bitrix24 из приложения, встроенного в интерфейс Bitrix24, используйте объект B24Frame.
Он инициализируется на стороне клиента через initializeB24Frame().
App.tsx
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk';
import type { DateTime } from 'luxon';
import { useEffect, useRef } from 'react';
import { initializeB24Frame, LoggerFactory, EnumCrmEntityTypeId, Text } from '@bitrix24/b24jssdk';
const devMode = typeof import.meta !== 'undefined' && (import.meta.env?.DEV ?? false);
const $logger = LoggerFactory.createForBrowser('MyApp', devMode);
type CompanyResponse = { id: number; title: string; createdTime: ISODate };
type Company = Omit<CompanyResponse, 'createdTime'> & { createdTime: DateTime };
async function loadCompanyList(b24: B24Frame): Promise<Company[]> {
const result: Company[] = [];
const response = await b24.actions.v2.call.make<{ items: CompanyResponse[] }>({
method: 'crm.item.list',
params: {
entityTypeId: EnumCrmEntityTypeId.company,
order: { id: 'DESC' },
select: ['id', 'title', 'createdTime'],
},
});
if (!response.isSuccess) {
throw new Error(`API Error: ${response.getErrorMessages().join('; ')}`);
}
const responseData = response.getData()!.result as { items: CompanyResponse[] };
responseData.items.forEach((entity) => {
result.push({
id: entity.id,
title: entity.title,
createdTime: Text.toDateTime(entity.createdTime),
});
});
return result;
}
function App() {
const b24Ref = useRef<B24Frame | null>(null);
useEffect(() => {
let isMounted = true;
async function init() {
try {
const b24 = await initializeB24Frame();
if (!isMounted) {
b24.destroy();
return;
}
b24Ref.current = b24;
const companies = await loadCompanyList(b24);
$logger.notice('Companies loaded successfully', { companies });
} catch (error) {
$logger.error('Some problems', { error });
}
}
init();
return () => {
isMounted = false;
b24Ref.current?.destroy();
};
}, []);
return (
<div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
<h1>B24 JS SDK - React Demo</h1>
<p>See the result in the developer console</p>
<p style={{ color: '#666', fontSize: '14px' }}>
Note: This app must be opened inside Bitrix24 as a frame application.
</p>
</div>
);
}
export default App;
Ключевые особенности React:
- Используйте React-хуки: инициализируйте B24Frame в useEffect с функцией очистки
- Используйте Refs: храните экземпляр B24Frame в ref, чтобы он сохранялся между рендерами
- Очистка: всегда вызывайте destroy() при размонтировании компонента, чтобы избежать утечек памяти
- Окружение: помните, что B24Frame работает только внутри iframe Bitrix24
Объект
B24Hook предназначен исключительно для использования на сервере.- Вебхук содержит секретный ключ доступа, который НЕЛЬЗЯ использовать в клиентском коде (браузер, мобильное приложение).
- Для клиентской стороны используйте
B24Frame
Для работы с Bitrix24 из автономного серверного приложения используйте объект B24Hook.
import { B24Hook } from '@bitrix24/b24jssdk'
// 1. Получите URL вебхука в Bitrix24:
// - Перейдите в Bitrix24
// - Настройки → Разработчикам → Вебхуки
// - Создайте новый вебхук с необходимыми правами
// - Скопируйте URL в формате: https://your-domain.bitrix24.com/rest/1/your-token/
// 2. Инициализируйте B24Hook
const $b24 = B24Hook.fromWebhookUrl('https://your-domain.bitrix24.com/rest/1/your-token/')
// 3. Используйте методы API
Объект
B24OAuth предназначен исключительно для использования на сервере.- B24OAuth содержит секретный ключ доступа, который НЕЛЬЗЯ использовать в клиентском коде (браузер, мобильное приложение).
- Для клиентской стороны используйте
B24Frame
Для работы с Bitrix24 из автономного серверного приложения используйте объект B24OAuth.
import { B24OAuth } from '@bitrix24/b24jssdk'
// 1. Зарегистрируйте приложение в Bitrix24:
// - Перейдите в Bitrix24
// - Настройки → Разработчикам → Приложения
// - Создайте новое приложение
// - Получите Client ID и Client Secret
// 2. Инициализируйте B24OAuth — передайте данные токена и OAuth-учётные данные отдельно.
// Полную форму B24OAuthParams см. на /docs/working-with-the-rest-api/oauth/.
import { EnumAppStatus } from '@bitrix24/b24jssdk'
const $b24 = new B24OAuth(
{
applicationToken: 'current_application_token',
userId: 1,
memberId: 'portal_member_id',
accessToken: 'current_access_token',
refreshToken: 'refresh_token',
expires: 1745997853, // unix timestamp, секунды
expiresIn: 3600,
scope: 'crm,user_brief',
domain: 'your-domain.bitrix24.com',
clientEndpoint: 'https://your-domain.bitrix24.com/rest/',
serverEndpoint: 'https://oauth.bitrix.info/rest/',
status: EnumAppStatus.Free
},
{
clientId: 'your_client_id',
clientSecret: 'your_client_secret'
}
)
// 3. Используйте методы API
// B24OAuth автоматически обновляет токены при их истечении