cordova-plugin-yandex-mapkit

A native Cordova bridge that places Yandex MapKit behind a transparent Cordova WebView on Android and iOS. It exposes provider-focused map, camera, placemark, user-location, event, and lifecycle primitives without application-specific station or charging behavior.

Why this plugin exists

Yandex MapKit officially supports Android, iOS, and Flutter, but its published platform matrix does not currently include Apache Cordova. This community-maintained plugin was created to fill that critical integration gap, providing Cordova applications with a reusable native bridge to MapKit on Android and iOS.

The plugin is independently maintained and is not affiliated with or endorsed by Yandex.

Requirements

• Cordova Android 15 or newer.
• Android min SDK 26 or newer (required by MapKit 4.42).
• JDK 21 for Android builds (MapKit 4.42 Android artifacts use Java 21 bytecode).
• Cordova iOS 8 or newer.
• iOS deployment target 15.0 or newer.
• A MapKit Mobile SDK key created in the Yandex developer dashboard.
• A Yandex license or free-use eligibility appropriate for your application.

The package currently uses Yandex MapKit Mobile SDK 4.42.0-lite. Consult the official Android quick start, iOS quick start, SDK versions, and license conditions before shipping.

The Yandex attribution rendered by MapKit is mandatory. Do not obscure, remove, restyle, or cover it.

Install

cordova plugin add cordova-plugin-yandex-mapkit

To install a specific version:

cordova plugin add [email protected]

Add the native platform minimums to the application config.xml:

<preference name="android-minSdkVersion" value="26" />
<preference name="deployment-target" value="15.0" />

Make sure Cordova and Gradle use JDK 21 when building Android. For example, set JAVA_HOME in the build environment to a JDK 21 installation before running cordova build android.

The plugin installs com.yandex.android:maps.mobile:4.42.0-lite from Maven on Android and YandexMapsMobile through CocoaPods on iOS. No application-specific hooks, native sources, assets, or configuration files are required.

API key

The package never contains or persists an API key. Supply the key to attach at runtime from your application's build/environment configuration. Do not commit it to a public repository.

MapKit accepts only one key per application process. Calling attach with a different key after initialization returns an api_key error.

Embedded map

The map is a native sibling below the Cordova WebView. viewport, mapRect, and interactiveRects use CSS pixel coordinates measured by the web layer:

document.addEventListener('deviceready', () => {
  YandexMapKit.attach({
    apiKey: runtimeConfig.yandexMapKitApiKey,
    viewport: {
      width: window.innerWidth,
      height: window.innerHeight
    },
    mapRect: {
      x: 0,
      y: 0,
      width: window.innerWidth,
      height: window.innerHeight
    },
    interactiveRects: [
      {x: 16, y: 16, width: 64, height: 64}
    ],
    camera: {
      latitude: 55.751225,
      longitude: 37.62954,
      zoom: 14
    },
    nightMode: false,
    tiltGestures: true,
    rotateGestures: true,
    twoDMode: false
  }, console.log, console.error);
});

Call updateViewport after layout, orientation, or safe-area changes. Interactive rectangles continue receiving WebView touches; other touches inside mapRect are routed to the native map.

The plugin makes the native WebView transparent while attached. The host page must also leave the intended map region visually transparent: an opaque HTML background or element above mapRect will cover the native map. Put buttons, cards, and other controls into interactiveRects so their WebView touch handling is preserved.

attach also accepts:

• mapStyle — a Yandex MapKit style JSON string.
• nightMode — enables the SDK night palette.
• tiltGestures and rotateGestures — enable the corresponding gestures.
• twoDMode — locks the map to the SDK's 2D mode.
• poiLimit — limits displayed map POIs when supported by the SDK.

Placemarks

const pngBase64 = 'iVBORw0KGgo...';

YandexMapKit.setPlacemarks([
  {
    id: 'item-42',
    point: { latitude: 55.75, longitude: 37.62 },
    icon: {
      base64Png: pngBase64,
      cacheKey: 'station-green-pin',
      anchorX: 0.5,
      anchorY: 1,
      scale: 1
    },
    zIndex: 10,
    userData: { category: 'example' }
  }
]);

