or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bridge-runtime.mdbuiltin-plugins.mdconfig-utilities.mddata-exchange.mdindex.mdplugin-calls.mdplugin-development.md
tile.json

tessl/npm-capacitor--android

Android platform integration package providing native Android runtime and plugin development framework for Capacitor apps

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@capacitor/android@7.4.x

To install, run

npx @tessl/cli install tessl/npm-capacitor--android@7.4.0

index.mddocs/

Capacitor Android

Capacitor Android provides the native Android platform integration for Capacitor applications. This package enables web applications to run natively on Android devices by providing the core Android runtime, bridge infrastructure, and comprehensive plugin development framework. It includes native Java classes, Android build configurations, and JavaScript bridge code that facilitates seamless communication between web and native Android APIs.

Package Information

  • Package Name: @capacitor/android
  • Package Type: npm
  • Language: Java (Android) with JavaScript bridge
  • Installation: npm install @capacitor/android
  • Android SDK: Requires Android SDK 23+ (API Level 23+)

Core Imports

This package is primarily consumed by the Capacitor CLI and build system. Plugin developers work with the native Java APIs:

import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginResult;
import com.getcapacitor.JSObject;
import com.getcapacitor.annotation.CapacitorPlugin;

For app developers extending the main activity:

import com.getcapacitor.BridgeActivity;
import com.getcapacitor.Bridge;

Basic Usage

Creating an Android Plugin

import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginResult;
import com.getcapacitor.JSObject;
import com.getcapacitor.annotation.CapacitorPlugin;
import com.getcapacitor.annotation.PluginMethod;

@CapacitorPlugin(name = "MyPlugin")
public class MyPlugin extends Plugin {
    
    @PluginMethod
    public void echo(PluginCall call) {
        String value = call.getString("value");
        
        JSObject result = new JSObject();
        result.put("value", value);
        
        call.resolve(result);
    }
}

Extending BridgeActivity

import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        // Initialize your plugins
        this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
            add(MyPlugin.class);
        }});
    }
}

Architecture

Capacitor Android is built around several key components:

  • Bridge System: Core communication layer between JavaScript and native Android code
  • Plugin Framework: Base classes and utilities for creating native Android plugins
  • Activity Management: Android activity lifecycle integration with Capacitor apps
  • Data Exchange: Type-safe JSON object handling between web and native layers
  • JavaScript Bridge: Native bridge code injected into the WebView for seamless communication
  • Configuration System: Runtime configuration management for Capacitor apps
  • Built-in Plugins: Core functionality like HTTP requests and cookie management

Capabilities

Bridge and Runtime System

Core bridge infrastructure that enables communication between web and native layers, manages plugin lifecycle, and provides the foundational runtime for Capacitor apps.

public class Bridge {
    public static class Builder {
        public Builder(AppCompatActivity activity);
        public Builder(Fragment fragment);
        public Builder setInstanceState(Bundle savedInstanceState);
        public Builder addPlugins(List<Class<? extends Plugin>> plugins);
        public Builder addPlugin(Class<? extends Plugin> plugin);
        public Builder addPluginInstance(Plugin plugin);
        public Builder addPluginInstances(List<Plugin> plugins);
        public Builder setConfig(CapConfig config);
        public Builder setRouteProcessor(RouteProcessor routeProcessor);
        public Builder setServerPath(ServerPath serverPath);
        public Bridge create();
    }
}

public class BridgeActivity extends AppCompatActivity {
    protected Bridge bridge;
    protected boolean keepRunning;
    protected CapConfig config;
    protected List<Class<? extends Plugin>> initialPlugins;
    protected final Bridge.Builder bridgeBuilder;
    
    protected void load();
    public void registerPlugin(Class<? extends Plugin> plugin);
    public void registerPlugins(List<Class<? extends Plugin>> plugins);
    public Bridge getBridge();
}

Bridge and Runtime

Plugin Development Framework

Base classes, annotations, and utilities for developing native Android plugins that integrate with Capacitor's bridge system.

@Retention(RetentionPolicy.RUNTIME)
public @interface CapacitorPlugin {
    String name() default "";
    int[] requestCodes() default {};
    Permission[] permissions() default {};
}

public class Plugin {
    protected Bridge bridge;
    protected AppCompatActivity activity;
    protected Context context;
    
    public void load();
    public void handleOnActivityResult(int requestCode, int resultCode, Intent data);
    public void handleRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults);
}

Plugin Development

Plugin Call System

Classes and interfaces for handling method calls from the web layer to native Android plugins, including parameter passing and response handling.

public class PluginCall {
    public static final String CALLBACK_ID_DANGLING = "-1";
    
