0
# VK Bridge
1

2
VK Bridge is a JavaScript/TypeScript bridge library that enables seamless communication between VK Mini Apps and official VK clients across iOS, Android, and Web platforms. It provides a comprehensive API for accessing native VK client features through a promise-based interface, supporting over 110 methods for user authentication, device features, social interactions, payments, and platform-specific capabilities.
3

4
## Package Information
5

6
- **Package Name**: @vkontakte/vk-bridge
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @vkontakte/vk-bridge`
10

11
## Core Imports
12

13
```typescript
14
import bridge from "@vkontakte/vk-bridge";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const bridge = require("@vkontakte/vk-bridge");
21
```
22

23
Additional imports:
24

25
```typescript
26
import bridge, { applyMiddleware, parseURLSearchParamsForGetLaunchParams } from "@vkontakte/vk-bridge";
27
```
28

29
For browser usage:
30

31
```html
32
<script src="https://unpkg.com/@vkontakte/vk-bridge/dist/browser.min.js"></script>
33
<script>
34
  // Available as global vkBridge
35
  vkBridge.send('VKWebAppInit');
36
</script>
37
```
38

39
## Basic Usage
40

41
```typescript
42
import bridge from "@vkontakte/vk-bridge";
43

44
// Initialize the bridge connection
45
await bridge.send('VKWebAppInit');
46

47
// Get user information
48
const userInfo = await bridge.send('VKWebAppGetUserInfo');
49
console.log('User:', userInfo.first_name, userInfo.last_name);
50

51
// Subscribe to events from VK client
52
bridge.subscribe((event) => {
53
  if (!event.detail) return;
54
  
55
  const { type, data } = event.detail;
56
  console.log('Received event:', type, data);
57
  
58
  if (type === 'VKWebAppUpdateConfig') {
59
    console.log('App config updated:', data);
60
  }
61
});
62

63
// Check platform capabilities
64
const canShowImages = await bridge.supportsAsync('VKWebAppShowImages');
65
if (canShowImages) {
66
  await bridge.send('VKWebAppShowImages', {
67
    images: ['https://example.com/photo1.jpg']
68
  });
69
}
70
```
71

72
## Architecture
73

74
VK Bridge is built around several key components:
75

76
- **Bridge Instance**: Main `bridge` object providing send/subscribe interface for all VK client communication
77
- **Platform Detection**: Runtime environment detection (WebView, iframe, standalone) with capability checking
78
- **Method Registry**: 110+ API methods organized by functional areas (auth, UI, device, social, etc.)
79
- **Event System**: Promise-based request/response pattern with event subscription for real-time updates
80
- **Middleware Support**: Redux-style middleware system for intercepting and processing bridge communications
81
- **Type Safety**: Full TypeScript support with comprehensive type definitions for all methods and responses
82

83
## Capabilities
84

85
### Core Bridge Interface
86

87
Primary bridge instance with send/subscribe methods for all VK client communication. Essential for initializing apps and managing the communication lifecycle.
88

89
```typescript { .api }
90
interface VKBridge {
91
  /** Send event to VK client and receive response */
92
  send: <K extends AnyRequestMethodName>(
93
    method: K,
94
    props?: RequestProps<K> & RequestIdProp
95
  ) => Promise<K extends AnyReceiveMethodName ? ReceiveData<K> : void>;
96
  
97
  /** Subscribe to events from VK client */
98
  subscribe: (listener: VKBridgeSubscribeHandler) => void;
99
  
100
  /** Unsubscribe from events */
101
  unsubscribe: (listener: VKBridgeSubscribeHandler) => void;
102
  
103
  /** Check method support asynchronously */
104
  supportsAsync: <K extends AnyRequestMethodName>(method: K) => Promise<boolean>;
105
  
106
  /** Check if running in WebView */
107
  isWebView: () => boolean;
108
  
109
  /** Check if running in iframe */
110
  isIframe: () => boolean;
111
  
112
  /** Check if running embedded (WebView or iframe) */
113
  isEmbedded: () => boolean;
114
  
115
  /** Check if running standalone */
116
  isStandalone: () => boolean;
117
}
118

