إعداد مشروع في "استوديو Android"

لإعداد تطبيقك لاستخدام حزمة تطوير برامج الأماكن لأجهزة Android، اتبع الخطوات التالية. وهي مطلوبة لجميع التطبيقات التي تستخدم حزمة تطوير برامج الأماكن لأجهزة Android.

الخطوة 1: إعداد "استوديو Android"

يوضّح هذا المستند بيئة تطوير باستخدام Android Studio Hedgehog ومكوّن Android Gradle الإضافي الإصدار 8.2.

الخطوة 2. إعداد حزمة تطوير البرامج (SDK)

تتوفّر مكتبة تطوير برامج الأماكن لأجهزة Android من خلال مستودع Maven من Google. لإضافة حزمة SDK إلى تطبيقك، عليك اتّباع الخطوات التالية:

  1. في ملف settings.gradle ذي المستوى الأعلى، ضمِّن بوابة المكوّنات الإضافية في Gradle ومستودع Google Maven ومستودع Maven المركزي ضمن الجزء pluginManagement. يجب أن تظهر مجموعة pluginManagement قبل أي عبارات أخرى في النص البرمجي.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. في ملف settings.gradle ذي المستوى الأعلى، ضمِّن مستودع Maven من Google ومستودع Maven المركزي ضمن المجموعة dependencyResolutionManagement:
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. في القسم dependencies في ملف build.gradle على مستوى الوحدة، أضِف تبعية إلى حزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل Android:

    رائع

    dependencies {
        // If updating kotlin-bom version number above, also edit project-level build.gradle definition of $kotlin_version variable
        implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
        implementation 'com.google.android.libraries.places:places:3.3.0'
    }

    Kotlin

    dependencies {
        implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
        implementation("com.google.android.libraries.places:places:3.3.0")
    }
  4. في ملف build.gradle على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية:

    رائع

    android {
        compileSdk 34
    
        defaultConfig {
            minSdk 21
            // ...
        }
    }

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 21
            // ...
        }
    }
  5. في القسم buildFeatures من ملف build.gradle على مستوى الوحدة، أضِف الفئة BuildConfig التي تستخدمها للوصول إلى قيم البيانات الوصفية التي تم تحديدها لاحقًا في هذا الإجراء:

    رائع

    android {
      // ...
      buildFeatures {
        buildConfig true
        // ...
      }
    }

    Kotlin

    android {
      // ...
      buildFeatures {
        buildConfig = true
        // ...
      }
    }

الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

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

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secret Gradle الإضافي لنظام Android.

لتثبيت المكوّن الإضافي Secret Gradle الإضافي لنظام التشغيل Android في مشروع "خرائط Google"، اتَّبِع الخطوات التالية:

  1. في "استوديو Android"، افتح ملف build.gradle أو build.gradle.kts ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

    رائع

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

    Kotlin

    buildscript {
        dependencies {
            classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
        }
    }
    
  2. افتح ملف build.gradle على مستوى الوحدة وأضِف الرمز التالي إلى العنصر plugins.

    رائع

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. في ملف build.gradle على مستوى الوحدة، تأكَّد من ضبط targetSdk وcompileSdk على 34.
  4. احفظ الملف وزامِن مشروعك مع Gradle.
  5. افتح ملف secrets.properties في دليل المستوى الأعلى، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. يمكنك تخزين مفتاحك في هذا الملف لأنّه تم استبعاد secrets.properties من التسجيل في نظام التحكّم في الإصدار.
    PLACES_API_KEY=YOUR_API_KEY
  6. احفظ الملف.
  7. أنشِئ ملف local.defaults.properties في دليل المستوى الأعلى، أي الملف نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

    PLACES_API_KEY=DEFAULT_API_KEY

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

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

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

    رائع

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

الخطوة 4. إعداد عميل Places API

يمكنك إعداد حزمة تطوير برامج الأماكن لأجهزة Android ضمن نشاط أو جزء. عليك أولاً تحديد إصدار حزمة SDK المطلوب استخدامه: حزمة تطوير برامج الأماكن لنظام التشغيل Android أو حزمة SDK للأماكن لنظام التشغيل Android (جديد). للاطّلاع على مزيد من المعلومات حول إصدارات المنتجات، يُرجى الاطّلاع على اختيار إصدار حزمة تطوير البرامج (SDK).

يوضّح المثال التالي كيفية إعداد حزمة تطوير البرامج (SDK) لكلا الإصدارين.

حزمة تطوير برامج الأماكن لأجهزة Android (جديدة)

مرِّر مفتاح واجهة برمجة التطبيقات عند طلب Places.initializeWithNewPlacesApiEnabled():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

حزمة تطوير برامج الأماكن لأجهزة Android

مرِّر مفتاح واجهة برمجة التطبيقات عند طلب Places.initialize():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initialize(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initialize(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

أنت الآن جاهز لبدء استخدام حزمة تطوير برامج الأماكن لأجهزة Android!

الخطوة 5: إعداد جهاز Android

لتشغيل تطبيق يستخدم "حزمة تطوير برامج الأماكن" لنظام التشغيل Android، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 4.0 من نظام التشغيل Android أو الإصدارات الأحدث ويتضمّن Google APIs.

  • لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
  • لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير جهاز Android الافتراضي (AVD) المتوفّر مع "استوديو Android".

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

بعد ضبط مشروعك، يمكنك استكشاف نماذج التطبيقات.