Migration to v1
This guide provides step-by-step instructions to migrate your application to Bitrix24 JS SDK v1.
After upgrading to Bitrix24 JS SDK v1, please note the following important changes:
Change
PlacementManager.title
To align with documentation and reduce confusion, the PlacementManager.title property has been renamed to PlacementManager.placement.
- if (b24Frame.placement.title === 'DEFAULT') {
+ if (b24Frame.placement.placement === 'DEFAULT') {
// some code
}
TypeB24.getTargetOriginWithPath
Get the account address Bitrix24 with path
The function now returns paths for restApi:v2 and restApi:v3.
+ import { ApiVersion } from '@bitrix24/b24jssdk'
- b24.getTargetOriginWithPath()
+ b24.getTargetOriginWithPath().get(ApiVersion.v2)
+ b24.getTargetOriginWithPath().get(ApiVersion.v3)
TypeB24.getHttpClient
Returns the HTTP client to perform the request.
The function now returns HTTP client for restApi:v2 and restApi:v3.
+ import { ApiVersion } from '@bitrix24/b24jssdk'
- b24.getHttpClient()
+ b24.getHttpClient(ApiVersion.v2)
+ b24.getHttpClient(ApiVersion.v3)
Error
All errors now inherit from SdkError. Just be aware of that.
+ import { SdkError } from '@bitrix24/b24jssdk'
try {
// ...
} catch (error) {
- if (error instanceof Error) {
+ if (error instanceof SdkError) {
// ...
}
}
Removed
Unused methods in TypeHttp
Request registration methods:
TypeHttp.setLogTag()TypeHttp.clearLogTag()
Now you need to use the requestId parameter for these purposes.
Unused methods in Http
Method for displaying system messages Http.getSystemLogger()
Now forced display is used via LoggerFactory.forcedLog()
Restriction Manager
The RestrictionManager class has been removed. The Limiters system is used instead.
- import { RestrictionManagerParamsForEnterprise } from '@bitrix24/b24jssdk'
+ import { ParamsFactory } from '@bitrix24/b24jssdk'
- $b24.getHttpClient().setRestrictionManagerParams( RestrictionManagerParamsForEnterprise )
+ $b24.setRestrictionManagerParams( ParamsFactory.getEnterprise() )
// or
+ const b24 = B24Hook.fromWebhookUrl(hookPath, { restrictionParams: ParamsFactory.getEnterprise() })
- $b24.getHttpClient().setRestrictionManagerParams( { sleep: 600, speed: 0.01, amount: 30 * 5 } )
+ $b24.setRestrictionManagerParams( { rateLimit: { burstLimit: 250, drainRate: 5 } } )
Deprecated
AbstractB24.batchSize
Maximum length for batch response.
This const is deprecated and will be removed in version 2.0.0.
- if (size < AbstractB24.batchSize) {
+ if (size < 50) {
// some code ...
}
TypeB24.callMethod
Calls the Bitrix24 REST API method.
This method is deprecated and will be removed in version 2.0.0.
For restApi:v2, you must use the b24.actions.v2.call.make(options) method.
- await b24.callMethod('some.method', { filter: { '>id': 123 } }, 100)
+ await b24.actions.v2.call.make({
+ method: 'some.method',
+ params: {
+ filter: { '>id': 123 },
+ start: 100
+ },
+ requestId: 'unique-request-id'
+ })
For restApi:v3, you must use the b24.actions.v3.call.make(options) method.
- await b24.callMethod('some.method', { filter: { '>id': 123 } }, 100)
+ await b24.actions.v3.call.make({
+ method: 'some.method',
+ params: {
+ filter: [['id', '>', 123 ]],
+ pagination: { limit: 50, page: 2 }
+ },
+ requestId: 'unique-request-id'
+ })
TypeB24.callListMethod
Calls a Bitrix24 REST API list method to retrieve all data.
This method is deprecated and will be removed in version 2.0.0.
For restApi:v2, you must use the b24.actions.v2.call.callList(options) method.
- await b24.callListMethod('some.method', { filter: { '>id': 123 } }, null, 'items')
+ await b24.actions.v2.callList.make({
+ method: 'some.method',
+ params: { filter: { '>id': 123 } },
+ idKey: 'id',
+ customKeyForResult: 'items',
+ requestId: 'unique-request-id'
+ })
For restApi:v3, you must use the b24.actions.v3.call.callList(options) method.
- await b24.callListMethod('some.method', { filter: { '>id': 123 } }, null, 'items')
+ await b24.actions.v3.callList.make({
+ method: 'some.method',
+ params: { filter: [['id', '>', 123 ]] },
+ idKey: 'id',
+ customKeyForResult: 'items',
+ requestId: 'unique-request-id',
+ limit: 60
+ })
TypeB24.fetchListMethod
Calls a Bitrix24 REST API list method and returns an async generator.
This method is deprecated and will be removed in version 2.0.0.
For restApi:v2, you must use the b24.actions.v2.fetchList.make(options) method.
- b24.fetchListMethod('some.method', { filter: { '>id': 123 } }, 'id', 'items')
+ b24.actions.v2.fetchList.make({
+ method: 'some.method',
+ params: { filter: { '>id': 123 } },
+ idKey: 'id',
+ customKeyForResult: 'items',
+ requestId: 'unique-request-id'
+ })
For restApi:v3, you must use the b24.actions.v3.fetchList.make(options) method.
- b24.fetchListMethod('some.method', { filter: { '>id': 123 } }, 'id', 'items')
+ b24.actions.v3.fetchList.make({
+ method: 'some.method',
+ params: { filter: [['id', '>', 123 ]] },
+ idKey: 'id',
+ customKeyForResult: 'items',
+ requestId: 'unique-request-id',
+ limit: 60
+ })
TypeB24.callBatch
Executes a batch request to the Bitrix24 REST API.
This method is deprecated and will be removed in version 2.0.0.
For restApi:v2, you must use the b24.actions.v2.batch.make(options) method.
- await b24.callBatch([['some.method.1', { filter: { '>id': 123 } }], ['some.method.2', { filter: { '<id': 456 } }]], true, true)
+ await b24.actions.v2.batch.make({
+ calls: [
+ ['some.method.1', { filter: { '>id': 123 } }],
+ ['some.method.2', { filter: { '<id': 456 } }],
+ ],
+ options: {
+ isHaltOnError: true,
+ returnAjaxResult: true,
+ requestId: 'unique-request-id'
+ }
+ })
For restApi:v3, you must use the b24.actions.v3.batch.make(options) method.
- await b24.callBatch([['some.method.1', { filter: { '>id': 123 } }], ['some.method.2', { filter: { '<id': 456 } }]], true, true)
+ await b24.actions.v3.batch.make({
+ calls: [
+ ['some.method.1', { filter: [['id', '>', 123 ]] }],
+ ['some.method.2', { filter: [['id', '<', 456 ]] }],
+ ],
+ options: {
+ isHaltOnError: true,
+ returnAjaxResult: true,
+ requestId: 'unique-request-id'
+ }
+ })
TypeB24.callBatchByChunk
Executes a batch request to the Bitrix24 REST API with automatic chunking for any number of commands.
This method is deprecated and will be removed in version 2.0.0.
For restApi:v2, you must use the b24.actions.v2.batchByChunk.make(options) method.
- await b24.callBatchByChunk([['some.method.1', { filter: { '>id': 123 } }], ['some.method.2', { filter: { '<id': 456 } }]], true)
+ await b24.actions.v2.batchByChunk.make({
+ calls: [
+ ['some.method.1', { filter: { '>id': 123 } }],
+ ['some.method.2', { filter: { '<id': 456 } }],
+ ],
+ options: {
+ isHaltOnError: true,
+ requestId: 'unique-request-id'
+ }
+ })
For restApi:v3, you must use the b24.actions.v3.batchByChunk.make(options) method.
- await b24.callBatchByChunk([['some.method.1', { filter: { '>id': 123 } }], ['some.method.2', { filter: { '<id': 456 } }]], true)
+ await b24.actions.v3.batchByChunk.make({
+ calls: [
+ ['some.method.1', { filter: [['id', '>', 123 ]] }],
+ ['some.method.2', { filter: [['id', '<', 456 ]] }],
+ ],
+ options: {
+ isHaltOnError: true,
+ requestId: 'unique-request-id'
+ }
+ })
LoggerBrowser
Used for logging data
This class is deprecated and will be removed in version 2.0.0.
Now a more universal logging system is used, somewhat similar to Monolog (PHP).
- import { LoggerBrowser } from '@bitrix24/b24jssdk'
+ import { LoggerFactory } from '@bitrix24/b24jssdk'
- const $logger = LoggerBrowser.build('MyApp', import.meta.env?.DEV === true)
+ const $logger = LoggerFactory.createForBrowser('MyApp', import.meta.env?.DEV === true)
const dataList = { key1: value1, key2: value2 }
- $logger.info('response', dataList)
+ $logger.info('response', { someInfo: dataList })