CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-vkontakte--vk-bridge

Bridge library for VK Mini Apps to communicate with VK clients across iOS, Android, and Web platforms

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

VK Bridge

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.

Package Information

  • Package Name: @vkontakte/vk-bridge
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @vkontakte/vk-bridge

Core Imports

import bridge from "@vkontakte/vk-bridge";

For CommonJS:

const bridge = require("@vkontakte/vk-bridge");

Additional imports:

import bridge, { applyMiddleware, parseURLSearchParamsForGetLaunchParams } from "@vkontakte/vk-bridge";

For browser usage:

<script src="https://unpkg.com/@vkontakte/vk-bridge/dist/browser.min.js"></script>
<script>
  // Available as global vkBridge
  vkBridge.send('VKWebAppInit');
</script>

Basic Usage

import bridge from "@vkontakte/vk-bridge";

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

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

// Subscribe to events from VK client
bridge.subscribe((event) => {
  if (!event.detail) return;
  
  const { type, data } = event.detail;
  console.log('Received event:', type, data);
  
  if (type === 'VKWebAppUpdateConfig') {
    console.log('App config updated:', data);
  }
});

// Check platform capabilities
const canShowImages = await bridge.supportsAsync('VKWebAppShowImages');
if (canShowImages) {
  await bridge.send('VKWebAppShowImages', {
    images: ['https://example.com/photo1.jpg']
  });
}

Architecture

VK Bridge is built around several key components:

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

Capabilities

Core Bridge Interface

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

interface VKBridge {
  /** Send event to VK client and receive response */
  send: <K extends AnyRequestMethodName>(
    method: K,
    props?: RequestProps<K> & RequestIdProp
  ) => Promise<K extends AnyReceiveMethodName ? ReceiveData<K> : void>;
  
  /** Subscribe to events from VK client */
  subscribe: (listener: VKBridgeSubscribeHandler) => void;
  
  /** Unsubscribe from events */
  unsubscribe: (listener: VKBridgeSubscribeHandler) => void;
  
  /** Check method support asynchronously */
  supportsAsync: <K extends AnyRequestMethodName>(method: K) => Promise<boolean>;
  
  /** Check if running in WebView */
  isWebView: () => boolean;
  
  /** Check if running in iframe */
  isIframe: () => boolean;
  
  /** Check if running embedded (WebView or iframe) */
  isEmbedded: () => boolean;
  
  /** Check if running standalone */
  isStandalone: () => boolean;
}

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

interface RequestIdProp {
  request_id?: number | string;
}

Core Bridge Interface

Authentication & Authorization

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

// Get user access token
function send(method: 'VKWebAppGetAuthToken', props: {
  app_id: number;
  scope: PersonalAuthScope | string;
}): Promise<{
  access_token: string;
  scope: string;
  expires?: number;
}>;

// Get community access token
function send(method: 'VKWebAppGetCommunityToken', props: {
  app_id: number;
  group_id: number;
  scope: CommunityAuthScope | string;
}): Promise<{
  access_token: string;
  scope: string;
}>;

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

Authentication & Authorization

User Data & Profile

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

// Get user information
function send(method: 'VKWebAppGetUserInfo', props?: {
  user_id?: number;
  user_ids?: string;
}): Promise<UserInfo>;

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

interface UserInfo {
  id: number;
  first_name: string;
  last_name: string;
  photo_100: string;
  photo_200: string;
  is_closed: boolean;
  can_access_closed: boolean;
}

User Data & Profile

Application Lifecycle

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

// Initialize bridge
function send(method: 'VKWebAppInit'): Promise<{ result: true }>;

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

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

interface GetLaunchParamsResponse {
  vk_user_id: number;
  vk_app_id: number;
  vk_platform: EGetLaunchParamsResponsePlatforms;
  vk_language: EGetLaunchParamsResponseLanguages;
  vk_is_app_user: 0 | 1;
  vk_are_notifications_enabled: 0 | 1;
  sign: string;
}

Application Lifecycle

UI & Display Control

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

// Set appearance and status bar
function send(method: 'VKWebAppSetViewSettings', props: {
  status_bar_style: AppearanceType;
  action_bar_color?: 'none' | string;
  navigation_bar_color?: string;
}): Promise<{ result: true }>;

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

type AppearanceType = 'light' | 'dark';

UI & Display Control

Device Features & Sensors

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

// Haptic feedback
function send(method: 'VKWebAppTapticImpactOccurred', props: {
  style: TapticVibrationPowerType;
}): Promise<{ result: true }>;

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

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

// Open contacts picker
function send(method: 'VKWebAppOpenContacts'): Promise<{
  phone?: string;
  first_name?: string;
  last_name?: string;
}>;

type TapticVibrationPowerType = 'light' | 'medium' | 'heavy';

Device Features & Sensors

Social Features

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

