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

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

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

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

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

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

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

    Kotlin

    plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.jetbrains.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.secrets.gradle.plugin) apply false
}

    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 {
    // ...
    alias(libs.plugins.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 من التحقّق من الملفات في نظام التحكّم في الإصدارات 
    MAPS_API_KEY=YOUR_API_KEY

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

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

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