Cordova/plugins android

يشرح هذا القسم كيفية تنفيذ شيفرات الإضافات الأصلية (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 الخاص بالتطبيق. انظر صفحة الإضافات لمزيد من المعلومات حول كيفية استخدام الملف plugin.xml لإدارج العنصر feature:

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

يتطابق service_name مع الاسم المستخدم عند الاستدعاء exec في JavaScript. قيمته تساوي الاسم الكامل المؤهل (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);
    // شيفرة التهيئة هنا
}‎

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

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

يرسل استدعاء من جافاسكريبت طلبية إضافة (plugin request) إلى الجانب الأصلي (native side)، ويُعيّن إضافة جافا المقابلة في الملف config.xml، وسيُمرّر أي شيء يتم إرساله إلى الإضافة عبر الدالة exec التي تخص JavaScript إلى تابع 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;  // "MethodNotFound" في حال وقوع خطأ false إعادة القيمة
}

يتوافق المعامل action الخاص بالدالة exec تخص JavaScript مع تابع صنف خاص (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 (انظر صفحة مواصفات الإضافات لمزيد من التفاصيل). لا تستخدم هذه الطريقة إلا إن كنت على يقين من أنه لا توجد إضافة أخرى تعتمد على تلك المكتبة (مثلًا إن كانت المكتبة خاصة فقط بإضافتك). وإلا فإنك تخاطر بالتسبب في إطلاق أخطاء بنائية لمستخدمي الإضافة في حال قامت إضافة أخرى بإضافة المكتبة نفسها. تجدر الإشارة إلى أنَّ مطوري تطبيقات كوردوفا ليسوا بالضرورة مطورين أصليين (أي لا يطورون بالضروة في اللغات الأصلية، مثل جافا)، لذا فإنّ أخطاء المنصة الأصلية البنائية قد تكون مصدر إحباط لهم.

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

لمطابقة واجهة الميزة 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;

/**
* هذا الصنف يعرض سلسلة نصية مُستدعاة من جافاسكريبت
*/
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". وأي قيمة أخرى ستعيد false وتطلق الخطأ INVALID_ACTION، والذي سيُحوّل إلى دالة الخطأ المستدعاة (error callback) من جانب شيفرة جافاسكريبت.

بعد ذلك، يسترد التابع السلسلة النصية echo (أو صدى السلسلة النصية) باستخدام التابع getString الخاص بالكائن المعطى args، لتحديد المعامل الأول المُمرَّر إلى التابع.

بعد تمرير القيمة إلى التابع echo الخاص، يٌفحص المعامل للتأكد من أنَّه لا يساوي null أو سلسلة نصية فارغة، وإلا سيستدعي التابعُ callbackContext.error()‎ دالة الخطأ (error callback) في جافاسكريبت. إذا مرت التحقيقات بنجاح، فسيُمرر callbackContext.success() ‎السلسلةَ النصية message الأصلية مرةً أخرى إلى دالة رد نداء النجاح (success callback) في JavaScript كمعامل.

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

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

بدءًا من كوردوفا 2.0، لم يعد بإمكان الإضافات الوصول إلى السياق Context مباشرةً، كما تم إيقاف العضو القديم ctx.

كل توابع ctx صارت موجودة الآن في السياق Context، بحيث يمكن لكلا التابعين getActivity()‎ و getContext()‎ إعادة الكائن المطلوب.

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

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

يستخدم المثال التالي إذن جهات الاتصال (Contacts permission):

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

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

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

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

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

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

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

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

من المتعارف عليه أيضًا تعريف شيفرة الطلب requestCode على النحو التالي:

public static final int SEARCH_REQ_CODE = 0;‎

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

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

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

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

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

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;
    }
}

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

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

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

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

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

تنقيح إضافات أندرويد

يمكن تنقيح أخطاء أندرويد (Debugging Android Plugins) باستخدام Eclipse أو Android Studio، لكن يُوصَى باستخدام Android Studio.

لمّا كانت منصة Cordova-Android تُستخدَم حاليًا كمكتبة مشروع، وكانت الإضافات مدعومة كشيفرة مصدرية، فمن الممكن تصحيح شيفرة جافا داخل تطبيقات كوردوفا تمامًا مثل تطبيقات أندرويد الأصلية.

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

هناك بعض الإجراءات الخاصة التي يجب اتخاذها إن كنت تريد من الإضافة أن تطلق نشاطًا (Activity) يدفع (pushes) نشاط كوردوفا (Cordova Activity) إلى الخلفية. سيُنهِي أندرويد الأنشطة الموجودة في الخلفية عندما تنحسر الذاكرة المتاحة في الجهاز. في هذه الحالة، ستُنهَى أيضًا النسخة CordovaPlugin.

إن كانت الإضافة تنتظر نتيجة من النشاط الذي أطلَقته، فسيتم إنشاء نسخةٍ جديدةٍ من الإضافة عند إعادة نشاط كوردوفا إلى الواجهة، وعند الحصول على النتيجة. على أي حال، لن تُحفَظ حالة الإضافة أو تستعاد تلقائيًا، وسيُفقد السياق CallbackContext الخاص بالإضافة. هناك تابعان يمكن أن تنفذهما CordovaPlugin للتعامل مع هذه المسألة:

