لضبط تطبيقك على استخدام حزمة تطوير برامج الأماكن لأجهزة Android، اتبع الخطوات التالية الخطوات. وتكون مطلوبة لجميع التطبيقات التي تستخدم حزمة تطوير برامج الأماكن لنظام التشغيل Android.
الخطوة 1: إعداد "استوديو Android"
تصف هذه الوثيقة بيئة تطوير تستخدم Android Studio Hedgehog المكوّن الإضافي لنظام Gradle المتوافق مع Android الإصدار 8.2.
الخطوة 2: إعداد حزمة تطوير البرامج (SDK)
تتوفر حزمة تطوير برامج الأماكن لأجهزة Android من خلال مستودع Maven من Google إلى أضِف حزمة تطوير البرامج (SDK) إلى تطبيقك، اتّبِع الخطوات التالية:
- في ملف
settings.gradle
ذي المستوى الأعلى، ضمِّن بوابة المكوّنات الإضافية في Gradle، مستودع Google Maven ومستودع Maven المركزي ضمن جزءpluginManagement
. جزءpluginManagement
قبل أي عبارات أخرى في النص البرمجي.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- في ملف
settings.gradle
ذي المستوى الأعلى، ضمِّن مستودع Maven من Google ومستودع Maven المركزي ضمن مجموعةdependencyResolutionManagement
:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
-
في
dependencies
في ملفbuild.gradle
على مستوى الوحدة، أضِف تبعية. إلى حزمة تطوير برامج الأماكن لأجهزة Android:Groovy
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.5.0") }
- في ملف
build.gradle
على مستوى الوحدة، اضبطcompileSdk
وminSdk
إلى القيم التالية:Groovy
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
- في القسم
buildFeatures
من ملفbuild.gradle
على مستوى الوحدة، أضِف الفئةBuildConfig
التي تستخدمها للوصول إلى قيم البيانات الوصفية المحدّدة لاحقًا. في هذا الإجراء:Groovy
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع
يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يمكن الرجوع إليه بشكل آمن من خلال
تطبيقك. يجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصحك
تخزينه في ملف secrets.properties
، الموجود في الدليل الجذري
مشروعك. لمزيد من المعلومات عن ملف secrets.properties
، يمكنك الاطّلاع على
ملفات خصائص Gradle:
لتبسيط هذه المهمة، نوصيك باستخدام المكوّن الإضافي السري لنظام Gradle المتوافق مع Android
لتثبيت مكوّن Secrets Gradle الإضافي لنظام التشغيل Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:
-
في "استوديو Android"، افتح
build.gradle
أوbuild.gradle.kts
المستوى الأعلى. وإضافة التعليمة البرمجية التالية إلى العنصرdependencies
ضمنbuildscript
Groovy
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") } }
-
افتح ملف
build.gradle
على مستوى الوحدة وأضِف الرمز التالي إلى العنصرplugins
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- وفي ملف
build.gradle
على مستوى الوحدة، تأكد من أنtargetSdk
تَمَّ ضَبْطُcompileSdk
عَلَى 34. - احفظ الملف، مزامنة مشروعك مع Gradle
-
افتح ملف
secrets.properties
في دليل المستوى الأعلى، ثم أضِف الملف الرمز التالي. استبدِلYOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات الخاص بك. تخزين مفتاحك في هذا الملف لأنّه تم استبعادsecrets.properties
من التحقق من عنصر تحكّم الإصدار .PLACES_API_KEY=YOUR_API_KEY
- احفظ الملف.
-
أنشئ الملف
local.defaults.properties
في دليل المستوى الأعلى، بالطريقة نفسها كملفsecrets.properties
، ثم أضف الرمز التالي.PLACES_API_KEY=DEFAULT_API_KEY
الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات إذا كان لم يتم العثور على ملف
secrets.properties
، لذا لا تفشل عمليات الإنشاء. يمكن أن يحدث هذا إذا استنساخ التطبيق من نظام تحكم في الإصدار يحذفsecrets.properties
لم تنشئ بعد ملفsecrets.properties
محليًا لتقديم مفتاح واجهة برمجة التطبيقات. - احفظ الملف.
-
في "استوديو Android"، افتح
build.gradle
على مستوى الوحدة أوbuild.gradle.kts
وعدِّل السمةsecrets
. إذا كانت لم يتم العثور على سمة واحدة (secrets
). يُرجى إضافتها.عدِّل خصائص المكوِّن الإضافي لضبط
propertiesFileName
علىsecrets.properties
، ضبط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" // 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 { // 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" // 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) المطلوب استخدامه: حزمة Places 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.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 يستند إلى الإصدار 5.0 من نظام التشغيل Android أو الإصدارات الأحدث ويتضمن Google APIs.
- لاستخدام جهاز Android، يُرجى اتّباع التعليمات الواردة في تشغيل التطبيقات على جهاز
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال أداة إدارة الأجهزة الافتراضية التي تعمل بنظام التشغيل Android (AVD) المتوفّرة ضمن "استوديو Android"