0
# Launch Parameters Parsing
1

2
Utility function for parsing VK Mini App launch parameters from URL search params with type-safe extraction and validation of VK-specific parameters.
3

4
## Capabilities
5

6
### Parse URL Search Parameters
7

8
Extract and parse VK launch parameters from URL search string with proper type conversion and validation.
9

10
```typescript { .api }
11
/**
12
 * Parse URL search params to extract VK Mini App launch parameters
13
 * Converts string values to appropriate types with validation
14
 * @param searchParams - URL search params string (e.g., window.location.search)
15
 * @returns Parsed launch parameters object with type-safe values
16
 */
17
function parseURLSearchParamsForGetLaunchParams(
18
  searchParams: string
19
): Partial<LaunchParams>;
20

21
interface LaunchParams extends GetLaunchParamsResponse {
22
  /** Chat ID if launched from chat context */
23
  vk_chat_id: string;
24
  /** Whether app is recommended (0 or 1) */
25
  vk_is_recommended: number;
26
  /** Profile ID context */
27
  vk_profile_id: number;
28
  /** Whether profile button should be shown (0 or 1) */
29
  vk_has_profile_button: number;
30
  /** Testing group ID if in testing mode */
31
  vk_testing_group_id: number;
32
  /** ODR (On-Demand Resources) enabled flag */
33
  odr_enabled: undefined | 1;
34
}
35

36
interface GetLaunchParamsResponse {
37
  /** User ID who launched the app */
38
  vk_user_id: number;
39
  /** VK application ID */
40
  vk_app_id: number;
41
  /** Community ID if launched from community */
42
  vk_group_id?: number;
43
  /** Platform identifier */
44
  vk_platform: EGetLaunchParamsResponsePlatforms;
45
  /** User's language preference */
46
  vk_language?: EGetLaunchParamsResponseLanguages;
47
  /** User's role in community context */
48
  vk_viewer_group_role?: EGetLaunchParamsResponseGroupRole;
49
  /** Whether user has installed the app (0 or 1) */
50
  vk_is_app_user?: 0 | 1;
51
  /** Whether notifications are enabled (0 or 1) */
52
  vk_are_notifications_enabled?: 0 | 1;
53
  /** Whether user added app to favorites (0 or 1) */
54
  vk_is_favorite?: 0 | 1;
55
  /** Launch timestamp */
56
  vk_ts: number;
57
  /** Referrer information */
58
  vk_ref?: string;
59
  /** Access token settings */
60
  vk_access_token_settings?: string;
61
  /** Cryptographic signature for verification */
62
  sign: string;
63
}
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { parseURLSearchParamsForGetLaunchParams } from "@vkontakte/vk-bridge";
70

71
// Parse current page URL parameters
72
const launchParams = parseURLSearchParamsForGetLaunchParams(window.location.search);
73

74
console.log('User ID:', launchParams.vk_user_id);
75
console.log('App ID:', launchParams.vk_app_id);
76
console.log('Platform:', launchParams.vk_platform);
77
console.log('Language:', launchParams.vk_language);
78

79
// Example URL:
80
// https://example.com/?vk_user_id=12345&vk_app_id=51665960&vk_platform=desktop_web&vk_language=en&sign=abc123
81

82
// Handle different launch contexts
83
if (launchParams.vk_group_id) {
84
  console.log('Launched from community:', launchParams.vk_group_id);
85
  console.log('User role:', launchParams.vk_viewer_group_role);
86
  showCommunityInterface(launchParams.vk_group_id);
87
}
88

89
if (launchParams.vk_chat_id) {
90
  console.log('Launched from chat:', launchParams.vk_chat_id);
91
  showChatInterface(launchParams.vk_chat_id);
92
}
93

94
if (launchParams.vk_profile_id) {
95
  console.log('Profile context:', launchParams.vk_profile_id);
96
  showProfileInterface(launchParams.vk_profile_id);
97
}
98

99
// User status checks
100
if (launchParams.vk_is_app_user === 1) {
101
  console.log('User has installed the app');
102
  showAdvancedFeatures();
103
} else {
104
  console.log('New user - show onboarding');
105
  showOnboarding();
106
}
107

108
if (launchParams.vk_is_favorite === 1) {
109
  console.log('App is in user favorites');
110
} else {
111
  console.log('Suggest adding to favorites');
112
  suggestAddToFavorites();
113
}
114
```
115

116
### Parameter Type Conversion
117

118
The parser automatically converts string values to appropriate types with validation.
119

