cordova-plugin-appmetrica

A small Cordova bridge for the current AppMetrica Android and iOS SDKs.

Why this plugin exists

AppMetrica officially provides native Android and iOS SDKs and plugins for Unity, Flutter, and React Native, 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 one reusable bridge to the current native AppMetrica SDKs on Android and iOS.

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

Requirements

• Cordova Android 15 or newer
• Cordova iOS 8 or newer
• Android SDK requirements inherited from AppMetrica Android SDK 8.4.1
• iOS 15 or newer

The plugin uses AppMetrica Android SDK 8.4.1 and AppMetrica iOS SDK 6.5.0.

Installation

cordova plugin add cordova-plugin-appmetrica

To install a specific version:

cordova plugin add [email protected]

For iOS, declare the supported deployment target in the consuming application's config.xml:

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

Then regenerate or prepare the iOS platform before building.

The native SDK dependencies are installed by the plugin:

• Android: AppMetrica SDK from Maven.
• iOS: AppMetrica SDK through Swift Package Manager.

No files from another application, custom hooks, or manual native source copying are required.

API key

Create an application in AppMetrica and use its application API key. Inject the key through the consuming application's build or runtime configuration; the plugin never bundles or persists a key.

An application key is shipped to client devices and therefore cannot be treated like a server-side secret. Do not publish keys in source repositories, logs, examples, or issue reports.

Quick start

Wait for Cordova's deviceready event before calling the plugin:

document.addEventListener('deviceready', () => {
  appMetrica.activate(
    {
      apiKey: runtimeConfiguration.appMetricaApiKey,
      locationTracking: false,
      sessionTimeout: 30
    },
    () => {
      appMetrica.reportEvent('screen_open', {screen: 'home'});
    },
    category => {
      console.warn('AppMetrica activation failed', category);
    }
  );
});

Events reported before activation are queued in memory. The queue is limited to the latest 100 events. Events are dropped after a failed activation until the application calls activate again.

Only JSON objects are accepted as event parameters. Unsupported payload values are reported as events without parameters.

API

activate(configuration, onSuccess?, onError?)

Activates the native SDK. Concurrent activation calls are coalesced and all registered callbacks are settled by the same native activation.

Configuration:

• apiKey — required non-empty AppMetrica application key.
• locationTracking — optional; disabled by default by current native SDKs.
• sessionTimeout — optional session timeout in seconds; values below 10 are clamped to 10.

Errors are intentionally returned as stable categories and never include the API key.

reportEvent(eventName, payload?)

Reports or queues an event. Returns false for an invalid event name or when the bridge is in an error state; otherwise returns true.

getStatus()

Returns the current JavaScript bridge state and in-memory queue length.

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

import appMetrica = require('cordova-plugin-appmetrica');

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

Lifecycle and permissions

The native AppMetrica SDKs handle application lifecycle events; the host application does not need to forward pause or resume calls.

locationTracking defaults to false. If the consuming application enables location tracking, it remains responsible for platform permissions, iOS usage descriptions, user consent, and store-policy compliance. This plugin does not request location permission.

Troubleshooting

• api_key_missing: activate received an empty or missing key.
• native_error: the native SDK could not be activated. Confirm the key, platform network access, and native dependency installation.
• Events remain queued: wait for the activation success callback and inspect appMetrica.getStatus().
• appMetrica is undefined: call it only after deviceready and confirm the plugin appears in cordova plugin list.
• iOS build cannot resolve AppMetrica: verify Cordova iOS 8+, iOS deployment target 15+, and network access for Swift Package Manager.

Privacy

The plugin does not define a consent flow or select events for you. The consuming application is responsible for lawful data collection, consent, retention, and AppMetrica account configuration.

Review the current AppMetrica documentation before releasing an application.

Development

npm test
npm run check
npm pack --json

Inspect the generated tarball before every release. Never publish application configuration, credentials, signing material, or production data.

License

Apache-2.0. AppMetrica SDKs are distributed under their own terms.