/**
 * تُستدعى عند إنهاء النشاط، مثلا إن استدعت الإضافة نشاطا خارجيا وقام نظام التشغيل 
 * الموجود في الخلفية CordovaActivity بإنهاء
 * ينبغي أن تحفظ الإضافة حالتها في هذا التابع فقط إن كانت تنتظر نتيجة من النشاط 
 * الخارجي، وكانت بحاجة إلى حفظ بعض االمعلومات لأجل معالجة النتيجة
 * إلا في حال كانت الإضافة ستستلِم نتيجة النشاط onRestoreStateForActivityResult() لن يُستدعي
 * 
*
 * @return  حزمة تحتوي حالة الإضافة أو القيمة المعدومة إن لم تكن هناك حاجة لحفظ
 *          الحالة
 */
public Bundle onSaveInstanceState() {}
/**

 *
 * CordovaActivity تُستدعى إذا كانت الإضافة ستستلِم نتيجة نشاط ما بعد إنهاء 
 * onSaveInstanceState() الحزمة ستكون مماثلة لتلك المعادة من الإضافة في 
 * 
 * @param state             حزمة تحتوي حالة الإضافة
 * @param callbackContext   السياق البديل الذي ستُعاد نتيجة الإضافة إليه
 */
public void onRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {}‎

لاحظ أنه ينبغي ألا يُستخدم التابعان المذكورين أعلاه إلا إن كانت الإضافة ستطلق نشاطًا (Activity) تتوخى نتيجةً منه، ويجب ألأ تستعيد إلا الحالة اللازمة لمعالجة نتيجة النشاط. لن تُستعَاد (restore) حالة الإضافة إلا في حال الحصول من النشاط على نتيجة كانت الإضافة قد طلبتها (requested) باستخدام التابع CordovaInterface الخاص بالكائن startActivityForResult() ‎وكان نظام التشغيل قد سبق وأنهى نشاط كوردوفا أثناء وجوده في الخلفية. كجزء من التابع onRestoreStateForActivityResult()‎، سيتم تمرير سياق بديل CallbackContext إلى الإضافة. من المهم أن تدرك أنَّ السياق CallbackContext ليس هو نفسه السياق الذي تم إنهاؤه مع النشاط. إذ يُفقَد الاستدعاء الأصلي (original callback)، كما لن يُنفّذ في تطبيق JavaScript. بدلًا من ذلك، سيُعيد السياق CallbackContext النتيجة كجزء من الحدث resume الذي يُفعّل عند استئناف تشغيل التطبيق. حمل (payload) الحدث resume يتبغ الصيغة التالية:

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

• pluginServiceName: ستطابق اسم العنصر في الملف plugin.xml.
• pluginStatus: ستكون سلسلة نصية تصف حالة ناتج الإضافة (PluginResult) المٌمرر إلى السياق CallbackContext. راجع الصفحة PluginResult.java للتعرف على قيم السلسلة النصية الموافقة لحالات الإضافات.
• result: ستساوي النتيجة التي مررتها الإضافة إلى CallbackContext (سلسلة نصية، أو عدد، أو كائن JSON، ...إلخ.)

سيتم تمرير محتوى resume إلى كل ردود النداء التي سجلتها تطبيقات JavaScript مع الحدث resume. هذا يعني أنَّ النتيجة ستذهب مباشرةً إلى تطبيق كوردوفا؛ ولن يكون للإضافة فرصةٌ لمعالجة النتيجة بواسطة JavaScript قبل أن يتسلمها التطبيق. لذلك حاول جعل النتيجة المعادة من الشيفرة الأصلية كاملةً قدر الإمكان، وألا تعتمد على دوال جافاسكريبت عند إطلاق الأنشطة.

تأكد من توضيح كيفية تفسير تطبيق كوردوفا للنتيجة التي يتلقاها عند وقوع الحدث resume، إذ يُناط بتطبيقات كوردوفا حفظ حالاتها، وتذكر الطلبيات التي أرسلتها، والوسائط التي مررتها إذا لزم الأمر. يجب عليك أيضًا توضيح معاني قيم pluginStatus ونوع البيانات التي ستعاد في الحقل resume كجزء من الواجهة البرمجية للإضافة.

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

• يستدعي تطبيق كوردوفا الإضافة خاصتك
• تطلق الإضافة نشاطًا تتوخى منه الحصول على نتيجة
• ينهي نظام التشغيل أندرويد كلًا من النشاط ونسخة الإضافة
  • يُستدعَى التابع onSaveInstanceState()‎
• يتفاعل المستخدم مع نشاطك، ثم ينتهي النشاط
• يعاد إنشاء نشاط كوردوفا، ثم يُستَلم نتيجة النشاط
  • يُستدعَى التابع onRestoreStateForActivityResult()‎
• يٌستدعَى onActivityResult()‎ ثمَّ تمرِّر الإضافةُ النتيجةَ إلى السياق CallbackContext الجديد
• يُفعّل الحدث resume، ثم يُستلَم من قبل تطبيق كوردوفا

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

انظر أيضًا

• دليل تطوير الإضافات
• تطوير الإضافات على منصة iOS
• تطوير الإضافات على منصة ويندوز
• ترقية أندرويد

مصادر

• صفحة Android Plugin Development Guide في توثيق كوردوفا الرسمي