Cordova/plugins android

يقدم يوضح هذا القسم كيفية تقديم (implement) أكواد الإضافات الأصلية (native plugin code) على منصة أندرويد.

قبل قراءة هذه الصفحة، راجع صفحة دليل تطوير الإضافات لتكوين نظرة عامة على بنية الإضافات وواجهات JavaScript الخاصة بها. يواصل هذا القسم تطوير مثال الإضافة echo الوارد في دليل تطوير الإضافات، والذي يربط الاتصال من المعرض webview الخاص بكوردوفا إلى المنصة الأصلية (native platform)، والعكس بالعكس. للحصول على مثال آخر، راجع التعليقات في CordovaPlugin.java.

تستند إضافات أندرويد على منصة Cordova-Android، التي تُنشؤُ من المعرض Android WebView إضافة إلى جسر أصلي (native bridge). يتألف الجزء الأصلي من إضافات أندرويد من صنف جافا واحد على الأقل، والذي يوسع الصنف CordovaPlugin ويعيد تعريف أحد توابعه execute.

إعداد صنف الإضافة (Plugin Class Mapping)

تستخدم واجهة JavaScript الخاصة بالإضافة التابع cordova.exec على النحو التالي:

exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);‎

هذه الشيفرة ترسل طلبية (request) من webview إلى الجانب الأصلي (native side) لأندرويد، وتستدعي التابع action فعليا على الصنف service، مع وسائط إضافية تُمرر في المصفوفة args. سواء أقمت بتوزيع الإضافة على هيئة ملف جافا، أو كملف مضغوط jar، يجب تحديد الإضافة في ملف res/xml/config.xml الخاص بتطبيق Cordova-Android. انظر صفحة الإضافات لمزيد من المعلومات حول كيفية استخدام ملف plugin.xml لإدارج العنصر feature:

<feature name="<service_name>">
    <param name="android-package" value="<full_name_including_namespace>" />
</feature>‎

يتطابق service_name مع الاسم المستخدم عند استدعاء دالة الجافا exec . قيمته تساوي الاسم الكامل المؤهل لصنف جافا (ava class's fully qualified namespace identifier). بخلاف ذلك، يمكن أن تُصرّف (compiled) الإضافة لكنها لن تكون متاحة لكوردوفا.

تهيئة الإضافات ودورة الحياة (Plugin Initialization and Lifetime)

يتم إنشاء نسخة (instance) واحدة من كائن الإضافة خلال دورة حياة المعرض WebView. ولكن بعد الإشارة إليها أولاً عبر استدعاء من JavaScript، إلا في حال إضافة وسم <param> مع name="onload"‎ و value="true"‎في ملف config.xml. مثلا:

<feature name="Echo">
    <param name="android-package" value="<full_name_including_namespace>" />
    <param name="onload" value="true" />
</feature>‎

يجب أن تستخدم الإضافات التابع initialize في مرحلة الانطلاق.

@Override
public void initialize(CordovaInterface cordova, CordovaWebView webView) {
    super.initialize(cordova, webView);
    // your init code here
}‎

يمكن للإضافات الوصول إلى أحداث دورة حياة (lifecycle events) أندرويد، ويمكنها التعامل معها من خلال توسيع أحد التوابع (onResume و onDestroy، إلخ). الإضافات ذات الطلبيات الطويلة (long-running requests)، أو النشاطات الخلفية (background activity)، مثل قارئات الوسائط، أو المستمعات (listeners)، أو ذات الحالة الداخلية (internal state) يجب أن تقدّم (implement) التابع onReset()‎. والذي يُنفّذ عند انتقال المعرض(WebView) إلى صفحة جديدة، أو عند تحديث الصفحة، ما يؤدي إلى إعادة تحميل JavaScript.

كتابة إضافة لأندرويد بلغة جافا

يرسل استدعاء من JavaScript طلبية إضافة (plugin request) إلى الجانب الأصلي (native side)، ويُعيّن إضافة جافا المقابلة في ملف config.xml، ولكن كيف سيبدو الشكل النهائي لصنف إضافة جافا-أندرويد؟ أي شيء يتم إرساله إلى الإضافة عبر دالة الجافاسكريبت exec سيُمرّر إلى تابع execute الخاص بصنف بالإضافة. معظم تقديماتexecute تبدو كالتالي:

@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
    if ("beep".equals(action)) {
        this.beep(args.getLong(0));
        callbackContext.success();
        return true;
    }
    return false;  // Returning false results in a "MethodNotFound" error.
}‎