120
```typescript { .api }
121
interface ParameterConversions {
122
  /** String to number conversion for numeric parameters */
123
  vk_user_id: number;
124
  vk_app_id: number;
125
  vk_group_id: number;
126
  vk_ts: number;
127
  vk_profile_id: number;
128
  vk_testing_group_id: number;
129
  vk_is_recommended: number;
130
  vk_has_profile_button: number;
131
  
132
  /** String to 0|1 conversion with validation */
133
  vk_is_app_user: 0 | 1;
134
  vk_are_notifications_enabled: 0 | 1;
135
  vk_is_favorite: 0 | 1;
136
  
137
  /** String values preserved as-is */
138
  sign: string;
139
  vk_chat_id: string;
140
  vk_ref: string;
141
  vk_access_token_settings: string;
142
  
143
  /** Enum validation for specific values */
144
  vk_language: EGetLaunchParamsResponseLanguages;
145
  vk_platform: EGetLaunchParamsResponsePlatforms;
146
  vk_viewer_group_role: EGetLaunchParamsResponseGroupRole;
147
  
148
  /** Special handling for ODR flag */
149
  odr_enabled: undefined | 1;
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
// The parser handles type conversion automatically
157
const params = parseURLSearchParamsForGetLaunchParams(
158
  '?vk_user_id=12345&vk_is_app_user=1&vk_language=en&odr_enabled=1'
159
);
160

161
// Types are correctly converted:
162
console.log(typeof params.vk_user_id);        // 'number'
163
console.log(typeof params.vk_is_app_user);    // 'number' (0 or 1)
164
console.log(typeof params.vk_language);       // 'string' (validated enum)
165
console.log(typeof params.odr_enabled);       // 'number' (1) or 'undefined'
166

167
// Invalid values are filtered out:
168
const invalidParams = parseURLSearchParamsForGetLaunchParams(
169
  '?vk_user_id=invalid&vk_language=invalid_lang&vk_is_app_user=maybe'
170
);
171

172
console.log(invalidParams.vk_user_id);        // undefined (invalid number)
173
console.log(invalidParams.vk_language);       // undefined (invalid enum)
174
console.log(invalidParams.vk_is_app_user);    // undefined (invalid 0|1)
175
```
176

177
### Supported Parameters
178

179
Complete list of parameters recognized and parsed by the function:
180

181
```typescript { .api }
182
enum SupportedParameters {
183
  // Numeric parameters
184
  'vk_ts' = 'timestamp',
185
  'vk_is_recommended' = 'recommendation_flag',
186
  'vk_profile_id' = 'profile_context',
187
  'vk_has_profile_button' = 'profile_button_flag', 
188
  'vk_testing_group_id' = 'testing_group',
189
  'vk_user_id' = 'user_identifier',
190
  'vk_app_id' = 'application_identifier',
191
  'vk_group_id' = 'community_identifier',
192
  
193
  // String parameters
194
  'sign' = 'cryptographic_signature',
195
  'vk_chat_id' = 'chat_context',
196
  'vk_ref' = 'referrer_information',
197
  'vk_access_token_settings' = 'token_permissions',
198
  
199
  // Special flag
200
  'odr_enabled' = 'on_demand_resources',
201
  
202
  // Toggle state parameters (0|1)
203
  'vk_is_app_user' = 'app_installation_status',
204
  'vk_are_notifications_enabled' = 'notification_permissions',
205
  'vk_is_favorite' = 'favorite_status',
206
  
207
  // Enum parameters with validation
208
  'vk_language' = 'user_language_preference',
209
  'vk_viewer_group_role' = 'community_role',
210
  'vk_platform' = 'client_platform'
211
}
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
// Example with all possible parameters
218
const fullUrl = `
219
?vk_user_id=12345
220
&vk_app_id=51665960
221
&vk_group_id=123456789
222
&vk_platform=desktop_web
223
&vk_language=en
224
&vk_viewer_group_role=admin
225
&vk_is_app_user=1
226
&vk_are_notifications_enabled=1
227
&vk_is_favorite=0
228
&vk_ts=1640995200
229
&vk_ref=menu
230
&vk_access_token_settings=friends,photos
231
&sign=abc123def456
232
&vk_chat_id=2000000001
233
&vk_profile_id=67890
234
&vk_has_profile_button=1
235
&vk_testing_group_id=999888777
236
&vk_is_recommended=1
237
&odr_enabled=1
238
`.replace(/\s+/g, '');
239

240
const allParams = parseURLSearchParamsForGetLaunchParams(fullUrl);
241

242
// All parameters are properly typed and converted
243
console.log('Complete launch context:', allParams);
244
```
245

246
### Error Handling and Validation
247

248
The parser includes built-in error handling and validation:
249

