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

لتهيئة تطبيقك لاستخدام الأماكن SDK لنظام التشغيل Android، اتبع هذه الخطوات. وهي مطلوبة لجميع التطبيقات التي تستخدم الأماكن SDK لنظام التشغيل Android.

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

1. مطلوب Android Studio Arctic Fox أو إصدار أحدث. في حال عدم إجراء ذلك من قبل، يمكنك تنزيله وتثبيته.
2. تأكّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي لنظام التشغيل Android أو إصدار أحدث في "استوديو Android".

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

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

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

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

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

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

   dependencies {
       implementation 'com.google.android.libraries.places:places:3.1.0'
   }
   

4. في ملف build.gradle على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية:

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

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

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

لتبسيط هذه المهمة، نقترح عليك استخدام Secrets Gradle Plugin for Android. لتثبيت المكون الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:

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

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

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

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. احفظ الملف وزامن مشروعك مع Gradle.
4. افتح local.properties في الدليل على مستوى مشروعك، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

   MAPS_API_KEY=YOUR_API_KEY
       

5. احفظ الملف.
6. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل android:value attribute على النحو التالي:

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

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

الخطوة الرابعة: تهيئة عميل واجهة برمجة تطبيقات الأماكن

ابدأ في إعداد حزمة تطوير البرامج (SDK) في تطبيق "الأماكن" لنظام التشغيل Android ضمن نشاط أو جزء على النحو الموضح في المثال التالي (لاحظ أنك تمرِّر مفتاح واجهة برمجة التطبيقات عند استدعاء Places.initialize()):

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

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

      

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

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

      

أنت الآن جاهز لبدء استخدام الأماكن SDK لنظام التشغيل Android!

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

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

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

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