المكوّن الإضافي Secrets Gradle

تنصح Google بشدة بعدم إدخال مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدارات. بدلاً من ذلك، يمكنك تخزينه في ملف secrets.properties محلي، والذي يقع في الدليل الجذري لمشروعك ولكن يتم استبعاده من التحكم في الإصدارات، ثم استخدام المكوّن الإضافي Secrets Gradle لنظام التشغيل Android لقراءة مفتاح واجهة برمجة التطبيقات.

يقرأ المكوّن الإضافي Secrets Gradle لأجهزة Android الرموز السرية، بما في ذلك مفتاح واجهة برمجة التطبيقات، من ملف خصائص لم يتم تسجيله في نظام التحكّم في الإصدارات. بعد ذلك، يعرض المكوّن الإضافي هذه السمات كمتغيّرات في فئة BuildConfig التي تم إنشاؤها بواسطة Gradle وفي ملف بيان Android.

للاطّلاع على مثال كامل على استخدام المكوّن الإضافي Secrets Gradle لأجهزة Android من أجل الوصول إلى مفتاح واجهة برمجة التطبيقات، يُرجى الاطّلاع على إعداد مشروع على "استوديو Android".

التثبيت والاستخدام

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android وتخزين مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

1. في استوديو Android، افتح ملف build.gradle.kts أو build.gradle ذي المستوى الأعلى وأضِف الرمز التالي إلى مجموعة plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وأضِف الرمز التالي إلى العنصر plugins.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. إذا كنت تستخدم "استوديو Android"، زامن مشروعك مع Gradle.
4. افتح ملف secrets.properties في الدليل ذي المستوى الأعلى، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك. تأكَّد من إضافة secrets.properties إلى ملف .gitignore (أو استبعاده من نظام التحكّم في الإصدارات) كي لا يتم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدارات.

   MAPS_API_KEY=YOUR_API_KEY

5. أنشئ ملف local.defaults.properties في الدليل ذي المستوى الأعلى، وهو المجلد نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

   MAPS_API_KEY=DEFAULT_API_KEY

   الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف secrets.properties لكي لا تفشل عمليات الإنشاء. قد يحدث ذلك في حال استنساخ التطبيق من نظام تحكّم في الإصدارات يحذف secrets.properties ولم يتم بعد إنشاء ملف secrets.properties محليًا لتوفير مفتاح واجهة برمجة التطبيقات.

6. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل السمة android:value على النحو التالي:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   ملاحظة: com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على واجهات برمجة تطبيقات متعددة مستندة إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android. لضمان التوافق مع الأنظمة القديمة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن لأي تطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وفي حال تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

7. في استوديو Android، افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وعدِّل السمة secrets. إذا لم تكن السمة secrets متوفّرة، أضِفها.

   عدِّل سمات المكوّن الإضافي لضبط propertiesFileName على "secrets.properties"، واضبط defaultPropertiesFileName على "local.defaults.properties"، واضبط أي سمات أخرى.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

الخطوات التالية

• يمكنك الاطّلاع على صفحة مشروع المكوّن الإضافي Secrets Gradle لأجهزة Android على GitHub.
• يمكنك الاطّلاع على إعداد مشروع في "استوديو Android" للحصول على مثال كامل على استخدام المكوّن الإضافي.