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

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

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

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

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

ملاحظة: يمكنك الاطّلاع على مستندات المكوّن الإضافي Secrets Gradle لأجهزة Android على GitHub لمعرفة أحدث متطلبات النظام وتعليمات التثبيت.

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

1. في Android Studio، افتح ملف build.gradle.kts أو build.gradle الأولي وأضِف الرمز البرمجي التالي إلى عنصر dependencies ضمن buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

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

   Kotlin

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

   Groovy

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

3. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، تأكَّد من ضبط targetSdk وcompileSdk على 34.
4. مزامنة مشروعك مع Gradle
5. افتح ملف secrets.properties في الدليل من المستوى الأعلى، ثم أضِف الرمز التالي: استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. عليك تخزين مفتاحك في هذا الملف لأنّه تم استبعاد secrets.properties من التحقّق من الملفات في نظام التحكّم في الإصدارات
   ملاحظة: إذا لم يكن ملف secrets.properties موجودًا، أنشِئه في المجلد نفسه الذي يتضمّن ملف local.properties.

   MAPS_API_KEY=YOUR_API_KEY

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

   ملاحظة: أدخِل الرمز كما هو معروض. لا تستبدِل DEFAULT_API_KEY بمفتاح واجهة برمجة التطبيقات.

   MAPS_API_KEY=DEFAULT_API_KEY

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

7. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل android:value attribute. إذا لم تكن علامة <meta-data> متوفّرة، أنشئها كعنصر تابع لعلامة <application>.

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

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

8. في Android Studio، افتح ملف 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 same folder as the 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 same folder as the 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" للحصول على مثال كامل لاستخدام المكوّن الإضافي.