يتوافق الوسيط action الخاص بدالة جافاسكريبت exec مع تابع صنف خاص (private class method)، والذي يُرسل مع الوسائط الاختيارية.

عند إمساك الاستثناءات والأخطاء، من المهم أن تطابق الأخطاء المُعاادة إلى JavaScript أسماء الاستثناءات في لغة جافا قدر الممكن.

المهام الفرعية (Threading)

لا تعمل إضافات JavaScript في المهمة الرئيسية (main thread) للواجهة WebView؛ ولكنها تُجرى في المهمة الفرعية WebCore، مثل التابع execute. إن كنت بحاجة إلى التفاعل مع واجهة المستخدم، فعليك استخدام التابع runOnUiThread الخاص بالنشاط (Activity) كما يلي:

@Override
public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
    if ("beep".equals(action)) {
        final long duration = args.getLong(0);
        cordova.getActivity().runOnUiThread(new Runnable() {
            public void run() {
                ...
                callbackContext.success(); // Thread-safe.
            }
        });
        return true;
    }
    return false;
}‎

إذا لم تكن بحاجة إلى تشغيل الإضافة في المهمة الفرعية لواجهة المستخدم، ولكنك لا ترغب في إعاقة (block) المهمة الفرعية WebCore، فعليك تنفيذ الشيفرة البرمجية باستخدام ExecutorService الناتجة عن cordova.getThreadPool()‎ على النحو التالي:

@Override
public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
    if ("beep".equals(action)) {
        final long duration = args.getLong(0);
        cordova.getThreadPool().execute(new Runnable() {
            public void run() {
                ...
                callbackContext.success(); // Thread-safe.
            }
        });
        return true;
    }
    return false;
}‎

إضافة مكتبات الارتباط (Adding Dependency Libraries)

إن كان لإضافة أندرويد خاصتك ارتباطات (dependencies) إضافية، فيجب إدراجها في ملف plugin.xml، هناك طريقتان لفعل ذلك.

الطريقة المثلى هي استخدام الوسم <framework /‎> (انظر صفحة مواصفات الإضافات لمزيد من التفاصيل). يسمح تحديد المكتبات بهذه الطريقة بحلّها (تحديدها) عبر منطق إدارة الارتباطات الخاص بأداة Gradle. يسمح ذلك باستخدام المكتبات الشائعة مثل: gson و android-support-v4 و google-play-services من قبل عدة إضافات دون تداخل.

الخيار الثاني هو استخدام الوسم <lib-file /‎> لتحديد موضع ملف jar (انظر صفحة مواصفات الإضافات لمزيد من التفاصيل). لا تستخدم هذه الطريقة إلا إن كنت على يقين من أنه لا توجد إضافة أخرى تعتمد على تلك المكتبة (مثلًا إن كانت المكتبة مخصوصة بالإضافة). وإلا فإنك تخاطر بالتسبب في إطلاق أخطاء بنائية لمستخدمي الإضافة في حال قامت إضافة أخرى بإضافة المكتبة نفسها. تجدر الإشارة إلى أن مطوري تطبيقات Cordova ليسوا بالضرورة مطورين أصليين (أي لا يطورون بالضروة في اللغات الأصلية، مثل جافا)، لذا فإنّ أخطاء المنصة الأصلية البنائية قد تكون مصدر إحباط لهم.

مثال لإضافة أندرويد

لمطابقة ميزة جافااسكريبت echo المقدمة في واجهة في صفحة الإضافات، استخدم الملف plugin.xml لإدراج مواصفات feature في ملف config.xml الخاص بالمنصة المحلية:

<platform name="android">
    <config-file target="config.xml" parent="/*">
        <feature name="Echo">
            <param name="android-package" value="org.apache.cordova.plugin.Echo"/>
        </feature>
    </config-file>
    <source-file src="src/android/Echo.java" target-dir="src/org/apache/cordova/plugin" />
</platform>‎

ثم أضف ما يلي إلى ملف src/android/Echo.java:

package org.apache.cordova.plugin;
import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
/**
* This class echoes a string called from JavaScript.
*/
public class Echo extends CordovaPlugin {
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
    if (action.equals("echo")) {
        String message = args.getString(0);
        this.echo(message, callbackContext);
        return true;
    }
    return false;
}
private void echo(String message, CallbackContext callbackContext) {
    if (message != null && message.length() > 0) {
        callbackContext.success(message);
    } else {
        callbackContext.error("Expected one non-empty string argument.");
    }
}
}‎

