0
# Core Bridge Interface
1

2
The primary VK Bridge interface providing essential communication methods between VK Mini Apps and VK clients across all supported platforms.
3

4
## Capabilities
5

6
### Bridge Instance
7

8
The main bridge object providing the complete VK Bridge API.
9

10
```typescript { .api }
11
/**
12
 * Default export - VK Bridge instance
13
 * Provides complete API for VK Mini App communication
14
 */
15
declare const bridge: VKBridge;
16

17
interface VKBridge {
18
  /** Send event to VK client and receive response */
19
  send: VKBridgeSend;
20
  
21
  /** Deprecated alias for send method */
22
  sendPromise: VKBridgeSend;
23
  
24
  /** Subscribe to events from VK client */
25
  subscribe: (listener: VKBridgeSubscribeHandler) => void;
26
  
27
  /** Unsubscribe from events */
28
  unsubscribe: (listener: VKBridgeSubscribeHandler) => void;
29
  
30
  /** Check method support synchronously (deprecated) */
31
  supports: <K extends AnyRequestMethodName>(method: K) => boolean;
32
  
33
  /** Check method support asynchronously */
34
  supportsAsync: <K extends AnyRequestMethodName>(method: K) => Promise<boolean>;
35
  
36
  /** Check if running in WebView */
37
  isWebView: () => boolean;
38
  
39
  /** Check if running in iframe */
40
  isIframe: () => boolean;
41
  
42
  /** Check if running embedded (WebView or iframe) */
43
  isEmbedded: () => boolean;
44
  
45
  /** Check if running standalone */
46
  isStandalone: () => boolean;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import bridge from "@vkontakte/vk-bridge";
54

55
// Initialize bridge connection
56
await bridge.send('VKWebAppInit');
57

58
// Check environment
59
if (bridge.isWebView()) {
60
  console.log('Running in mobile app WebView');
61
} else if (bridge.isIframe()) {
62
  console.log('Running in iframe (web)');
63
} else {
64
  console.log('Running standalone');
65
}
66

67
// Check method support before using
68
const canAccessCamera = await bridge.supportsAsync('VKWebAppOpenCodeReader');
69
if (canAccessCamera) {
70
  const result = await bridge.send('VKWebAppOpenCodeReader');
71
  console.log('QR code:', result.code_data);
72
}
73
```
74

75
### Send Method
76

77
Primary method for sending events to VK client with type-safe responses.
78

79
```typescript { .api }
80
/**
81
 * Send event to VK client and receive typed response
82
 * @param method - VK Bridge method name
83
 * @param props - Method-specific parameters (optional for some methods)
84
 * @returns Promise with method-specific response data
85
 */
86
type VKBridgeSend = <K extends AnyRequestMethodName>(
87
  method: K,
88
  props?: RequestProps<K> & RequestIdProp
89
) => Promise<K extends AnyReceiveMethodName ? ReceiveData<K> : void>;
90

91
interface RequestIdProp {
92
  request_id?: number | string;
93
}
94

95
type RequestProps<M extends AnyRequestMethodName> = RequestPropsMap[M];
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
// Method without parameters
102
const initResult = await bridge.send('VKWebAppInit');
103

104
// Method with required parameters
105
const userInfo = await bridge.send('VKWebAppGetUserInfo', {
106
  user_id: 12345
107
});
108

109
// Method with optional parameters
110
const authToken = await bridge.send('VKWebAppGetAuthToken', {
111
  app_id: 51665960,
112
  scope: 'friends,photos'
113
});
114

115
// Method with custom request ID for tracking
116
const geoData = await bridge.send('VKWebAppGetGeodata', {
117
  request_id: 'my-geo-request-001'
118
});
119
```
120

121
### Event Subscription
122

123
Subscribe to events from VK client for real-time updates and responses.
124

125
```typescript { .api }
126
/**
127
 * Subscribe to events from VK client
128
 * @param listener - Event handler function
129
 */
130
subscribe(listener: VKBridgeSubscribeHandler): void;
131

132
/**
133
 * Unsubscribe from events
134
 * @param listener - Previously subscribed event handler
135
 */
136
unsubscribe(listener: VKBridgeSubscribeHandler): void;
137

138
type VKBridgeSubscribeHandler = (event: VKBridgeEvent<AnyReceiveMethodName>) => void;
139

140
interface VKBridgeEvent<M extends AnyReceiveMethodName> {
141
  detail: {
142
    type: M extends AnyRequestMethodName ? ResultResponseEventName<M> : M;
143
    data: M extends AnyReceiveMethodName ? ReceiveData<M> : never;
144
  };
145
}
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
// Subscribe to all events
152
const eventHandler = (event) => {
153
  if (!event.detail) return;
154
  
155
  const { type, data } = event.detail;
156
  console.log('Event received:', type, data);
157
  
158
  switch (type) {
159
    case 'VKWebAppInitResult':
160
      console.log('Bridge initialized successfully');
161
      break;
162
    case 'VKWebAppInitFailed':
163
      console.error('Bridge initialization failed:', data.error_data);
164
      break;
165
    case 'VKWebAppUpdateConfig':
166
      console.log('App config updated:', data);
167
      break;
168
    case 'VKWebAppLocationChanged':
169
      console.log('Location changed:', data.location);
170
      break;
171
  }
172
};
173

174
bridge.subscribe(eventHandler);
175

176
// Unsubscribe when no longer needed
177
bridge.unsubscribe(eventHandler);
178

179
// Subscribe to specific event types
180
bridge.subscribe((event) => {
181
  if (event.detail.type === 'VKWebAppAccelerometerChanged') {
182
    const { x, y, z } = event.detail.data;
183
    console.log('Accelerometer:', { x, y, z });
184
  }
185
});
186
```
187