119
type VKBridgeSubscribeHandler = (event: VKBridgeEvent<AnyReceiveMethodName>) => void;
120

121
interface RequestIdProp {
122
  request_id?: number | string;
123
}
124
```
125

126
[Core Bridge Interface](./core-bridge.md)
127

128
### Authentication & Authorization
129

130
User and community authentication with access token management and permission scoping. Essential for accessing VK API and user data.
131

132
```typescript { .api }
133
// Get user access token
134
function send(method: 'VKWebAppGetAuthToken', props: {
135
  app_id: number;
136
  scope: PersonalAuthScope | string;
137
}): Promise<{
138
  access_token: string;
139
  scope: string;
140
  expires?: number;
141
}>;
142

143
// Get community access token
144
function send(method: 'VKWebAppGetCommunityToken', props: {
145
  app_id: number;
146
  group_id: number;
147
  scope: CommunityAuthScope | string;
148
}): Promise<{
149
  access_token: string;
150
  scope: string;
151
}>;
152

153
type PersonalAuthScope = 'friends' | 'photos' | 'video' | 'stories' | 'pages' | 'status' | 'notes' | 'wall' | 'docs' | 'groups' | 'stats' | 'market';
154
type CommunityAuthScope = 'stories' | 'photos' | 'app_widget' | 'messages' | 'docs' | 'manage';
155
```
156

157
[Authentication & Authorization](./authentication.md)
158

159
### User Data & Profile
160

161
Access to user profile information, friends, contact details, and personal data with privacy controls.
162

163
```typescript { .api }
164
// Get user information
165
function send(method: 'VKWebAppGetUserInfo', props?: {
166
  user_id?: number;
167
  user_ids?: string;
168
}): Promise<UserInfo>;
169

170
// Get user's friends
171
function send(method: 'VKWebAppGetFriends', props?: {
172
  multi?: boolean;
173
}): Promise<{
174
  users: UserGetFriendsFriend[];
175
}>;
176

177
interface UserInfo {
178
  id: number;
179
  first_name: string;
180
  last_name: string;
181
  photo_100: string;
182
  photo_200: string;
183
  is_closed: boolean;
184
  can_access_closed: boolean;
185
}
186
```
187

188
[User Data & Profile](./user-data.md)
189

190
### Application Lifecycle
191

192
Application initialization, configuration, and lifecycle management including launch parameter handling.
193

194
```typescript { .api }
195
// Initialize bridge
196
function send(method: 'VKWebAppInit'): Promise<{ result: true }>;
197

198
// Get launch parameters
199
function send(method: 'VKWebAppGetLaunchParams'): Promise<GetLaunchParamsResponse>;
200

201
// Close application
202
function send(method: 'VKWebAppClose', props: {
203
  status: AppCloseStatus;
204
  payload?: any;
205
}): Promise<{ payload: any }>;
206

207
interface GetLaunchParamsResponse {
208
  vk_user_id: number;
209
  vk_app_id: number;
210
  vk_platform: EGetLaunchParamsResponsePlatforms;
211
  vk_language: EGetLaunchParamsResponseLanguages;
212
  vk_is_app_user: 0 | 1;
213
  vk_are_notifications_enabled: 0 | 1;
214
  sign: string;
215
}
216
```
217

218
[Application Lifecycle](./application-lifecycle.md)
219

220
### UI & Display Control
221

222
User interface management including view settings, window resizing, scrolling, and appearance control.
223

224
```typescript { .api }
225
// Set appearance and status bar
226
function send(method: 'VKWebAppSetViewSettings', props: {
227
  status_bar_style: AppearanceType;
228
  action_bar_color?: 'none' | string;
229
  navigation_bar_color?: string;
230
}): Promise<{ result: true }>;
231

232
// Show image gallery
233
function send(method: 'VKWebAppShowImages', props: {
234
  images: string[];
235
  start_index?: number;
236
}): Promise<{ result: true }>;
237