توسع عمليات الاستيراد (import) الموجودة في أعلى الملف الصنف من CordovaPlugin، والذي يُعاد تعريف تابعه execute() لتلقي الرسائل من exec(). يختبر التابع execute() في البداية قيمة action، والتي ليس لها في هذه الحالة سوى قيمة echo واحدة صالحة. أي إجراء (action) آخر سيُعيد false ويطلق خطأ INVALID_ACTION، والذي يُحوّل إلى دالة الخطأ المستدعاة من جانب JavaScript.

بعد ذلك، يسترد التابع سلسلة echo باستخدام التابع args الخاص بالكائن المعطى getString، لتحديد الوسيط الأول الممرر إلى التابع. بعد تمرير القيمة إلى التابع الخاص echo، يتم فحص الوسيط للتأكد من أنه لا يساوي null أو سلسلة نصية فارغة، وإلا سيستدعي التابع callbackContext.error() دالة الخطأ (error callback) في JavaScript. إذا مرت التحقيقات بنجاح، يمرر callbackContext.success() السلسلة النصية الأصلية message مرة أخرى إلى دالة النجاح (success callback) في JavaScript كوسيط.

تكامل أندرويد (Android Integration)

يوفر أندرويد نظام مقاصد (Intent) يسمح للعمليات (processes) بالتواصل مع بعضها البعض. يمكن للإضافات الوصول إلى كائنات CordovaInterface، والتي لديها القدرة على الوصول إلى نشاط (Activity ) أندرويد الذي بُشغّل التطبيق. هذا هو السياق (Context) المطلوب لإطلاق مقصد أندرويد جديد. يتيح Intent للإضافات بدء تشغيل نشاط (CordovaInterface) للحصول على نتيجة، وتعيين استدعاء الإضافة (callback plugin) لاستخدامه عند عودة Activity إلى التطبيق.

اعتبارًا من Cordova 2.0، لم يعد بإمكان الإضافات الوصول إلى Intent مباشرةً، وتم إيقاف العضو القديم Context. كل توابع ctx صارت موجودة الآن في السياق (ctx)، بحيث يمكن لكلا التابعين Context و getContext() إعادة الكائن المطلوب.

أذونات أندرويد

كانت أذونات أندرويد تُعالج حتى وقت قريب وقتَ التثبيت (install-time)، بدلاً من وقت التشغيل (runtime). من الضروري التصريح بهذه الأذونات في أي تطبيق يستخدم الأذونات، ويجب إضافة هذه الأذونات إلى بيان أندرويد (Android Manifest). يمكن تحقيق ذلك باستخدام getActivity() لإدارج تلك الأذونات في ملف config.xml. يستخدم المثال التالي إذن جهات الاتصال (Contacts permission). AndroidManifest.xml

أذونات وقت التشغيل (Cordova-Android 5.0.0 فما فوق)

قدم إصدار Android 6.0 "Marshmallow" نموذج أذونات جديد حيث يمكن للمستخدم تشغيل وإيقاف الأذونات حسب الضرورة. وهذا يعني أن التطبيقات يجب أن تتكيف مع هذه التغييرات، وهذا هو محور إصدار Cordova-Android 5.0.0.

يمكن العثور على الأذونات التي تحتاج إلى المعالجة وقت التشغيل في توثيق مطوري برامج أندرويد

<config-file target="AndroidManifest.xml" parent="/*">
    <uses-permission android:name="android.permission.READ_CONTACTS" />
</config-file>‎

.

بالنسبة للإضافات، يمكن طلب الإذن عن طريق استدعاء تابع الأذونات ذو الإمضاء التالي: here

من المعتاد تعيينه إلى متغير محلي ثابت.

cordova.requestPermission(CordovaPlugin plugin, int requestCode, String permission);‎

من المتعارف أيضًا تعريف كود الطلب requestCode على النحو التالي:

public static final String READ = Manifest.permission.READ_CONTACTS;‎

ثم ينبغي التحقق من الإذن في التابع exec، :

public static final int SEARCH_REQ_CODE = 0;‎

في هذه الحالة، سنستدعي requestPermission وحسب:

if(cordova.hasPermission(READ))
{
    search(executeArgs);
}
else
{
    getReadPermission(SEARCH_REQ_CODE);
}‎

سيؤدي هذا إلى استدعاء النشاط (activity) وظهور مِحَثّ (prompt) يطلب الإذن. بمجرد حصول المستخدم على الإذن، يجب معالجة النتيجة باستخدام التابع