188
### Platform Detection
189

190
Runtime environment detection for conditional functionality and platform-specific behavior.
191

192
```typescript { .api }
193
/**
194
 * Check if running in WebView (mobile app)
195
 * @returns true if running in iOS or Android WebView
196
 */
197
isWebView(): boolean;
198

199
/**
200
 * Check if running in iframe (browser)
201
 * @returns true if running in iframe
202
 */
203
isIframe(): boolean;
204

205
/**
206
 * Check if running embedded (WebView or iframe)
207
 * @returns true if running in WebView or iframe
208
 */
209
isEmbedded(): boolean;
210

211
/**
212
 * Check if running standalone (not embedded)
213
 * @returns true if NOT running in WebView or iframe
214
 */
215
isStandalone(): boolean;
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
// Platform-specific functionality
222
if (bridge.isWebView()) {
223
  // Full API available in mobile apps
224
  await bridge.send('VKWebAppTapticImpactOccurred', { style: 'medium' });
225
  await bridge.send('VKWebAppAccelerometerStart');
226
} else if (bridge.isIframe()) {
227
  // Limited API in web iframe
228
  await bridge.send('VKWebAppShare', { link: 'https://example.com' });
229
} else if (bridge.isStandalone()) {
230
  // No bridge functionality
231
  console.log('Running outside VK environment');
232
}
233

234
// Check embedded vs standalone
235
if (bridge.isEmbedded()) {
236
  // Has access to VK Bridge API
237
  await bridge.send('VKWebAppGetLaunchParams');
238
} else {
239
  // Fallback behavior for standalone
240
  console.warn('VK Bridge not available');
241
}
242
```
243

244
### Method Support Checking
245

246
Check if specific methods are available on the current platform before attempting to use them.
247

248
```typescript { .api }
249
/**
250
 * Check method support asynchronously (recommended)
251
 * @param method - VK Bridge method name to check
252
 * @returns Promise resolving to true if method is supported
253
 */
254
supportsAsync<K extends AnyRequestMethodName>(method: K): Promise<boolean>;
255

256
/**
257
 * Check method support synchronously (deprecated)
258
 * @param method - VK Bridge method name to check
259
 * @returns true if method is supported
260
 * @deprecated Use supportsAsync instead
261
 */
262
supports<K extends AnyRequestMethodName>(method: K): boolean;
263
```
264

265
**Usage Examples:**
266

267
```typescript
268
// Recommended async approach
269
const features = {
270
  camera: await bridge.supportsAsync('VKWebAppOpenCodeReader'),
271
  haptics: await bridge.supportsAsync('VKWebAppTapticImpactOccurred'),
272
  geolocation: await bridge.supportsAsync('VKWebAppGetGeodata'),
273
  payments: await bridge.supportsAsync('VKWebAppOpenPayForm')
274
};
275

276
console.log('Available features:', features);
277

278
// Conditional feature usage
279
if (await bridge.supportsAsync('VKWebAppShowImages')) {
280
  await bridge.send('VKWebAppShowImages', {
281
    images: ['https://example.com/photo.jpg']
282
  });
283
} else {
284
  // Fallback: open link
285
  window.open('https://example.com/photo.jpg', '_blank');
286
}
287

288
// Check multiple methods
289
const desiredMethods = [
290
  'VKWebAppStorageSet',
291
  'VKWebAppStorageGet', 
292
  'VKWebAppGetUserInfo'
293
] as const;
294

295
const supportedMethods = await Promise.all(
296
  desiredMethods.map(async method => ({
297
    method,
298
    supported: await bridge.supportsAsync(method)
299
  }))
300
);
301

302
console.log('Method support:', supportedMethods);
303
```
304

305
## Platform Constants
306

307
```typescript { .api }
308
/** Is the runtime environment client-side */
309
declare const IS_CLIENT_SIDE: boolean;
310

311
/** Is the runtime environment an Android WebView */
312
declare const IS_ANDROID_WEBVIEW: boolean;
313

314
/** Is the runtime environment an iOS WebView */
315
declare const IS_IOS_WEBVIEW: boolean;
316

317
/** Is the runtime environment React Native WebView */
318
declare const IS_REACT_NATIVE_WEBVIEW: boolean;
319

320
/** Is the runtime environment a browser */
321
declare const IS_WEB: boolean;
322

323
/** Is the runtime environment m.vk.com */
324
declare const IS_MVK: boolean;
325

326
/** Is the runtime environment desktop vk.com */
327
declare const IS_DESKTOP_VK: boolean;
328

329
/** Event type for current platform */
330
declare const EVENT_TYPE: string;
331

332
/** Array of methods supported on desktop platforms */
333
declare const DESKTOP_METHODS: Array<AnyRequestMethodName>;
334
```