المكوّن الإضافي 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 (أو استبعاده من نظام التحكّم في الإصدار بطريقة أخرى) حتى لا يتم تسجيل مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدار.
   ملاحظة: إذا لم يكن ملف secrets.properties موجودًا، أنشِئه في المجلد نفسه الذي يحتوي على ملف local.properties.

   MAPS_API_KEY=YOUR_API_KEY

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

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

   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. يسمح هذا الاسم القديم بالمصادقة على Android Maps API v2 فقط. لا يمكن للتطبيق تحديد سوى أحد أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كلا الاسمين، ستعرض واجهة برمجة التطبيقات استثناءً.

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 Plugin لأجهزة Android على GitHub.
• للاطّلاع على مثال كامل لاستخدام المكوّن الإضافي، يُرجى الاطّلاع على مقالة إعداد مشروع في "استوديو Android".