plugins - 插件

云控提供了加载插件的机制，允许用户编写带有Activity, Service, C/C++库等的apk，安装到Android设备上，并用云控加载和调用。

一个插件是一个可独立安装的apk文件，用户安装后，再通过$plugins模块加载插件和调用其中的API。

插件支持打包时合并到apk中，打包后无需再单独安装插件。

$plugins.load(packageName)

• packageName {string} 加载的插件包名

加载一个插件，并返回插件模块中module.exports导出的对象。

如果插件未安装，则抛出PluginLoadException异常。

如何开发一个插件

提示

以下示例代码可在这里找到完整项目：插件SDK

本示例中的包名均为com.cloud.plugin.sdk.demo，在实际项目中插件包名可能有所不同。

插件SDK集成

新建一个Android项目，在项目的build.gradle文件中添加：

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

在具体模块(比如app)的build.gradle文件中添加：

dependencies {
    // ... 
    implementation 'com.github.CloudControlPro:sdk:1.0.0'
}

更多信息参见Jitpack.io。

插件配置

1. 新建PluginHelloWorld文件，继承于Plugin.

public class PluginHelloWorld extends Plugin {

    public PluginHelloWorld(Context context, Context selfContext, Object runtime, Object topLevelScope) {
        super(context, selfContext, runtime, topLevelScope);
    }

    // 返回插件的JavaScript胶水层代码的assets目录路径
    @Override
    public String getAssetsScriptDir() {
        return "js-plugin";
    }

    // 插件public API，可被JavaScript代码调用
    public String getStringFromJava() {
        return "Hello, CloudControl!";
    }

    // 插件public API，可被JavaScript代码调用
    public void say(String message) {
        getSelfContext().startActivity(new Intent(getSelfContext(),  HelloWorldActivity.class)
                .putExtra("message", message)
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    }
}

2. 新增MyPluginRegistry文件，继承于PluginRegistry:

public class MyPluginRegistry extends PluginRegistry {

    static {
        // 注册默认插件
        registerDefaultPlugin(new PluginLoader() {
            @Override
            public Plugin load(Context context, Context selfContext, Object runtime, Object topLevelScope) {
                return new PluginHelloWorld(context, selfContext, runtime, topLevelScope);
            }
        });
    }
}

在AndroidManifest.xml中配置以下meta-data, name为"org.cloud.plugin.sdk.registry"，value为MyPluginRegistry的包名。

  <application
        ...>

        <meta-data
            android:name="org.cloud.plugin.sdk.registry"
            android:value="com.cloud.plugins.sdk.demo.MyPluginRegistry" />

        <activity
            android:name=".HelloWorldActivity"
            android:exported="true" />

        <service
            android:name=".HelloworldPluginService"
            android:exported="true" />
    </application>

3. 编写JavaScript胶水层

在assets的相应目录(由Plugin.getAssetsScriptDir返回)中添加index.js文件，用于作为胶水层导出插件API。

module.exports = function (plugin) {
    let runtime = plugin.runtime;
    let scope = plugin.topLevelScope;

    function helloWorld() {
    }

    helloWorld.stringFromJava = plugin.getStringFromJava();

    helloWorld.say = function (message) {
        plugin.say(message);
    }

    return helloWorld;
}

4. 在CloudControl Pro中调用

编译插件为apk(assembleDebug/assembleRelease)，安装到设备上。在CloudControl Pro中使用以下代码调用：

let helloWorld = $plugins.load("com.cloud.plugins.sdk.demo");
console.log(helloWorld.stringFromJava);
helloWorld.say("Hello, CloudControl Pro Plugin");

5. 独立服务AIDL方式调用

可以在插件中编写一个Service，由CloudControl Pro唤起和绑定，并可在js中通过aidl调用Service的接口。

在Plugin中重写方法getService。

// 插件服务类，可选，用于AIDL方式和CloudControl Pro本体通信。可返回null
@Override
public ComponentName getService() {
    return new ComponentName(getSelfContext().getPackageName(), HelloworldPluginService.class.getName());
}

新建一个Service组件（注意在AndroidManifest中注册时需要是exported="true")，继承于PluginService。

public class HelloworldPluginService extends PluginService {
    private static final String ACTION_ADD = "add";

    @Override
    protected Result onRemoteCall(@NonNull String action, @NonNull Map<String, Object> args, @Nullable RemoteCallback callback) throws RuntimeException {
        switch (action) {
            case ACTION_ADD:
                return invokeAdd(args);
        }
        return Result.notImplemented(action);
    }

    private Result invokeAdd(Map<String, Object> args) {
        Number a   = PluginUtils.getNotNull(args, "a");
        Number b   = PluginUtils.getNotNull(args, "b");
        double sum = a.doubleValue() + b.doubleValue();
        return new Result(Collections.singletonMap("sum", sum));
    }
}

在index.js中添加胶水层代码:

helloWorld.remoteAdd = function (a, b) {
    return plugin.waitForConnection().call('add', {
        a: a,
        b: b
    }, null).get('sum');
}

然后可以在CloudControl Pro中调用：

let helloWorld = $plugins.load("com.cloud.plugins.sdk.demo");
console.log(helloWorld.remoteAdd(1, 2));