    public void successCallback(PluginResult successResult);
    public void errorCallback(String msg);
    public void resolve(JSObject data);
    public void resolve();
    public void reject(String msg, String code, Exception ex, JSObject data);
    public void reject(String msg, Exception ex, JSObject data);
    public void reject(String msg, String code, JSObject data);
    public void reject(String msg, String code, Exception ex);
    public void reject(String msg, JSObject data);
    public void reject(String msg, Exception ex);
    public void reject(String msg, String code);
    public void reject(String msg);
    public void unimplemented();
    public void unimplemented(String msg);
    public void unavailable();
    public void unavailable(String msg);
    
    public String getPluginId();
    public String getCallbackId();
    public JSObject getData();
    public String getMethodName();
    
    public String getString(String name);
    public String getString(String name, String defaultValue);
    public Integer getInt(String name);
    public Integer getInt(String name, Integer defaultValue);
    public Long getLong(String name);
    public Long getLong(String name, Long defaultValue);
    public Float getFloat(String name);
    public Float getFloat(String name, Float defaultValue);
    public Double getDouble(String name);
    public Double getDouble(String name, Double defaultValue);
    public Boolean getBoolean(String name);
    public Boolean getBoolean(String name, Boolean defaultValue);
    public JSObject getObject(String name);
    public JSObject getObject(String name, JSObject defaultValue);
    public JSArray getArray(String name);
    public JSArray getArray(String name, JSArray defaultValue);
    
    public void setKeepAlive(Boolean keepAlive);
    public boolean isKeptAlive();
}

public class PluginResult {
    public PluginResult();
    public PluginResult(JSObject data);
}

Plugin Calls

Data Exchange Objects

Type-safe JSON object and array classes for exchanging data between JavaScript and native Android code.

public class JSObject extends JSONObject {
    public JSObject();
    public JSObject(String json) throws JSONException;
    
    public JSObject put(String key, Object value);
    public String getString(String key, String defaultValue);
    public Integer getInteger(String key);
    public Boolean getBoolean(String key, Boolean defaultValue);
    public JSObject getJSObject(String key);
    public JSArray getJSArray(String key);
    
    public static JSObject fromJSONObject(JSONObject obj) throws JSONException;
}

public class JSArray extends JSONArray {
    public JSArray();
    public JSArray(JSONArray array) throws JSONException;
    public JSObject getJSObject(int index) throws JSONException;
}

Data Exchange

Configuration and Utilities

Configuration management, logging, file utilities, and other helper classes for Android plugin development.

public class CapConfig {
    public static CapConfig loadDefault(Context context);
    public JSONObject getPluginConfiguration(String pluginName);
    public String getString(String key, String defaultValue);
}

public class Logger {
    public static void debug(String msg);
    public static void info(String msg);
    public static void warn(String msg);
    public static void error(String msg, Exception ex);
}

public enum PermissionState {
    GRANTED, DENIED, PROMPT, PROMPT_WITH_RATIONALE
}

Configuration and Utilities

Built-in Android Plugins

Core plugins that provide essential functionality like HTTP requests, cookie management, and WebView control.

@CapacitorPlugin(name = "CapacitorHttp")
public class CapacitorHttp extends Plugin {
    @PluginMethod
    public void request(PluginCall call);
    @PluginMethod
    public void get(PluginCall call);
    @PluginMethod
    public void post(PluginCall call);
    @PluginMethod
    public void put(PluginCall call);
    @PluginMethod
    public void patch(PluginCall call);
    @PluginMethod
    public void delete(PluginCall call);
}

@CapacitorPlugin(name = "CapacitorCookies")
public class CapacitorCookies extends Plugin {
    @PluginMethod
    public void getCookies(PluginCall call);
    @PluginMethod
    public void setCookie(PluginCall call);
    @PluginMethod
    public void deleteCookie(PluginCall call);
    @PluginMethod
    public void clearCookies(PluginCall call);
    @PluginMethod
    public void clearAllCookies(PluginCall call);
}

@CapacitorPlugin(name = "WebView")
public class WebView extends Plugin {
    @PluginMethod
    public void setServerAssetPath(PluginCall call);
    @PluginMethod
    public void setServerBasePath(PluginCall call);
    @PluginMethod
    public void getServerBasePath(PluginCall call);
    @PluginMethod
    public void persistServerBasePath(PluginCall call);
}

Built-in Plugins

Types

public @interface Permission {
    String[] strings() default {};
    String alias() default "";
}

public @interface PluginMethod {
    String RETURN_PROMISE = "promise";
    String RETURN_CALLBACK = "callback";
    String RETURN_NONE = "none";
    
    String returnType() default RETURN_PROMISE;
}

public interface MessageHandler {
    void sendResponseMessage(PluginCall call, PluginResult successResult, PluginResult errorResult);
}

public class PluginHandle {
    public Plugin getInstance();
    public String getId();
}