238
type AppearanceType = 'light' | 'dark';
239
```
240

241
[UI & Display Control](./ui-display.md)
242

243
### Device Features & Sensors
244

245
Access to device capabilities including haptic feedback, camera flash, sensors, clipboard operations, and hardware features.
246

247
```typescript { .api }
248
// Haptic feedback
249
function send(method: 'VKWebAppTapticImpactOccurred', props: {
250
  style: TapticVibrationPowerType;
251
}): Promise<{ result: true }>;
252

253
// Start accelerometer
254
function send(method: 'VKWebAppAccelerometerStart', props?: {
255
  refresh_rate?: string;
256
}): Promise<{ result: true }>;
257

258
// Copy text to clipboard
259
function send(method: 'VKWebAppCopyText', props: {
260
  text: string;
261
}): Promise<{ result: true }>;
262

263
// Open contacts picker
264
function send(method: 'VKWebAppOpenContacts'): Promise<{
265
  phone?: string;
266
  first_name?: string;
267
  last_name?: string;
268
}>;
269

270
type TapticVibrationPowerType = 'light' | 'medium' | 'heavy';
271
```
272

273
[Device Features & Sensors](./device-features.md)
274

275
### Social Features
276

277
Social interactions including sharing, wall posts, communities, stories, and VK platform integration.
278

279
```typescript { .api }
280
// Share content
281
function send(method: 'VKWebAppShare', props?: {
282
  link?: string;
283
}): Promise<LinkShareResult[]>;
284

285
// Join community
286
function send(method: 'VKWebAppJoinGroup', props: {
287
  group_id: number;
288
}): Promise<{ result: true }>;
289

290
// Show wall post dialog
291
function send(method: 'VKWebAppShowWallPostBox', props: WallPostRequestOptions): Promise<{
292
  post_id: number | string;
293
}>;
294
```
295

296
[Social Features](./social-features.md)
297

298
### Storage & Data Management
299

300
Client-side storage management for persisting application data across sessions.
301

302
```typescript { .api }
303
// Set storage value
304
function send(method: 'VKWebAppStorageSet', props: {
305
  key: string;
306
  value: string;
307
}): Promise<{ result: true }>;
308

309
// Get storage values
310
function send(method: 'VKWebAppStorageGet', props: {
311
  keys: string[];
312
}): Promise<{
313
  keys: Array<{ key: string; value: string }>;
314
}>;
315
```
316

317
[Storage & Data Management](./storage-data.md)
318

319
### Payments & Commerce
320

321
Payment processing and e-commerce functionality for monetizing VK Mini Apps.
322

323
```typescript { .api }
324
// Open payment form
325
function send(method: 'VKWebAppOpenPayForm', props: VKPayProps<VKPayActionType>): Promise<
326
  TransactionResult | { result: TransactionResult }
327
>;
328

329
interface VKPayProps<T extends VKPayActionType> {
330
  app_id: number;
331
  action: T;
332
  params: VKPayActionParamsMap[T];
333
}
334
```
335

336
[Payments & Commerce](./payments-commerce.md)
337

338
### Advertising & Monetization
339

340
Advertising integration including native ads, banner ads, and conversion tracking for app monetization.
341

342
```typescript { .api }
343
// Show banner ad
344
function send(method: 'VKWebAppShowBannerAd', props: ShowBannerAdRequest): Promise<VKWebAppShowBannerAdResponse>;
345

346
// Check native ads availability
347
function send(method: 'VKWebAppCheckNativeAds', props: {
348
  ad_format: EAdsFormats;
349
  use_waterfall?: boolean;
350
}): Promise<{ result: boolean }>;
351

352
enum EAdsFormats {
353
  REWARD = 'reward',
354
  INTERSTITIAL = 'interstitial'
355
}
356
```
357

358
[Advertising & Monetization](./advertising-monetization.md)
359

360
### Middleware System
361

362
Redux-style middleware for intercepting and processing bridge communications, enabling logging, data transformation, and custom handling.
363

364
```typescript { .api }
365
function applyMiddleware(
366
  ...middlewares: Array<Middleware | undefined | null>
367
): (bridge: VKBridge) => VKBridge;
368

369
type Middleware<S extends VKBridgeSend = VKBridgeSend> = (
370
  api: MiddlewareAPI<S>
371
) => (next: S) => S;
372