protected void getReadPermission(int requestCode)
{
    cordova.requestPermission(this, requestCode, READ);
}‎

، والذي يجب أن يعاد تعريفه في كل إضافة. يمكن العثور على مثال على ذلك أدناه:

onRequestPermissionResult

ستعود التعليمة switch أعلاه من المحث وبناءًا على قيمة الوسيط المعطى requestCode قد تستدعي التابع المعني. تجدر الإشارة إلى أن محثات (switch) الأذونات قد تتعطل في حالة عدم معالجة التنفيذ بشكل صحيح، وأنه يجب تجنب ذلك.

بالإضافة إلى الاستئذان للحصول على إذن واحد، من الممكن أيضًا طلب الأذونات لمجموعة بأكملها، عن طريق تعريف مصفوفة الأذونات، كما هو الحال في الإضافة Geolocation:

public void onRequestPermissionResult(int requestCode, String[] permissions,
                                         int[] grantResults) throws JSONException
{
    for(int r:grantResults)
    {
        if(r == PackageManager.PERMISSION_DENIED)
        {
            this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR));
            return;
        }
    }
    switch(requestCode)
    {
        case SEARCH_REQ_CODE:
            search(executeArgs);
            break;
        case SAVE_REQ_CODE:
            save(executeArgs);
            break;
        case REMOVE_REQ_CODE:
            remove(executeArgs);
            break;
    }
}‎

يعد ذلك، كل ما عليك القيام به لطلب الإذن، هو ما يلي:

String [] permissions = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION };‎

يطلب هذا التعبير الأذونات المحددة في المصفوفة. من المستحسن إتاحة مصفوفة أذونات بشكل عام، نظرًا لأنه يمكن استخدامها من طرف الإضافات التي تستخدم إضافتك كواحدة من ارتباطاتها، على الرغم من أن هذا ليس ضروريا.

تصحيح إضافات أندرويد (Debugging Android Plugins)

يمكن تصحيح أخطاء أندرويد باستخدام Eclipse أو Android Studio، على الرغم من أنه يُوصى باستخدام Android Studio. نظرًا لاستخدام Cordova-Android حاليًا كمكتبة، وأن الإضافات تُدعم كشيفرة مصدرية، فمن الممكن تصحيح شيفرة جافا داخل تطبيقات Cordova تمامًا مثل تطبيقات أندرويد الأصلية.

إطلاق أنشطة أخرى

هناك بعض الإجراءات الخاصة التي يجب اتخاذها إن كانت الإضافة ستطلق نشاطًا (Activity) يدفع Cordova

cordova.requestPermissions(this, 0, permissions);‎

إلى الخلفية. سينهي نظام التشغيل أندرويد الأنشطة الموجودة في الخلفية عندما تنحسر الذاكرة المتاحة في الجهاز. في هذه الحالة، ستُنهى نسخة (instance‏) Activity كذلك. إن كانت الإضافةة تنتظر نتيجة من النشاط (CordovaPlugin) الذي أطلقته، فسيتم إنشاء نسخة جديدة من الإضافة عند إعادة Cordova Activity إلى الواجهة، وعند الحصول على النتيجة. لكن لن تُحفظ حالة الإضافة أو تستعاد تلقائيًا، وسيُفقد السياق Activity الخاص بالإضافة. هناك تابعان يمكن أن يعرفها CallbackContext للتعامل مع هذه المسألة:

CordovaPlugin

من المهم ملاحظة أنه يجب لا ينبغي استخدام التابعين المذكورين أعلاه إلا إن كانت الإضافة ستطلق نشاطًا (

/**
 * Called when the Activity is being destroyed (e.g. if a plugin calls out to an
 * external Activity and the OS kills the CordovaActivity in the background).
 * The plugin should save its state in this method only if it is awaiting the
 * result of an external Activity and needs to preserve some information so as
 * to handle that result; onRestoreStateForActivityResult() will only be called
 * if the plugin is the recipient of an Activity result
 *
 * @return  Bundle containing the state of the plugin or null if state does not
 *          need to be saved
 */
public Bundle onSaveInstanceState() {}
/**
 * Called when a plugin is the recipient of an Activity result after the
 * CordovaActivity has been destroyed. The Bundle will be the same as the one
 * the plugin returned in onSaveInstanceState()
 *
 * @param state             Bundle containing the state of the plugin
 * @param callbackContext   Replacement Context to return the plugin result to
 */
public void onRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {}‎

) تتوخى نتيجة منه، ويجب ألأ تستعيد إلا الحالة اللازمة لمعالجة نتيجة النشاط. لن تتم استعادة حالة الإضافة إلا في حالة الحصول على نتيجة من النشاط طلبتها الإضافة باستخدام التابع Activity الخاص بالكائن CordovaInterface وكان نظام التشغيل قد أنهى نشاط كوردوفا أثناء وجوده في الخلفية.

