Напишем плагин для apache cordova на примере определения рутованного устройства android.
Подразумевается, что вы умеете работать уже с cordova и вся экосистема развернута. Нам понадобится утилита plugman.
npm install -g plugman
Далее с помощью нее можем создать «рыбу» для плагина с помощью команды
plugman create --plugin_id "ru.trykov.rootdetection" --name cordova-plugin-root-detection --plugin_version 0.1.0
- —plugin_id задает идентификатор плагина в реестре плагинов кордовы
- —name задает имя плагина
- —plugin_version версию плагина
В результате мы получили файл plugin.xml, папки src и www. Папка www еще содержит js файл плагина с примером экспорта функции.
plugin.xml
Конфигурация плагина, в которой можно указать различные параметры. Подбронбее о всех элементах можно прочитать в документации. Мы же остановимся на основных вещах.
engines
Указываем версию кордовы на которую ориентирован плагин. В примере указана версия не менее 3.0.0
<engines> <engine name="cordova" version=">=3.0.0"/> </engines>
js-module
Указываем js модуль плагина, его имя и расположение. Так же используется элемент clobbers, который указывает, как в приложении cordova мы будем обращаться к модулю.
<js-module name="RootDetection" src="www/rootdetection.js"> <clobbers target="rootdetection"/> </js-module>
platform
Добавить платформу можно командой
plugman platform add --platform_name android
В результате в plugin.xml появится элемент platform, в котором мы можем указать конфигурационный файл в конечной платформе. И требуемые файлы плагина.
<platform name="android"> <config-file parent="/*" target="res/xml/config.xml"> <feature name="RootDetection"> <param name="android-package" value="ru.trykov.root.RootDetection"/> <param name="onload" value="true"/> </feature> </config-file> <config-file parent="/*" target="AndroidManifest.xml"></config-file> <source-file src="src/android/RootDetection.java" target-dir="src/ru/trykov/root"/> </platform>
Связываем java и js
Итак мы прописали пути до java файлов нашего плагина, теперь неплохо бы их самих создать. В элементе source-file мы указали путь src/android/RootDetection.java. Создадим необходимые папки и файлы по данному пути.
RootDetection.java
Файл, которые отвечает за работу на android платформе. Он должен наследоваться от CordovaPlugin и переопределять метод execute.
public class RootDetection extends CordovaPlugin { @Override public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { if (action.equals("isDeviceRooted")) { try { callbackContext.success(isDeviceRooted() ? 1 : 0); return true; } catch (Exception e) { callbackContext.error("N/A"); return false; } } return false; } }
Метод execute принимает на вход следующие параметры:
- action — имя метода по которому обращаются к плагину через js
- args — аргументы метода
- callbackContext — контекст обратного вызова, в который передаем результат работы плагина
Мы проверяем имя метода и вызываем нужный нам приватный метод класса для его исполнения. При успешном выполнении возвращаем success через контекст, иначе error.
www/rootdetection.js
Теперь через js мы должны обратиться к плагину. Cordova позволяет это делать через интерфейс cordova.exec со следующими параметрами:
- successCallback функция при успешном вызове
- errorCallack функция при ошибке
- Имя Класса для вызова
- Имя метода
- аргументы
var exec = require('cordova/exec'); exports.isDeviceRooted = function(arg0, success, error) { exec(success, error, "RootDetection", "isDeviceRooted", [arg0]); };
Работа в приложении
Фактически создание плагина завершено, его уже можно добавлять в приложение cordova.
cordova plugin add /путь/до/плагина/
Вы так же можете поделится результатами своих трудов с другими разработчиками опубликовал плагин в реестре плагинов кордова.
Публикация
Итак у нас есть готовый плагин и мы хотим его зарегистрировать в cordova plugin registry т.е. реестр плагинов кордовы, для этого выполним следующие команды:
Добавляем пользователя: указываем логин, пароль, почту.
plugman adduser
Публикуем.
plugman publish
И… чуть было не опубликовались, но выскочила ошибка login error. Хотя мы тока что добавили пользователя. Гугление приводит к даунгрейду plugman до 23 версии
npm install -g plugman@0.23.0
Далее заново добавляем пользователя и публикуемся.
Теперь плагин доступен в cordova cli по id плагина.
cordova plugin add ru.trykov.rootdetection
Миграция на npm
C 21 апреля 2015 года cordova потихоньку переносит плагины в npm реестр. Чтобы начать использовать npm необходимо обновить cordova cli до версии не ниже 5.0. Меняются id основных плагинов cordova с org.apache.cordova.*
на cordova-plugin-*
. Теперь разработчики могут использовать команду cordova plugin add cordova-plugin-device
. с использование нового ID плагина, который будет выкачиваться из npm. Что будет с текущим реестром плагинов? С 15 июля 2015 он станет доступен только для чтения до 15 октября, а дальше увидим. Подробнее читайте тут.
По шагам мигрируем на npm:
- (По желанию) Можно изменить id плагина в plugin.xml и опубликовать их в реестре плагинов кордовы.
- Отправить pull request с новым и старым id на Cordova Registry Mapper.
- Кордова итегрирует эти id в cordova cli и будет выдавать предупреждение пользователям, чтобы они использовали новый идентификатор
- Добавить package.json
- plugman createpackagejson <directory> (если находимся в папке плагина, то ставим точку)
- Опубликовать в npm
- npm login
- npm publish
Далее можем уже добавлять плагин cordova через новый id.
cordova plugin add cordova-plugin-root-detection
Но после логина в npm у нас эта команда вызовет ошибку
unauthorized Name or password is incorrect
Чтобы от нее избавится — удаляем .npmrc из домашней директории.
Итого
Мы написали плагин, опубликовали его в реестре плагинов кордовы и npm. Ознакомится с полным кодом плагина вы можете на github. Присылайте свои pull request’ы и пишите плагины для кордовы.
Удачного дня.
Спасибо за статью, все четко и по делу
А можно ли у вас заказать плагин для mobile ads яндекса, хочу перейти с эдмоб на яндекс. Делаю приложения на кордове
Спасибо за обращение. К сожалению из-за ограниченного количества свободного времени боюсь это будут неадекватные сроки для реализации данного плагина. Я бы порекомендовал вам обратится на фриланс биржу или создать issue в репозитории mobile ads яндекса с просьбой создать данный плагин. Ребята из яндекса внимательные и думаю не откажут в данной просьбе.