// Share content
function send(method: 'VKWebAppShare', props?: {
  link?: string;
}): Promise<LinkShareResult[]>;

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

// Show wall post dialog
function send(method: 'VKWebAppShowWallPostBox', props: WallPostRequestOptions): Promise<{
  post_id: number | string;
}>;

Social Features

Storage & Data Management

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

// Set storage value
function send(method: 'VKWebAppStorageSet', props: {
  key: string;
  value: string;
}): Promise<{ result: true }>;

// Get storage values
function send(method: 'VKWebAppStorageGet', props: {
  keys: string[];
}): Promise<{
  keys: Array<{ key: string; value: string }>;
}>;

Storage & Data Management

Payments & Commerce

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

// Open payment form
function send(method: 'VKWebAppOpenPayForm', props: VKPayProps<VKPayActionType>): Promise<
  TransactionResult | { result: TransactionResult }
>;

interface VKPayProps<T extends VKPayActionType> {
  app_id: number;
  action: T;
  params: VKPayActionParamsMap[T];
}

Payments & Commerce

Advertising & Monetization

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

// Show banner ad
function send(method: 'VKWebAppShowBannerAd', props: ShowBannerAdRequest): Promise<VKWebAppShowBannerAdResponse>;

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

enum EAdsFormats {
  REWARD = 'reward',
  INTERSTITIAL = 'interstitial'
}

Advertising & Monetization

Middleware System

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

function applyMiddleware(
  ...middlewares: Array<Middleware | undefined | null>
): (bridge: VKBridge) => VKBridge;

type Middleware<S extends VKBridgeSend = VKBridgeSend> = (
  api: MiddlewareAPI<S>
) => (next: S) => S;

interface MiddlewareAPI<S extends VKBridgeSend = VKBridgeSend> {
  send: S;
  subscribe(listener: VKBridgeSubscribeHandler): void;
}

Middleware System

QR & Barcode Scanning

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

// Open QR code scanner
function send(method: 'VKWebAppOpenCodeReader'): Promise<{
  code_data: string;
  code_type?: string;
}>;

// Alternative QR scanner
function send(method: 'VKWebAppOpenQR'): Promise<{
  qr_data: string;
}>;

QR & Barcode Scanning

Geolocation Services

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

// Get device location
function send(method: 'VKWebAppGetGeodata'): Promise<{
  lat: number;
  long: number;
  accuracy?: number;
}>;

// Set app location context
function send(method: 'VKWebAppSetLocation', props: {
  location: string;
}): Promise<{ result: true }>;

Geolocation Services

Launch Parameters Parsing

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

function parseURLSearchParamsForGetLaunchParams(
  searchParams: string
): Partial<LaunchParams>;

interface LaunchParams extends GetLaunchParamsResponse {
  vk_chat_id: string;
  vk_is_recommended: number;
  vk_profile_id: number;
  vk_has_profile_button: number;
  vk_testing_group_id: number;
  odr_enabled: undefined | 1;
}

Launch Parameters Parsing

Types

Core Event Types

interface VKBridgeEvent<M extends AnyReceiveMethodName> {
  detail: {
    type: M extends AnyRequestMethodName ? ResultResponseEventName<M> : M;
    data: M extends AnyReceiveMethodName ? ReceiveData<M> : never;
  };
}

interface VKBridgeEventBase<Type extends string, Data> {
  detail: {
    type: Type;
    data: Data;
  };
}

Error Types

type ErrorData = 
  | {
      error_type: 'client_error';
      error_data: ErrorDataClientError;
      request_id?: number | string;
    }
  | {
      error_type: 'api_error';
      error_data: ErrorDataAPIError;
      request_id?: number | string;
    }
  | {
      error_type: 'auth_error';
      error_data: ErrorDataAuthError;
      request_id?: number | string;
    };

interface ErrorDataClientError {
  error_code: number;
  error_reason: string;
  error_description?: string;
}

interface ErrorDataAPIError {
  error_code: number;
  error_msg: string;
  request_params: string[];
}

interface ErrorDataAuthError {
  error_code: number;
  error_reason: string;
  error_description?: string[];
}

Method Name Types

type AnyRequestMethodName = keyof RequestPropsMap;
type AnyReceiveMethodName = keyof ReceiveDataMap;
type AnyRequestOnlyMethodName = Exclude<AnyRequestMethodName, AnyReceiveMethodName>;
type AnyReceiveOnlyMethodName = Exclude<AnyReceiveMethodName, AnyRequestMethodName>;
type AnyIOMethodName = AnyRequestMethodName & AnyReceiveMethodName;

docs

advertising-monetization.md

application-lifecycle.md

authentication.md

core-bridge.md

device-features.md

geolocation.md

index.md

launch-parameters.md

middleware.md

payments-commerce.md

qr-barcode-scanning.md

social-features.md

storage-data.md

ui-display.md

user-data.md

tile.json