250
```typescript { .api }
251
interface ValidationBehavior {
252
  /** Invalid numeric values become undefined */
253
  numericValidation: 'undefined_on_invalid';
254
  
255
  /** Invalid enum values become undefined */
256
  enumValidation: 'undefined_on_invalid';
257
  
258
  /** Invalid toggle states (not 0 or 1) become undefined */
259
  toggleValidation: 'undefined_on_invalid';
260
  
261
  /** Parsing errors are caught and logged */
262
  errorHandling: 'warn_and_continue';
263
}
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
// Robust parameter parsing with fallbacks
270
function parseLaunchParamsWithFallbacks(searchParams: string) {
271
  try {
272
    const params = parseURLSearchParamsForGetLaunchParams(searchParams);
273
    
274
    // Provide fallbacks for critical parameters
275
    return {
276
      userId: params.vk_user_id || 0,
277
      appId: params.vk_app_id || 0,
278
      platform: params.vk_platform || EGetLaunchParamsResponsePlatforms.DESKTOP_WEB,
279
      language: params.vk_language || EGetLaunchParamsResponseLanguages.EN,
280
      isAppUser: params.vk_is_app_user === 1,
281
      notificationsEnabled: params.vk_are_notifications_enabled === 1,
282
      isFavorite: params.vk_is_favorite === 1,
283
      timestamp: params.vk_ts || Date.now() / 1000,
284
      signature: params.sign || '',
285
      
286
      // Optional context
287
      groupId: params.vk_group_id,
288
      chatId: params.vk_chat_id,
289
      profileId: params.vk_profile_id,
290
      viewerRole: params.vk_viewer_group_role,
291
      referrer: params.vk_ref,
292
      tokenSettings: params.vk_access_token_settings,
293
      
294
      // Flags
295
      isRecommended: params.vk_is_recommended === 1,
296
      hasProfileButton: params.vk_has_profile_button === 1,
297
      testingGroupId: params.vk_testing_group_id,
298
      odrEnabled: params.odr_enabled === 1
299
    };
300
  } catch (error) {
301
    console.error('Failed to parse launch parameters:', error);
302
    return null;
303
  }
304
}
305

306
// Usage with validation
307
const launchContext = parseLaunchParamsWithFallbacks(window.location.search);
308

309
if (!launchContext || !launchContext.userId || !launchContext.appId) {
310
  console.error('Invalid launch parameters');
311
  showError('Invalid app launch context');
312
} else {
313
  console.log('Valid launch context:', launchContext);
314
  initializeApp(launchContext);
315
}
316
```
317

318
### Integration with Bridge API
319

320
Combining parsed parameters with bridge API calls:
321

322
```typescript
323
// Complete launch parameter handling
324
async function handleAppLaunch() {
325
  // 1. Parse URL parameters
326
  const urlParams = parseURLSearchParamsForGetLaunchParams(window.location.search);
327
  
328
  // 2. Initialize bridge
329
  await bridge.send('VKWebAppInit');
330
  
331
  // 3. Get official launch parameters from bridge
332
  const bridgeParams = await bridge.send('VKWebAppGetLaunchParams');
333
  
334
  // 4. Compare and validate
335
  const isValidLaunch = validateLaunchParameters(urlParams, bridgeParams);
336
  
337
  if (!isValidLaunch) {
338
    console.error('Launch parameter mismatch');
339
    return;
340
  }
341
  
342
  // 5. Use merged context
343
  const launchContext = {
344
    ...urlParams,
345
    ...bridgeParams,
346
    // Additional parsed parameters from URL
347
    chatId: urlParams.vk_chat_id,
348
    profileId: urlParams.vk_profile_id,
349
    isRecommended: urlParams.vk_is_recommended === 1,
350
    odrEnabled: urlParams.odr_enabled === 1
351
  };
352
  
353
  return launchContext;
354
}
355

356
function validateLaunchParameters(urlParams: Partial<LaunchParams>, bridgeParams: GetLaunchParamsResponse): boolean {
357
  // Critical parameters must match
358
  const criticalFields = ['vk_user_id', 'vk_app_id', 'vk_platform', 'sign'] as const;
359
  
360
  return criticalFields.every(field => {
361
    const urlValue = urlParams[field];
362
    const bridgeValue = bridgeParams[field];
363
    
364
    if (urlValue !== undefined && bridgeValue !== undefined) {
365
      return urlValue === bridgeValue;
366
    }
367
    
368
    return true; // Allow if one is undefined
369
  });
370
}
371

372
// Initialize app with launch context
373
handleAppLaunch().then(context => {
374
  if (context) {
375
    startApplication(context);
376
  } else {
377
    showError('Failed to initialize app context');
378
  }
379
});
380
```