icon.cacheKey is optional. When provided, it must identify the image bytes uniquely and remain stable while only anchorX, anchorY, or scale changes. The native bridge caches the decoded image and uses the platform setIconStyle fast path for subsequent updates, avoiding per-marker PNG decoding during camera gestures. Change the key whenever base64Png changes.

setPlacemarks reconciles the whole collection. Use upsertPlacemark, removePlacemark, and clearPlacemarks for incremental updates. If no PNG is supplied, the plugin renders a neutral default dot.

userData must be JSON-serializable. It is retained only in memory and echoed with placemarkTap; it should not contain secrets or personal data.

User location

The plugin does not request location permission or collect coordinates. The host app remains responsible for permission and geolocation, then passes a coordinate explicitly:

YandexMapKit.setUserLocation({
  latitude: 55.75,
  longitude: 37.62
});

An optional icon uses the same shape as placemark icons.

Events

YandexMapKit.listenEvents((event) => {
  switch (event.type) {
    case 'mapTap':
    case 'mapLongTap':
    case 'placemarkTap':
    case 'cameraChanged':
    case 'lifecycle':
      console.log(event);
  }
}, console.error);

Only one listener is retained. Registering a new listener replaces the previous callback.

API reference

All commands are asynchronous Cordova calls. Success callbacks receive a status object with available, attached, platform, placemarkCount, and hasUserLocation.

• isAvailable(success, error) — reports whether the native bridge is available.
• attach(options, success, error) — initializes MapKit and embeds the map.
• updateViewport(options, success, error) — updates viewport, mapRect, interactiveRects, and map display options after layout changes.
• detach(success, error) — removes the native map and restores the WebView.
• setCamera(camera, success, error) — moves the camera; optional duration performs a smooth animation.
• setPlacemarks(items, success, error) — reconciles the complete placemark collection.
• upsertPlacemark(item, success, error) — creates or updates one placemark.
• removePlacemark(id, success, error) — removes one placemark.
• clearPlacemarks(success, error) — removes every placemark.
• setUserLocation(location, success, error) — displays a host-supplied user coordinate and optional icon.
• clearUserLocation(success, error) — removes the user-location marker.
• setTrafficVisible(visible, success, error) — enables or disables the native MapKit traffic layer.
• listenEvents(success, error) — subscribes to map, placemark, camera, and lifecycle events; a later call replaces the current listener.

TypeScript declarations are published through the package's types field:

import YandexMapKit = require('cordova-plugin-yandex-mapkit');

Cordova also exposes the same instance globally as window.YandexMapKit.

Lifecycle

The plugin automatically starts and stops MapKit during Cordova pause/resume and disposes the native view on application termination. Consumers may use the emitted lifecycle events to refresh their own application state; no manual native lifecycle forwarding is required.

Call detach when leaving a screen that will no longer display the map.

Errors

Errors are objects with a stable code and a sanitized message:

• api_key — missing key or an attempt to change the initialized key.
• invalid_argument — malformed viewport, camera, placemark, or icon.
• unavailable — the native map is not attached or the host is unsupported.
• native_error — an unexpected native SDK error.

Browser

This is a native-only plugin. Cordova browser builds do not receive a map implementation; applications should provide their own browser adapter or fallback UI.

Troubleshooting

• api_key: provide a non-empty Mobile SDK key. A different key cannot be applied after MapKit has been initialized in the same application process.
• invalid_argument: verify positive viewport/map dimensions, finite coordinates, non-empty placemark IDs, and valid PNG base64 data.
• unavailable: wait for deviceready, run on Android or iOS rather than the Cordova browser platform, and attach before invoking map operations.
• native_error: inspect native Android Logcat or the Xcode console; error messages are sanitized and never contain the API key.
• Blank map area: ensure the key is valid for Yandex MapKit Mobile SDK, the device has network access, and no opaque HTML element covers mapRect.
• Gestures do not reach the map: make sure the point is inside mapRect and outside every interactiveRects entry.
• Android build fails on bytecode compatibility: build with JDK 21.
• iOS dependency resolution fails: verify CocoaPods, Cordova iOS 8+, deployment target 15+, and access to the CocoaPods CDN.

Development

npm test
npm run audit:package
npm pack --dry-run

License

Apache-2.0. Yandex MapKit itself is governed by Yandex's separate terms.