عرض مصدر Cordova/platforms android

<noinclude>{{DISPLAYTITLE:دليل التطوير على منصة أندرويد في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
[[تصنيف: Cordova Platform]]
يوضح هذا الدليل كيفية إعداد بيئة SDK لنشر تطبيقات كوردوفا لأجهزة أندرويد، وكيفية استخدام أدوات سطر الأوامر المتمحورة حول أندرويد اختياريًا في سير عمل التطوير الخاص بك. تحتاج إلى تثبيت Android SDK بغض النظر عما إذا كنت تريد استخدام أدوات الصدفة (shell) المتمحورة حول المنصة أو سطر الأوامر العابر للمنصات لأغراض التطوير. للمقارنة بين مساري التطوير، راجع صفحة [[Cordova/overview|نظرة عامة]] التي شُرح فيها كل [[Cordova/overview#.D9.85.D8.B3.D8.A7.D8.B1.D8.A7.D8.AA .D8.A7.D9.84.D8.AA.D8.B7.D9.88.D9.8A.D8.B1|مسار عمل]] على حدة. وللحصول على تفاصيل حول سطر الأوامر، انتقل إلى صفحة [[Cordova/cli|واجهة سطر الأوامر]] في كوردوفا.

== المتطلبات والدعم ==
استعمال كوردوفا من أجل أندرويد يتطلب Android SDK الذي يمكن تثبيته على OS X أو لينكس أو ويندوز. راجع [http://developer.android.com/sdk/index.html#Requirements متطلبات النظام] من أجل تثبيت Android SDK. تدعم أحدث حزمة من أندرويد في كوردوفا [http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels المستوى 28] للواجهة البرمجية (Android API-Level). يمكن العثور على مستويات Android API المعتمدة وإصدارات Android لإصدارات كوردوفا-أندرويد الماضية في الجدول التالي:
{| class="wikitable"
!إصدار كوردوفا-أندرويد
!مستويات واجهة أندرويد البرمجية المدعومة
!إصدار أندرويد المقابل
|-
|‎8.X.X
|1‎9 - 28
|‎4.4 - 9.0.0
|-
|‎7.X.X
|1‎9 - 27
|‎4.4 - 8.1
|-
|6‎.X.X
|‎16 - 26
|4.1‎ - 8.0.0
|-
|5‎.X.X
|‎14 - 23
|‎4.0 - 6.0.1
|-
|4.1‎.X
|‎14 - 22
|4.0‎ - 5.1
|-
|‎4.0.X
|‎10 - 22
|2.3.‎3 - 5.1
|-
|‎3.7.X
|‎10 - 21
|‎2.3.3 - 5.0.2
|}
يرجى ملاحظة أن الإصدارات المذكورة هنا لأجل حزمة كوردوفا-أندرويد ([https://github.com/apache/cordova-android cordova-android]) وليس من أجل سطر أوامر كوردوفا. ولأجل تحديد إصدار حزمة أندرويد من كوردوفا المثبت في مشروعك الخاص، قم بتنفيذ الأمر <code>[[Cordova/cli#.D8.AE.D9.8A.D8.A7.D8.B1.D8.A7.D8.AA .D9.85.D8.AE.D8.B5.D9.88.D8.B5.D8.A9 .D8.A8.D8.A7.D9.84.D9.85.D9.86.D8.B5.D8.A7.D8.AA .28Platform-specific options.29|cordova platform ls]]</code> في المجلد الذي يحتوي على المشروع الخاص بك.

كقاعدة عامة، تصبح إصدارات أندرويد غير مدعومة من قِبل كوردوفا إذا انخفضت إلى أقل من 5٪ على [http://developer.android.com/about/dashboards/index.html لوحة بيانات التوزيع] من Google.

== تثبيت المتطلبات ==

=== مجموعة تطوير جافا (JDK) ===
قم بتثبيت [http://developer.android.com/about/dashboards/index.html مجموعة تطوير جافا] الإصدار JDK) 8). عند التثبيت على ويندوز، يجب أيضًا تعيين متغير البيئة <code>JAVA_HOME</code> وفقًا لمسار تثبيت JDK الخاص بك (اطلع على القسم إعداد متغيرات البيئة في الأسفل).

=== Gradle ===
بالنسبة لكوردوفا-أندرويد 6.4.0، أصبح [https://gradle.org/install/ Gradle] مطلوبًا الآن تثبيته لبناء أندرويد.

عند التثبيت على ويندوز، يجب إضافة Gradle إلى المسار الخاص بك (راجع قسم إعداد متغيرات البيئة في الأسفل).

=== أندرويد SDK ===
ثبت [https://developer.android.com/studio/index.html Android Studio]. توجد إرشادات التثبيت التفصيلية على الموقع بشكل واضح. عندما تفتح Android Studio للمرة الأولى سيتم إرشادك إلى كيفية تثبيت Android SDK.

=== إضافة حزم SDK ===
بعد تثبيت Android SDK، يجب أيضًا تثبيت الحزم لأي مستوى من [http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels مستويات واجهة برمجة التطبيقات] التي ترغب في استهدافها. يوصى بتثبيت أعلى إصدارمن SDK  يدعمه إصدار كوردوفا-أندرويد الخاص بك (راجع قسم المتطلبات والدعم في الأعلى).

افتح Android SDK Manager (عبر الذهاب إلى <code>Tools > SDK Manager</code> في Android Studio أو عبر تنفيذ الأمر <code>sdkmanager</code> من الطرفية) وتأكد من تثبيت ما يلي:
# حزم SDK لمنصة أندرويد للنسخة المستهدفة من نظام أندرويد
# أدوات بناء حزم SDK لأندرويد الإصدار 19.1.0 أو أحدث
# مستودع دعم أندرويد (ستعثر عليه في أسفل التبويب "SDK Tools")
راجع توثيق أندرويد حول [https://developer.android.com/studio/intro/update.html تثبيت حزم SDK] لمزيد من التفاصيل.

=== ضبط متغيرات البيئة ===
تتطلب أدوات سطر الأوامر في كوردوفا بعض متغيرات البيئة لتعمل بشكل صحيح. سيحاول سطر الأوامر تعيين هذه المتغيرات لك، ولكن في بعض الحالات قد تحتاج إلى تعيينها يدويًا. يجب تحديث المتغيرات التالية:
# اضبط متغير البيئة <code>JAVA_HOME</code> على مكان تثبيت JDK الخاص بك.
# اضبط متغير البيئة <code>ANDROID_HOME</code> على موقع تثبيت Android SDK.
# يوصى أيضًا بإضافة المجلدات <code>tools</code>، و <code>tools/bin</code>، و <code>platform-tools</code> الخاصة بحزم Android SDK إلى <code>PATH</code>.

=== النظام OS X ولينكس ===
في النظام ماك أو لينكس، يمكنك استخدام محرر نصي لإنشاء أو تعديل الملف <code>‎~/.bash_profile</code>. ولتعيين متغير بيئة، أضف خطًا يستخدم <code>export</code> مثل ذلك (استبدل المسار بالتثبيت المحلي):<syntaxhighlight lang="shell">
export ANDROID_HOME=/Development/android-sdk/
</syntaxhighlight>لتحديث <code>PATH</code>، أضف خطًا يشبه ما يلي (استبدال المسارات بمواقع تثبيت Android SDK المحلي):<syntaxhighlight lang="shell">
export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools

</syntaxhighlight>أعد تشغيل الطرفية لمعرفة سيريان مفعول هذا التغيير أو نفذ الأمر التالي عوضًا عن ذلك:<syntaxhighlight lang="shell">
$ source ~/.bash_profile
</syntaxhighlight>

=== نظام ويندوز ===
قد تختلف هذه الخطوات وفقًا لإصدار ويندوز المثبت. أغلق وأعد تشغيل أية نوافذ مفتوحة لموجه الأوامر (command prompt) بعد إجراء أية تغييرات للتحقق من تطبيقها.
# انقر فوق قائمة '''ابدأ (Start)''' في الزاوية السفلية اليسرى من سطح المكتب
# في شريط البحث، ابحث عن "'''متغيرات البيئة'''" ('''Environment Variables''') واختر "'''تعديل متغيرات بيئة النظام'''" ('''Edit the system Environment Variables''') من الخيارات التي تظهر لك
# في النافذة التي تظهر، انقر فوق زر "'''متغيرات البيئة'''" ('''Environment Variables''')
لإنشاء متغيرات بيئة جديدة، انقر فوق "'''جديد'''" ('''New...‎''') وأدخل اسم المتغير وقيمته.

لتعيين المتغير <code>PATH</code>، حدده ثم اضغط على "'''تعديل'''" ('''Edit'''). أضف بعد ذلك المدخلات في المواقع التابع للمتغير <code>PATH</code>. اطلع على المثال التالي (استبدل المسارات بمواقع تثبيت Android SDK المحلي:<syntaxhighlight lang="shell">
C:\Users\[your user]\AppData\Local\Android\Sdk\platform-tools
C:\Users\[your user]\AppData\Local\Android\Sdk\tools

</syntaxhighlight>

== ضبط المشروع ==

=== إعداد محاكي ===
إذا كنت ترغب في تشغيل تطبيق كوردوفا الخاص بك على محاكي أندرويد، فستحتاج أولًا إلى إنشاء جهاز أندرويد افتراضي (AVD، اختصار للعبارة Android Virtual Device). راجع توثيق أندرويد [https://developer.android.com/studio/run/managing-avds.html لإدارة الأجهزة الافتراضية] و[https://developer.android.com/studio/run/emulator.html#about ضبط المحاكي] و[https://developer.android.com/studio/run/emulator-acceleration.html إعداد حساس التسارع].

بمجرد تكوين الجهاز الافتراضي الخاص بك بشكل صحيح، يجب أن تكون قادرًا على نشر تطبيق كوردوفا الخاص بك على المحاكي عن طريق تنفيذ الأمر التالي:<syntaxhighlight lang="shell">
$ cordova run --emulator
</syntaxhighlight>

=== ضبط Gradle ===
اعتبارًا من cordova-android@4.0.0، تم تصميم كوردوفا لمشاريع أندرويد باستخدام [http://www.gradle.org/ Gradle]. للحصول على إرشادات حول البناء باستخدام Ant، راجع الإصدارات القديمة من التوثيق. يرجى ملاحظة أن البناء باستعمال Ant أصبح مهملًا بدءًا من الإصدار 25.3.0 لأدوات SDK للأندرويد.

=== ضبط خاصيات Gradle ===
من الممكن تكوين Gradle عن طريق تحديد قيم بعض [https://docs.gradle.org/current/userguide/build_environment.html خاصيات Gradle] التي تعرضها كوردوفا. الخصائص التالية متاحة لتعيين:
{| class="wikitable"
!الخاصية
!الوصف
|-
|<code>cdvBuildMultipleApks</code>
|إذا تم تعيين هذه الخاصية، فسيتم إنشاء ملفات APK متعددة: واحد لكل نظام أساسي مدمج مدعوم بمشاريع المكتبة (x86، ARM، ...إلخ). قد يكون هذا مهمًا إذا كان مشروعك يستخدم مكتبات أصلية كبيرة، مما قد يزيد بشكل كبير من حجم ملف APK الذي تم إنشاؤه. إذا لم يتم تعيينها، فسيتم إنشاء ملف APK واحد يمكن استخدامه على جميع الأجهزة.
|-
|<code>cdvVersionCode</code>
|تستبدل مجموعة كود الإصدار في A<code>ndroidManifest.xml</code>.
|-
|<code>cdvReleaseSigningPropertiesFile</code>
|القيمة الافتراضية: <code>release-signing.properties</code>

تحدد هذه الخاصية مسار الملف ‎.properties الذي يحتوي على معلومات التوقيع لبنيات الإصدار (انظر قسم توقيع التطبيق).
|-
|<code>cdvDebugSigningPropertiesFile</code>
|القيمة الافتراضية: <code>debug-signing.properties</code>

تحدد مسار الملف ‎.properties الذي يحتوي على معلومات تسجيل لبنيات التنقيح (انظر قسم توقيع التطبيق). هذه الخاصية مفيدة عندما تحتاج إلى مشاركة مفتاح توقيع مع مطورين آخرين.
|-
|<code>cdvMinSdkVersion</code>
|تستبدل قيمة المجموعة <code>minSdkVersion</code> في الملف <code>AndroidManifest.xml</code>. هذه الخاصية مفيدة عند إنشاء ملفات APK متعددة استنادًا إلى إصدار SDK.
|-
|<code>cdvBuildToolsVersion</code>
|تستبدل القيمة <code>android.buildToolsVersion</code> التي يتم اكتشافها تلقائيًا.
|-
|<code>cdvCompileSdkVersion</code>
|تستبدل القيمة <code>android.compileSdkVersion</code> التي يتم اكتشافها تلقائيًا.
|}
تستطيع أن تضبط هذه الخصائص بواسطة واحدة من هذه الطرق الأربعة:
* عن طريق ضبط متغيرات البيئة مثل:
<syntaxhighlight lang="shell">
$ export ORG_GRADLE_PROJECT_cdvMinSdkVersion=20
$ cordova build android


</syntaxhighlight>
* بواسطة استخدام الراية <code>‎--gradleArg</code> أثناء استعمال الأمر <code>[[Cordova/cli#.D8.A7.D9.84.D8.A3.D9.85.D8.B1 cordova build|build]]</code> أو <code>[[Cordova/cli#.D8.A7.D9.84.D8.A3.D9.85.D8.B1 cordova run|run]]</code> في سطر أوامر كوردوفا مثل:
<syntaxhighlight lang="shell">
 $ cordova run android -- --gradleArg=-PcdvMinSdkVersion=20
</syntaxhighlight>
* بواسطة وضع ملف اسمه <code>gradle.properties</code>  في مجلد منصة أندرويد (<code><your-project>/platforms/android</code>)  وادخال الخصائص فيه بالشكل التالي:
<syntaxhighlight lang="shell">
# In <your-project>/platforms/android/gradle.properties
cdvMinSdkVersion=20
</syntaxhighlight>
* بواسطة توسيع  <code>build.gradle</code> عن طريق الملف <code>build-extras.gradle</code> وضبط الخاصية بالشكل التالي:
<syntaxhighlight lang="shell">
// In <your-project>/platforms/android/build-extras.gradle
ext.cdvMinSdkVersion = 20


</syntaxhighlight>يتضمن الخياران الأخيران تضمين ملف إضافي في مجلد منصة أندرويد الخاص بك. وبصفة عامة، لا يمكن تحرير محتويات هذا المجلد لأنه من السهل أن فقدان أو استبدال هذه التغييرات. بدلًا من ذلك، يجب نسخ هذين الملفين من موقع آخر إلى هذا المجلد كجزء من أمر البناء باستخدام [[Cordova/hooks|الخطاف]] <code>before_build</code>.

=== توسيع build.gradle ===
إذا كنت بحاجة إلى تخصيص <code>build.gradle</code>، بدلًا من تحريره مباشرةً، فيجب إنشاء ملف شقيق باسم <code>build-extras.gradle</code>. سيتم تضمين هذا الملف بواسطة <code>build.gradle</code> الرئيسي عند وجوده. يجب وضع هذا الملف في مجلد منصة أندرويد (‎(<code><your-project>/platform/android</code>، لذا يُنصح بنسخه عبر برنامج نصي مرفق بالخطاف <code>before_build</code>. إليك هذا المثال:<syntaxhighlight lang="shell">
// build-extras.gradle مثال عن
// `build.gradle` يُضمّن هذا الملف في بداية

// وإعادة تعيين القيم الافتراضية - build.gradle يمكن إعداد بعض الخاصيات - انظر 
// ext.cdvDebugSigningPropertiesFile = '../../android-debug-keys.properties'

// `build.gradle` إعداد عادي لـ
android {
  defaultConfig {
    testInstrumentationRunner 'android.support.test.runner.AndroidJUnitRunner'
  }
}
dependencies {
  androidTestImplementation 'com.android.support.test.espresso:espresso-core:2.2.2', {
    exclude group: 'com.android.support', module: 'support-annotations'
  }
}

// `build.gradle` تنفيذ الشيفرة في نهاية  `ext.postBuildExtras` عند تعيينها، تتيح الدالة 
ext.postBuildExtras = {
    android.buildTypes.debug.applicationIdSuffix = '.debug'
}
</syntaxhighlight>لاحظ أن الإضافات ممكن أن تتضمن ملفات <code>build-extras.gradle</code>  عن طريق:<syntaxhighlight lang="xml">
<framework src="some.gradle" custom="true" type="gradleReference" />
</syntaxhighlight>

=== ضبط إصدار الشيفرة ===
إن أردت تغيير [https://developer.android.com/studio/publish/versioning.html إصدار الشيفرة] للتطبيق apk المولد، فاضبط الخاصية <code>android-versionCode</code> في العنصر widget في الملف [[Cordova/config ref|config.xml]] الخاص بالتطبيق. إذا لم يتم تعيين الخاصية <code>android-versionCode</code>، فسيتم تحديد رمز الإصدار باستخدام الخاصية <code>version</code>. على سبيل المثال، إذا كان الإصدار هو <code>MAJOR.MINOR.PATCH</code>:<syntaxhighlight lang="shell">
versionCode = MAJOR * 10000 + MINOR * 100 + PATCH
</syntaxhighlight>إذا كان التطبيق الخاص بك قد فعَّل خاصية Gradle التي هي <code>CdvBuildMultipleApks</code> (راجع قسم ضبط خاصيات Gradle في الأعلى)، فسيتم ضرب إصدار الشيفرة الخاص بتطبيقك أيضًا بالقيمة 10 بحيث يمكن استخدام آخر رقم من الشيفرة للإشارة إلى البنية التي تم إنشاء apk لها. ستجرى عملية الضرب هذه بغض النظر عما إذا كان رمز الإصدار مأخوذًا من الخاصية <code>android-versionCode</code> أو تم إنشاؤه باستخدام الإصدار. كن على علم بأن بعض الإضافات المضافة إلى مشروعك (بما في ذلك <code>Cordova-plugin-crosswalk-webview</code>) قد تقوم بتعيين خاصية Gradle هذه تلقائيًا.

'''ملاحظة مهمة''': عند تحديث الخاصية <code>android-versionCode</code>، فإنه ليس من الحكمة زيادة إصدار الشيفرة المأخوذ من التطبيقات apk المبنية. فبدلًا من ذلك، يجب زيادة الشيفرة استنادًا إلى القيمة الموجودة في الخاصية <code>android-versionCode</code> في الملف [[Cordova/config ref|config.xml]]. ويرجع ذلك إلى أنَّ الخاصية <code>cdvBuildMultipleApks</code> تتسبب في ضرب إصدار الشيفرة المراد ضربه بالقيمة 10 في التطبيقات apk المبنية، وبالتالي فإن استخدام هذه القيمة سيؤدي إلى أن يكون إصدار الشيفرة التالي لديك 100 مرة قدر الأصلي وهكذا دواليك.

== توقيع التطبيق ==
أولاً، يجب قراءة [https://developer.android.com/studio/publish/app-signing.html متطلبات توقيع تطبيق أندرويد].

=== استخدام الرايات ===
لتوقيع تطبيق، تحتاج إلى المعاملات التالية:
{| class="wikitable"
!المعامل
!الراية
!الوصف
|-
|المخزن الرئيسي (المفتاحي)
|<code>‎--keystore</code>
|المسار إلى ملف التنفيذ (binary file) الذي يمكنه الاحتفاظ بمجموعة من المفاتيح.
|-
|كلمة المرور للمخزن الرئيسي
|<code>‎--storePassword</code>
|إنشاء كلمة مرور للدخول إلى المخزن الرئيسي (المفتاحي).
|-
|الاسم البديل
|<code>‎--alias</code>
|الاسم البديل المعرف الذي يحدد المفتاح الخاص المستخدم الدخول.
|-
|كلمة المرور
|<code>‎--password</code>
|كلمة المرور المخصصة لمفتاح خاص.
|-
|انواع المخزن الرئيسي (المخزن المفتاحي)
|<code>‎--keystoreType</code>
|القيمة الافتراضية هي: <code>auto-detect</code> أي الاكتشاف التلقائي الذي يستند على لاحقة الملف والتي إما أن تكون pkcs12 أو jks.
|}
يمكن تحديد هذه المعاملات باستخدام وسائط سطر الأوامر أعلاه مع الأمر <code>[[Cordova/cli#.D8.A7.D9.84.D8.A3.D9.85.D8.B1 cordova build|build]]</code> والأمر <code>[[Cordova/cli#.D8.A7.D9.84.D8.A3.D9.85.D8.B1 cordova run|run]]</code> في سطر أوامر كوردوفا.

'''ملاحظة''': يجب أن تستخدم الرمز <code>--</code> بشكل مزدوج للإشارة إلى أنها وسائط خاصة بالمنصة. اطلع على المثال التالي:<syntaxhighlight lang="shell">
cordova run android --release -- --keystore=../my-release-key.keystore --storePassword=password --alias=alias_name --password=password
</syntaxhighlight>

=== استخدام build.json ===
بدلاً من ذلك، يمكنك تحديدها في ملف ضبط البناء (الذي هو <code>build.json</code>) باستخدام الوسيط <code>‎--buildConfig</code> مع نفس الأوامر. إليك نموذجًا من ملف ضبط البناء:<syntaxhighlight lang="text">
{
    "android": {
        "debug": {
            "keystore": "../android.keystore",
            "storePassword": "android",
            "alias": "mykey1",
            "password" : "password",
            "keystoreType": ""
        },
        "release": {
            "keystore": "../android.keystore",
            "storePassword": "",
            "alias": "mykey2",
            "password" : "password",
            "keystoreType": ""
        }
    }
}
</syntaxhighlight>بالنسبة إلى توقيع الإصدار، يمكن استبعاد كلمات المرور وسيصدر نظام الإنشاء نافذة منبثقة تطلب كلمة المرور.

هناك أيضا دعم لدمج ومطابقة وسائط ومعاملات سطر الأوامر في <code>build.json</code>. ستحصل القيم من وسائط سطر الأوامر على الأسبقية. هذا يمكن أن يكون مفيدًا لتحديد كلمات المرور على سطر الأوامر.

=== استخدام Gradle ===
يمكنك أيضًا تحديد خصائص التوقيع من خلال تضمين الملف <code>‎.properties</code> والإشارة إليه باستخدام خاصيات Gradle التي هي <code>cdvReleaseSigningPropertiesFile</code> و <code>cdvDebugSigningPropertiesFile</code> (راجع قسم ضبط خاصيات Gradle في الأعلى). يجب أن يبدو الملف كما يلي:<syntaxhighlight lang="text">
storeFile=relative/path/to/keystore.p12
storePassword=SECRET1
storeType=pkcs12
keyAlias=DebugSigningKey
keyPassword=SECRET2

</syntaxhighlight>الخاصية <code>storePassword</code> و <code>keyPassword</code> اختيارية، وستتم مطالبتك بها إذا تم حذفها.

== التنقيح ==
للحصول على تفاصيل حول أدوات تصحيح الأخطاء (debugging) التي تأتي مجمعة مع Android SDK، راجع توثيق مطوري برامج أندرويد لتصحيح الأخطاء. بالإضافة إلى ذلك، يوفر توثيق [https://developer.android.com/studio/debug/index.html مطوري برامج أندرويد لتصحيح الأخطاء] لتطبيقات الويب مقدمة [http://developer.android.com/guide/webapps/debugging.html لتصحيح أخطاء] جزء التطبيق الذي يعمل في عرض الويب.

=== فتح مشروع في Android Studio ===
يمكن فتح مشاريع كوردوفا للأندرويد في [https://developer.android.com/studio/index.html Android Studio]. قد يكون ذلك مفيدًا إذا كنت ترغب في استخدام أدوات التنقيح المدمجة في Android Studio أو إذا كنت تعمل على تطوير إضافات أندرويد. يرجى ملاحظة أنه عند فتح مشروعك في Android Studio، يوصى بعدم تعديل شيفرتك في البيئة التطويرية هنالك (IDE) لأن ذلك سيؤدي إلى تعديل الشيفرة في المجلد <code>platforms</code> في مشروعك (وليس المجلد <code>www</code>) وستكون التغييرات عرضةً للاستبدال. بدلًا من ذلك، قم بتحرير المجلد <code>www</code> ونسخ التغييرات التي أجريتها عن طريق تنفيذ الأمر <code>[[Cordova/cli#.D8.A7.D9.84.D8.A3.D9.85.D8.B1 cordova build|cordova build]]</code>.

يجب على مطوري الإضافات الراغبين في تحرير الشيفرة الأصلية في بيئة تطوير Android Studio استخدام الراية ‎<code>--link</code> عند إضافة الإضافة للمشروع عن طريق الأمر  <code>cordova plugin add</code>. سيؤدي هذا إلى ربط الملفات بحيث تلك التغييرات التي تطرأ على ملفات الإضافة في المجلد <code>platforms</code> تنعكس في المجلد المصدري للإضافة (والعكس صحيح).

لفتح مشروع كوردوفا لتطبيق أندرويد في Android Studio، اتبع الخطوات التالية:
# شغل '''Android Studio'''.
# حدد '''Import Project''' ‏(Eclipse ADT, Gradle, etc).  [[ملف:asdk_import_project.png|بديل=فتح Android Studio ثم تحديد الخيار Import Project من الخيارات الظاهرة لفتح مشروع كوردوفا لتطبيق أندرويد.|بدون|فتح Android Studio ثم تحديد الخيار Import Project من الخيارات الظاهرة لفتح مشروع كوردوفا لتطبيق أندرويد فيه.|تصغير|600بك]]
# حدد مجلد منصة أندرويد في مشروعك (‎<code><your-project>/platforms/android</code>).  [[ملف:asdk_import_select_location.png|بديل=تحديد مجلد منصة أندرويد في مشروعك الذي أنشئ باستعمال كوردوفا وذلك لفتحه في Android Studio.|بدون|تحديد مجلد منصة أندرويد في مشروعك الذي أنشئ باستعمال كوردوفا وذلك لفتحه في Android Studio.|تصغير|400بك]]
# بالنسبة إلى سؤال <code>Gradle Sync</code>، يمكنك ببساطة الإجابة بنعم.
بمجرد الانتهاء من الاستيراد، يجب أن تكون قادرًا على إنشاء التطبيق وتشغيله مباشرة من Android Studio. راجع صفحة [https://developer.android.com/studio/intro/index.html4 نظرة عامة على Android Studio] وصفحة [https://developer.android.com/studio/run/index.html البناء والتشغيل من Android Studio] لمزيد من التفاصيل.

[[ملف:asdk_import_done.png|بديل=اكتمال استيراد تطبيق أندرويد أنشئ باستعمال كوردوفا في Android Studio.|بدون|اكتمال استيراد تطبيق أندرويد أنشئ باستعمال كوردوفا في Android Studio.|تصغير|600بك]]

== سير العمل المرتكز على منصة واحدة ==
يتضمن كوردوفا-أندرويد عددًا من النصوص البرمجية (scripts) التي تسمح باستخدام المنصة بدون سطر أوامر كوردوفا الكامل. قد يوفر لك مسار التطوير هذا مجموعة أكبر من خيارات التطوير في مواقف معينة لا تجدها في سير العمل العابر للمنصات عبر سطر الأوامر. على سبيل المثال، تحتاج إلى استخدام أدوات الصدفة (shell) عند نشر عارض WebView مخصص إلى جانب المكونات الأصلية. قبل استخدام مسار التطوير هذا، يجب عليك تهيئة بيئة Android SDK كما هو موضح في قسم المتطلبات والدعم أعلاه.

لكل من النصوص الموضحة أدناه، ارجع إلى [[Cordova/cli|واجهة سطر أوامر كوردوفا]] للحصول على مزيد من المعلومات حول الوسائط والاستعمالات. يملك كل برنامج نصي اسمًا يطابق أمرًا مقابلًا له في سطر الأوامر. على سبيل المثال،إنَّ <code>Cordova-android/bin/create</code> يعادل الأمر <code>cordova create</code>.

للبدء، قم بتنزيل حزمة أندرويد-كوردوفا من [https://www.npmjs.com/package/cordova-android npm] أو [https://github.com/apache/cordova-android Github]. لإنشاء مشروع باستخدام هذه الحزمة، قم بتشغيل البرنامج النصي <code>create</code> في المجلد <code>bin</code>:<syntaxhighlight lang="shell">
$ cordova-android/bin/create
</syntaxhighlight>سيكون للمشروع الذي تم إنشاؤه مجلدًا باسم <code>cordova</code> بداخله يحتوي على برامج نصية لأوامر كوردوفا الخاصة بالمشروع (مثل الأمر <code>run</code>، و <code>build</code>، ...إلخ). بالإضافة إلى ذلك، سيحتوي المشروع على هيكل مختلف عن مشروع كوردوفا العادي. ومن الجدير بالذكر أن المجلد <code>‎/www</code> نقل إلى ‎<code>/assets/www</code>.

لتثبيت إضافات في هذا المشروع، استخدم الأداة [[Cordova/plugman|Plugman]] المساعدة.

== الترقية ==
انتقل إلى [https://cordova.apache.org/docs/en/latest/guide/platforms/android/upgrade.html هذه] الصفحة للحصول على إرشادات لترقية إصدار كوردوفا-أندرويد.

== دليل دورة الحياة ==

=== كوردوفا وأندرويد ===
تتكون تطبيقات أندرويد الأصيلة عادةً من سلسلة من [http://developer.android.com/reference/android/app/Activity.html النشاطات] (Activities) التي يتفاعل معها المستخدم. يمكن اعتبار هذه النشاطات كشاشات فردية تشكل تطبيقًا، إذ إن مهام مختلفة في التطبيق سيكون لها في الغالب نشاطها الخاص حيث تحتوي كل واجهة على دورة حياتها الخاصة التي يتم الحفاظ عليها أثناء دخول الواجهة من واجهة جهاز المستخدم وتركها.

وعلى العكس، يتم تنفيذ تطبيقات كوردوفا على منصة أندرويد داخل عرض الويب المضمّن في واجهة واحدة (أي نشاط أندرويد واحد فقط). يتم تعريض دورة حياة هذه الواجهة إلى التطبيق الخاص بك من خلال أحداث المستند التي يتم إطلاقها. لا يضمن للأحداث أن تتماشى مع دورة حياة أندرويد تمامًا، ولكن يمكنها توفير إرشادات لحفظ واستعادة حالتك. ترتبط هذه الأحداث تقريبًا بردود نداء أندرويد كما يلي:
{| class="wikitable"
!حدث كوردوفا
!المكافيء العام لأندرويد
!المعنى
|-
|<code>deviceready</code>
|<code>onCreate()‎</code>
|التطبيق قيد البدء (ليس من جهة الخلفية).
|-
|<code>pause</code>
|<code>onPause()‎</code>
|التطبيق قيد الانتقال إلى الخلفية.
|-
|<code>resume</code>
|<code>‎onResume()‎</code>
|التطبيق يعود إلى المقدمة.
|}
معظم منصات كوردوفا الأخرى لديها مفهوم مماثل لدورات الحياة ويجب أن تطلق هذه الأحداث نفسها عندما تحدث إجراءات مشابهة على جهاز المستخدم. ومع ذلك، يقدم أندرويد بعض التحديات الفريدة التي يمكن أن تظهر في بعض الأحيان بفضل دورة حياة الواجهة الأصلية.

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

=== متى يمكن أن يحدث هذا؟ ===
التطبيق الخاص بك هو عرضة للتدمير من قبل نظام التشغيل كلما تركته جانبًا. فهناك موقفان رئيسيان يمكن أن يحدث فيهما هذا؛ الحالة الأولى والأكثر وضوحًا هي عندما يضغط المستخدم على زر الصفحة الرئيسية أو يتحول إلى تطبيق آخر.

ومع ذلك، هناك حالة ثانية (وأكثر خفاء) يمكن لبعض الإضافات إدخالها. كما ذكر أعلاه، تقتصر تطبيقات كوردوفا عادة على النشاط الفردي الذي يحتوي على العارض [[Cordova/webviews|WebView]]. ومع ذلك، هناك حالات قد يتم فيها تشغيل أنشطة أخرى بواسطة المكونات الإضافية وتدفع نشاط كوردوفا مؤقتًا إلى الخلفية. يتم عادةً تشغيل هذه الأنشطة الأخرى لتنفيذ مهمة محددة باستخدام تطبيق أصلي مثبت على الجهاز. على سبيل المثال، تطلق [[Cordova/cordova plugin camera|إضافة الكاميرا]] في كوردوفا أي واجهة كاميرا مثبتة أصلًا على الجهاز لالتقاط صورة. إن إعادة استخدام تطبيق الكاميرا المثبت بهذه الطريقة يجعل تطبيقك يشبه إلى حد كبير التطبيق الأصلي كلما يحاول المستخدم التقاط صورة. وللأسف أيضًا، عندما تدفع الواجهة المحلية تطبيقك إلى الخلفية، هناك احتمال أن ينهيه نظام التشغيل.

لتحسين فهمنا للحالة الثانية، دعنا نجرب عبر مثال باستخدام [[Cordova/cordova plugin camera|إضافة الكاميرا]]. تخيل أنَّ لديك تطبيقًا يتطلب من المستخدم التقاط صورة للملف الشخصي. سيظهر تدفق الأحداث في التطبيق عندما يسير كل شيء كما هو مخطط له على النحو التالي:
# يتفاعل المستخدم مع تطبيقك ويحتاج إلى التقاط صورة.
# يُطلَق المكون الإضافي للكاميرا واجهة الكاميرا الأصلية.
## ''يتم دفع واجهة كوردوفا إلى الخلفية (يتم تشغيل الحدث <code>[[Cordova/events#pause|pause]]</code>).''
# يأخذ المستخدم صورة.
# ينتهي نشاط الكاميرا.
## ''يتم نقل واجهة كوردوفا إلى المقدمة (يتم إطلاق الحدث <code>[[Cordova/events#resume|resume]]</code>).''
# يتم إرجاع المستخدم إلى التطبيق الخاص بك حيث توقف.
ومع ذلك، يمكن تعطيل تدفق الأحداث هذا إذا كان الجهاز منخفضًا في الذاكرة. إذا تم إنهاء النشاط بواسطة نظام التشغيل، فسيتم تشغيل تسلسل الأحداث أعلاه على النحو التالي:
# يتفاعل المستخدم مع تطبيقك ويلزم التقاط صورة.
# يُطلق المكون الإضافي للكاميرا واجهة الكاميرا الأصلية.
## ''نظام التشغيل يدمر واجهة كوردوفا (يتم إطلاق الحدث <code>[[Cordova/events#pause|pause]]</code>).''
# يأخذ المستخدم صورة.
# تنتهي واجهة الكاميرا.
## ''يقوم نظام التشغيل بإعادة إنشاء نشاط كوردوفا (يتم إطلاق الحدث <code>[[Cordova/events#deviceready|deviceready]]</code> والحدث <code>[[Cordova/events#resume|resume]]</code>)''
# يشعر المستخدم بالارتباك حول سبب عودته فجأة إلى شاشة تسجيل الدخول إلى تطبيقك.
في هذه الحالة، قام نظام التشغيل بتدمير التطبيق في الخلفية ولم يحافظ التطبيق على حالته كجزء من دورة الحياة. وعندما عاد المستخدم إلى التطبيق، تم إعادة إنشاء العارض [[Cordova/webviews|WebView]] وبدا أن التطبيق قد أعيد تشغيله من الصفر (وبالتالي ارتبك المستخدم لحصول ذلك). هذا التسلسل من الأحداث يعادل ما يحدث عندما يتم الضغط على زر الصفحة الرئيسية أو يبدل المستخدم بين التطبيقات. إن المفتاح لمنع التجربة أعلاه هو الاشتراك في الأحداث والحفاظ على الحالة بشكل صحيح كجزء من دورة حياة النشاط.

=== احترام دورة الحياة ===
في الأمثلة أعلاه، تتم الإشارة إلى أحداث [[JavaScript]] التي يتم إطلاقها بخط مائل. هذه الأحداث هي فرصتك لحفظ واستعادة حالة التطبيق الخاص بك. يجب تسجيل عمليات الاسترجاعات في الدالة <code>bindEvents</code> الخاصة بالتطبيق والتي تستجيب لأحداث دورة الحياة عن طريق حفظ الحالة. يتم ترك المعلومات التي قمت بحفظها وكيفية حفظها لتقديرك، ولكن يجب عليك التأكد من حفظ المعلومات الكافية بحيث يمكنك إعادة المستخدم إلى المكان الذي توقف فيه عند عودته إلى تطبيقك.

هناك عامل إضافي واحد في المثال أعلاه لا ينطبق إلا في الحالة التي تمت مناقشتها ثانيًا (أي عندما تبدأ إضافة ما نشاطًا خارجيًا). حيث لم تكن حالة التطبيق مفقودة فقط عندما انتهى المستخدم من التقاط صورة، ولكن كانت أيضًا خلال التقاطها. عادةً، سيتم تسليم هذه الصورة إلى التطبيق الخاص بك من خلال رد نداء مسجل من قبل في إضافة الكاميرا. ومع ذلك، عندما تم تدمير العارض [[Cordova/webviews|WebView]]، فإنَّ رد النداء هذا - ولحسن الحظ - قد فقد إلى الأبد. يوفر الإصدار 5.1.0 وما بعده من كوردوفا-أندرويد وسيلة لجلب النتيجة لاستدعاء تلك الإضافة عند استئناف عمل تطبيقك.

=== استرداد نتائج رد نداء إضافة (الإصدار 5.1.0 وما بعده من كوردوفا-أندرويد) ===
عندما يدمر نظام التشغيل نشاط كوردوفا الذي تم دفعه إلى الخلفية عن طريق إضافة، يتم فقدان أي عمليات استرجاع معلقة أيضًا. هذا يعني أنه إذا قمت بتمرير رد نداء إلى الإضافة التي بدأت نشاطًا جديدًا (مثل [[Cordova/cordova plugin camera|إضافة الكاميرا]])، فلن يتم إطلاق رد النداء هذا عند إعادة إنشاء التطبيق. ومع ذلك، بدءًا من الإصدار 5.1.0 وما بعده من كوردوفا-أندرويد، ستتضمن حمولة الحدث <code>[[Cordova/events#resume|resume]]</code> أية نتائج معلقة للإضافة من طلب الإضافة الذي بدأ النشاط الخارجي الذي تم إجراؤه قبل تدمير النشاط.

تلتزم حمولة الحدث <code>[[Cordova/events#resume|resume]]</code> بالتنسيق التالي:<syntaxhighlight lang="text">
{
    action: "resume",
    pendingResult: {
        pluginServiceName: string,
        pluginStatus: string,
        result: any
    }
}
</syntaxhighlight>يتم تعريف حقول هذه الحمولة على النحو التالي:
* <code>pluginServiceName</code>: اسم الإضافة التي تعيد النتيجة (مثل "Camera" عند استعمال إضافة الكاميرا). يمكن العثور على هذا في الوسم <code><name></code> للملف plugin.xml للإضافة.
* <code>pluginStatus</code>: حالة استدعاء الإضافة (انظر أدناه).
* <code>result</code>: أيًا كانت نتيجة استدعاء الإضافة.
تتضمن القيم المحتملة للحقل <code>pluginStatus</code> في الحقل <code>pendingResult</code> ما يلي:
* <code>"OK"</code>: ثم استدعاء الإضافة بنجاح.
* <code>"No Result"</code>: انتهى استدعاء الإضافة دون نتيجة.
* <code>"Error"</code>: أدى استدعاء الإضافة إلى حدوث بعض الأخطاء العامة.

* أخطاء متنوعة أخرى:
**<code>"Class not found"</code>
**<code>"Illegal access"</code>
**<code>"Instantiation error"</code>
**<code>"Malformed url"</code>
**<code>"IO error"</code>
**<code>"Invalid action"</code>
**<code>"JSON error"</code>
يرجى ملاحظة أن الأمر متروك للإضافة لتقرر ما هو موجود في الحقل <code>result</code> ومعنى الحقل <code>pluginStatus</code> الذي تم إعادته. ويمكنك الرجوع إلى واجهة برمجة التطبيقات للإضافة التي تستخدمها للاطلاع على ما يجب أن تتوقعه من هذه الحقول وكيفية احتوائها على قيمها.

=== مثال ===
فيما يلي مثالًا موجزًا لتطبيق يستخدم الحدث <code>[[Cordova/events#resume|resume]]</code> والحدث <code>[[Cordova/events#pause|pause]]</code> لإدارة الحالة. ويستخدم البرنامج [[Cordova/cordova plugin camera|إضافة الكاميرا]] كمثال على كيفية استرداد نتائج استدعاء الإضافة من حمولة الحدث <code>[[Cordova/events#resume|resume]]</code>. ويتطلب الجزء من الشيفرة الذي يتعامل مع الكائن <code>event.pendingResult</code> للحدث <code>[[Cordova/events#resume|resume]]</code> الذي يتطلب الإصدار 5.1.0 وما بعده من كوردوفا-أندرويد:<syntaxhighlight lang="javascript">
// onPause() و  onResume() تمثل هذه الحالة حالة التطبيق وستُخزن وتُسترجع عبر 
var appState = {
    takingPicture: true,
    imageUri: ""
};

var APP_STORAGE_KEY = "exampleAppState";

var app = {
    initialize: function() {
        this.bindEvents();
    },
    bindEvents: function() {
        // سنسجل رد النداء لأحداث دورة الحياة التي تهمنا
        document.addEventListener('deviceready', this.onDeviceReady, false);
        document.addEventListener('pause', this.onPause, false);
        document.addEventListener('resume', this.onResume, false);
    },
    onDeviceReady: function() {
        document.getElementById("take-picture-button").addEventListener("click", function() {
            // لما أطلقت إضافة الكامير نشاطا خارجيا، فهناك احتمال أن يُنهى تطبيقنا قبل أن تُستدعى دوال رد النداء الخاصة
            //  بالفشل أو النجاح
            //  حيث نخزن ونسترجع الحالة لمعالجة هذه الحالة onResume() و  onPause() انظر
            appState.takingPicture = true;

            navigator.camera.getPicture(cameraSuccessCallback, cameraFailureCallback,
                {
                    sourceType: Camera.PictureSourceType.CAMERA,
                    destinationType: Camera.DestinationType.FILE_URI,
                    targetWidth: 250,
                    targetHeight: 250
                }
            );
        });
    },
    onPause: function() {
        // نتحقق هنا إن كنا في طور التقاط صورة. إن كان الأمر كذلك، نرغب في حفظ حالتنا لكي  
        // onResume()  نسترجع نتيجة الإضافة في
        // نرغب كذلك في الحفظ إن كنا قد استرجعنا عنوان الصورة سلفا.
        if(appState.takingPicture || appState.imageUri) {
            window.localStorage.setItem(APP_STORAGE_KEY, JSON.stringify(appState));
        }
    },
    onResume: function(event) {
        // نتحقق هنا من الحلة المحفوظة ونسترجعها إن لزم الأمر.الخيار يعود لك، يمكنك الاستمرار بتعقب المواضع
        // التي تأتي منها نتائج الإضافة المعلقة، أي مواضع الشيفرة البرمجية التي أتي منها الاستدعاء
        // وكذلك الوسائط التي مررتها للإضافة إن لزم الأمر
        var storedState = window.localStorage.getItem(APP_STORAGE_KEY);

        if(storedState) {
            appState = JSON.parse(storedState);
        }

        // التحقق من أننا نحتاج إلى حفظ الصورة التي أخذناها
        if(!appState.takingPicture && appState.imageUri) {
            document.getElementById("get-picture-result").src = appState.imageUri;
        }
        // cordova-android 5.1.0+ يمكننا الآن التحقق إن كانت هناك نتيجة في كائن الحدث، وهذا يتطلب الإصدار
        else if(appState.takingPicture && event.pendingResult) {
            // تعني "OK" التحقق من فشل أو نجاح استدعاء الإضافة، ثم استدعاء رد النداء المناسب. في حالة إضافة الكاميرا،
            // أن النتيجة ناجحة، وأي نتيجة أخرى ستُؤول كفشل
            if(event.pendingResult.pluginStatus === "OK") {
                //  تضع إضافة الكاميرا النتيجة نفسها في كائن الاستئناف، حيث يُمرر إلى   
                // getPictre() رد النداء الخاص بالنجاح والممرر إلى
                // وهكذا يمكننا تمريره إلى رد النداء نفسه. قد تعيد الإَضافات الأخرى نتائج أخرى. 
                // ارجع إلى توثيق الإضافة التي تستعمل لتتعلم كيف تؤول النتائج
                cameraSuccessCallback(event.pendingResult.result);
            } else {
                cameraFailureCallback(event.pendingResult.result);
            }
        }
    }
}

// getPicture() هاذان هما ردا النداء المُمرران إلى 
function cameraSuccessCallback(imageUri) {
    appState.takingPicture = false;
    appState.imageUri = imageUri;
    document.getElementById("get-picture-result").src = imageUri;
}

function cameraFailureCallback(error) {
    appState.takingPicture = false;
    console.log(error);
}

app.initialize();
</syntaxhighlight>ملف [[HTML]] المقابل:<syntaxhighlight lang="html">
<!DOCTYPE html>

<html>
    <head>
        <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
        <meta name="format-detection" content="telephone=no">
        <meta name="msapplication-tap-highlight" content="no">
        <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
        <link rel="stylesheet" type="text/css" href="css/index.css">
        <title>Cordova Android Lifecycle Example</title>
    </head>
    <body>
        <div class="app">
            <div>
                <img id="get-picture-result" />
            </div>
            <Button id="take-picture-button">Take Picture</button>
        </div>
        <script type="text/javascript" src="cordova.js"></script>
        <script type="text/javascript" src="js/index.js"></script>
    </body>
</html>
</syntaxhighlight>

=== اختبار دورة حياة الواجهة ===
يوفر أندرويد إعداد مطور البرامج لاختبار تدمير النشاط على ذاكرة منخفضة. قم بتمكين الضبط "عدم الاحتفاظ بالنشاطات" (Don't keep activities) في قائمة خيارات المطور (Developer Options) على جهازك أو على المحاكي لمحاكاة سيناريوهات الذاكرة المنخفضة. يجب عليك دائمًا إجراء بعض الاختبارات باستخدام هذا الإعداد وذلك للتأكد من أن التطبيق الخاص بك يحتفظ بحالته بشكل صحيح.

== انظر أيضًا ==
* [[Cordova/android upgrade|ترقية أندرويد]]
* [[Cordova/plugins android|تطوير الإضافات على منصة أندرويد]]
* [[Cordova/platform plugin versioning ref|إدارة إصدارات المنصات والإضافات]]
* [[Cordova/platforms ios|دليل التطوير على منصة iOS]]

== مصادر ==
* [https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html صفحة Android Platform Guide في توثيق كوردوفا الرسمي.]