Building Custom Capacitor Plugins to Access Native Device APIs

The Problem: Bridging the Web-Native Gap

Web applications running in Capacitor are confined to the browser's sandbox. When you need a device feature not provided by the core Capacitor library—such as a proprietary hardware sensor, a specific system setting, or a legacy native SDK—you must build a custom plugin. The primary challenge is ensuring the asynchronous communication between the JavaScript layer and the native OS (Android/iOS) does not freeze the user interface or crash due to type mismatches.

How the Capacitor Bridge Works

The Capacitor Bridge acts as a message broker. When a TypeScript method is called, Capacitor serializes the arguments into JSON and sends them to the native side. The native code processes the request and returns a JSObject (a key-value map) back to the web view. Because this process is asynchronous, the JavaScript side always receives a Promise.

Implementation Example: A Simple Device Info Plugin

This example demonstrates a plugin that retrieves a custom system value. We assume Capacitor 3+ is installed in a project with Android and iOS platforms added.

1. Define the TypeScript Interface

First, define the contract in your web code so TypeScript provides autocomplete and type safety.

// src/definitions.ts
export interface MyCustomPlugin {
  getDeviceStatus(options: { id: string }): Promise<{ status: string }>;
}

2. Android Implementation (Java/Kotlin)

In Android, create a class that extends Plugin. Use the @CapacitorPlugin annotation to register the name that the JavaScript layer will use to find the class.

// android/app/src/main/java/com/example/app/MyCustomPlugin.java
import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;nimport com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;

@CapacitorPlugin(name = "MyCustomPlugin")
public class MyCustomPlugin extends Plugin {
    @PluginMethod
    public void getDeviceStatus(PluginCall call) {
        String id = call.getString("id");
        JSObject ret = new JSObject();
        ret.put("status", "Device " + id + " is active");
        call.resolve(ret);
    }
}

3. iOS Implementation (Swift)

In iOS, use the @objc attribute to make the class and methods visible to the Capacitor bridge.

// ios/App/App/MyCustomPlugin.swift
import Foundation
import Capacitor

@objc(MyCustomPlugin)
public class MyCustomPlugin: CAPPlugin {
    @objc func getDeviceStatus(_ call: CAPPluginCall) {
        let id = call.getString("id") ?? "unknown"
        call.resolve([
            "status": "Device \(id) is active"
        ])
    }
}

4. Executing the Call

Run this code from your frontend components to trigger the native logic:

import { registerPlugin } from '@capacitor/core';
import { MyCustomPlugin } from './definitions';

const MyPlugin = registerPlugin<MyCustomPlugin>('MyCustomPlugin');

async function checkStatus() {
  try {
    const result = await MyPlugin.getDeviceStatus({ id: '123' });
    console.log(result.status); // Expected: "Device 123 is active"
  } catch (e) {
    console.error("Plugin error", e);
  }
}

Critical Engineering Constraints

Main Thread Blocking

Native methods in Capacitor run on the main UI thread by default. If you perform a heavy operation—such as a large file read or a synchronous network request—the entire web view will freeze. To prevent this, wrap heavy logic in a background thread (e.g., DispatchQueue.global().async in Swift or a new Thread in Java) and call call.resolve() once the work is complete.

Type Serialization

The bridge only supports JSON-serializable data. You cannot pass complex native objects (like a UIImage or a Context object) directly to JavaScript. You must convert these to strings, base64 encoded data, or primitive arrays before returning them in the JSObject.

Common Failures and Diagnostics

Verification Process

1. Log Verification: Use Log.d() in Android Studio or print() in Xcode to confirm the native method is actually reached when the JS function is triggered.
2. Cross-Platform Consistency: Verify that the keys returned in the JSObject (e.g., "status") are identical across both platforms to avoid conditional logic in your TypeScript code.
3. Memory Check: If your plugin uses listeners (e.g., call.setKeepAlive(true)), ensure you provide a method to remove those listeners to prevent memory leaks when the web view reloads.