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

ملاحظة: يعتمد الإصدار 2.0.0 والإصدارات الأحدث من "حزمة تطوير برامج الأماكن" لنظام التشغيل Android على AndroidX. واعتبارًا من هذا الإصدار، لن تعود مكتبة الدعم القديمة متاحة. للحفاظ على التوافق، يجب نقل مشاريعك إلى AndroidX.

لضبط تطبيقك لاستخدام Places SDK for Android، اتّبِع الخطوات التالية. وهي مطلوبة لجميع التطبيقات التي تستخدم حزمة تطوير البرامج Places SDK لنظام التشغيل Android.

الخطوة 1: إعداد Android Studio

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

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

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

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

1. في ملف settings.gradle.kts ذي المستوى الأعلى، أدرِج بوابة مكوّن Gradle الإضافي ومستودع Maven من Google ومستودع Maven المركزي ضمن الحظر pluginManagement. يجب أن يظهر الحظر pluginManagement قبل أي عبارات أخرى في النص البرمجي.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. في ملف settings.gradle.kts ذي المستوى الأعلى، أدرِج مستودع Maven من Google ومستودع Maven المركزي ضمن الحظر dependencyResolutionManagement:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. في قسم dependencies من ملف build.gradle.kts على مستوى الوحدة، أضِف مصدر اعتمادية إلى حزمة تطوير البرامج (SDK) الخاصة بـ Places API لنظام التشغيل Android:

   ملاحظة: يتطلّب الإصدار 3.5.0 من Places SDK لنظام التشغيل Androidkotlin-bom 1.8.0 أو إصدارًا أحدث. لمزيد من المعلومات حول التبعية kotlin-bom، يُرجى الاطّلاع على استخدام أحدث إصدار من kotlin-stdlib في التبعيات المتعدية.

   Groovy

   dependencies {
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
       implementation("com.google.android.libraries.places:places:3.5.0")
   }

   Kotlin

             dependencies {
   
       // Places and Maps SDKs
       implementation("com.google.android.libraries.places:places:4.3.1")
   }

4. في ملف build.gradle.kts على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية:
   ملاحظة: تأكَّد من ضبط compileSdk على 34 أو أعلى، وضبط minSdk على 23 أو أعلى.

   Groovy

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

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 23
           // ...
       }
   }

5. في قسم buildFeatures من ملف build.gradle على مستوى الوحدة، أضِف الفئة BuildConfig التي تستخدمها للوصول إلى قيم البيانات الوصفية المحدّدة لاحقًا في هذا الإجراء:

   Groovy

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

   Kotlin

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

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

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

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة 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.

   PLACES_API_KEY=YOUR_API_KEY

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

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

   PLACES_API_KEY=DEFAULT_API_KEY

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

7. في 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"
   }
           

الخطوة 4: إعداد برنامج Places API

يمكنك إعداد حزمة تطوير البرامج Places SDK for Android ضِمن نشاط أو جزء. عليك أولاً تحديد إصدار حزمة تطوير البرامج (SDK) الذي تريد استخدامه: حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة 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.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.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);
    

ملاحظة مهمة: لا تُضِف مفاتيح واجهة برمجة التطبيقات مباشرةً إلى رمز التطبيق. في بيئات الإنتاج، ننصحك باستخدام آلية آمنة لإدارة مفاتيح واجهة برمجة التطبيقات.

أنت الآن جاهز لبدء استخدام حزمة تطوير البرامج Places SDK for Android.

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

لتشغيل تطبيق يستخدم Places SDK for Android، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 5.0 من نظام التشغيل Android أو إصدار أحدث ويتضمّن واجهات Google API.

• لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
• لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير الأجهزة الافتراضية لنظام التشغيل Android المضمّن في "استوديو Android".
  ملاحظة: إذا اخترت استخدام محاكي Android، تأكَّد من اختيار جهاز يظهر عليه رمز Play، ، ضمن عمود متجر Play. يشير هذا الرمز إلى أنّ هذه الملفات الشخصية متوافقة تمامًا مع CTS ويمكنها استخدام صور النظام التي تتضمّن تطبيق "متجر Play":

  

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

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