كجزء من startActivityForResult()، سيُمرّر إلى الإضافة سياق بديل CallbackContext. من المهم أن تدرك أن السياق CallbackContext ليس هو نفسه الذي تم إنهاؤه مع النشاط. إذ يُفقد الاستدعاء الأصلي (original callback)، ولن يتم تشغيلها في تطبيق JavaScript. بدلاً من ذلك، سيُعيد onRestoreStateForActivityResult() النتيجة كجزء من الحدث CallbackContext الذي يتم تفعيله عند استئناف تشغيل التطبيق. الحدث [../../../cordova/events/events.html#resume resume] يتبغ البنية التالية: [../../../cordova/events/events.html#resume resume]

• سيطابق

  {
      action: "resume",
      pendingResult: {
          pluginServiceName: string,
          pluginStatus: string,
          result: any
      }
  }‎

  العنصر pluginServiceName من ملف plugin.xml.
• [../../../plugin_ref/spec.html#name name element] سيكون سلسلة نصية تصف حالة ناتج الإضافة (PluginResult) المٌمررة إلى CallbackContext. راجع صفحة PluginResult.java للتعرف على قيم السلسلة النصية الموافقة لحالات الإضافات
• pluginStatus سيساوي النتيجة التي مررتها الإضافة إلى CallbackContext (سلسلة نصية، عدد، كائن JSON، إلخ.)

سيتم تمرير محتوى result إلى لك عمليات الاستدعاء (callbacks) التي سجلتها تطبيقات JavaScript مع الحدث [../../../cordova/events/events.html#resume resume]. هذا يعني أن النتيجة ستذهب مباشرة إلى تطبيق Cordova؛ لن يكون للإضافة خاصتك فرصة لمعالجة النتيجة بجافااسكريبت قبل أن يتسلمها التطبيق. وبالتالي، يجب أن تسعى إلى جعل النتيجة المعادة من الشيفرة الأصلية كاملة قدر الإمكان، وألا تعتمد على دوال جافااسكريبت عند إطلاق الأنشطة.

تأكد من توضيح كيفية تفسير تطبيق Cordova للنتيجة التي يتلقاها عند الحدث [../../../cordova/events/events.html#resume resume]. يُناط بتطبيقات Cordova حفظ حالاتها، وتذكر الطلبيات التي أرسلتها، والوسائط التي مررتها إذا لزم الأمر. ومع ذلك، يجب عليك توضيح معاني قيم [../../../cordova/events/events.html#resume resume] ونوع البيانات التي ستعاد في الحقل pluginStatus كجزء من الواجهة البرمجية للإضافة.

هذه سلسلة الأحداث الكاملة لبدء نشاط معين:

• تطبيق Cordova يستدعي الإضافة خاصتك
• تطلق الإضافة نشاطًا قصد الحصول على نتيجة
• ينهي نظام التشغيل أندرويد كلًا من النشاط ونسخة (instance) الإضافة
• يستدعى الحدث onSaveInstanceState()‎
• يتفاعل المستخدم مع نشاطك، ثم ينتهي النشاط
• يعاد إنشاء نشاط Cordova، ويتم تلقي نتيجة النشاط
• يستدعى الحدث onRestoreStateForActivityResult()‎
• يتم استدعاء [../../../cordova/events/events.html#resume resume] ثم تمرر الإضافة نتيجة إلى السياق CallbackContext الجديد
• يُفعّل الحدث onActivityResult() ويُتلقى من قبل تطبيق Cordova

يوفر أندرويد إعدادات للمطوِّرين لتصحيح أخطاء إنهاء الأنشطة عندما يكون هناك انحسار في مساحة الذاكرة. قم بتمكين الإعداد "Don't keep activities" في قائمة خيارات المطور على جهازك أو المحاكي لمحاكاة سيناريوهات انحسار الذاكرة. إن كانت الإضافة تُطلق نشاطات خارجية، فيجب عليك إجراء بعض الاختبارات مع تمكين هذا الإعداد لضمان التعامل بشكل صحيح مع سيناريوهات انحسار الذاكرة.

مصادر

• قسم إضافات أندرويد في التوثيق الرسمي لكوردوفا.