373
interface MiddlewareAPI<S extends VKBridgeSend = VKBridgeSend> {
374
  send: S;
375
  subscribe(listener: VKBridgeSubscribeHandler): void;
376
}
377
```
378

379
[Middleware System](./middleware.md)
380

381
### QR & Barcode Scanning
382

383
Camera-based scanning capabilities for QR codes, barcodes, and other machine-readable codes with customizable scanning modes.
384

385
```typescript { .api }
386
// Open QR code scanner
387
function send(method: 'VKWebAppOpenCodeReader'): Promise<{
388
  code_data: string;
389
  code_type?: string;
390
}>;
391

392
// Alternative QR scanner
393
function send(method: 'VKWebAppOpenQR'): Promise<{
394
  qr_data: string;
395
}>;
396
```
397

398
[QR & Barcode Scanning](./qr-barcode-scanning.md)
399

400
### Geolocation Services
401

402
Access device location data and geographic information with privacy controls and accuracy options.
403

404
```typescript { .api }
405
// Get device location
406
function send(method: 'VKWebAppGetGeodata'): Promise<{
407
  lat: number;
408
  long: number;
409
  accuracy?: number;
410
}>;
411

412
// Set app location context
413
function send(method: 'VKWebAppSetLocation', props: {
414
  location: string;
415
}): Promise<{ result: true }>;
416
```
417

418
[Geolocation Services](./geolocation.md)
419

420
### Launch Parameters Parsing
421

422
Utility for parsing VK Mini App launch parameters from URL search params with type-safe extraction.
423

424
```typescript { .api }
425
function parseURLSearchParamsForGetLaunchParams(
426
  searchParams: string
427
): Partial<LaunchParams>;
428

429
interface LaunchParams extends GetLaunchParamsResponse {
430
  vk_chat_id: string;
431
  vk_is_recommended: number;
432
  vk_profile_id: number;
433
  vk_has_profile_button: number;
434
  vk_testing_group_id: number;
435
  odr_enabled: undefined | 1;
436
}
437
```
438

439
[Launch Parameters Parsing](./launch-parameters.md)
440

441
## Types
442

443
### Core Event Types
444

445
```typescript { .api }
446
interface VKBridgeEvent<M extends AnyReceiveMethodName> {
447
  detail: {
448
    type: M extends AnyRequestMethodName ? ResultResponseEventName<M> : M;
449
    data: M extends AnyReceiveMethodName ? ReceiveData<M> : never;
450
  };
451
}
452

453
interface VKBridgeEventBase<Type extends string, Data> {
454
  detail: {
455
    type: Type;
456
    data: Data;
457
  };
458
}
459
```
460

461
### Error Types
462

463
```typescript { .api }
464
type ErrorData = 
465
  | {
466
      error_type: 'client_error';
467
      error_data: ErrorDataClientError;
468
      request_id?: number | string;
469
    }
470
  | {
471
      error_type: 'api_error';
472
      error_data: ErrorDataAPIError;
473
      request_id?: number | string;
474
    }
475
  | {
476
      error_type: 'auth_error';
477
      error_data: ErrorDataAuthError;
478
      request_id?: number | string;
479
    };
480

481
interface ErrorDataClientError {
482
  error_code: number;
483
  error_reason: string;
484
  error_description?: string;
485
}
486

487
interface ErrorDataAPIError {
488
  error_code: number;
489
  error_msg: string;
490
  request_params: string[];
491
}
492

493
interface ErrorDataAuthError {
494
  error_code: number;
495
  error_reason: string;
496
  error_description?: string[];
497
}
498
```
499

500
### Method Name Types
501

502
```typescript { .api }
503
type AnyRequestMethodName = keyof RequestPropsMap;
504
type AnyReceiveMethodName = keyof ReceiveDataMap;
505
type AnyRequestOnlyMethodName = Exclude<AnyRequestMethodName, AnyReceiveMethodName>;
506
type AnyReceiveOnlyMethodName = Exclude<AnyReceiveMethodName, AnyRequestMethodName>;
507
type AnyIOMethodName = AnyRequestMethodName & AnyReceiveMethodName;
508
```