برای پیکربندی کردن برنامه‌تان جهت استفاده از «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android»، این مراحل را دنبال کنید. این کلیدها برای همه برنامه‌هایی که از «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android» استفاده می‌کنند الزامی است.
مرحله ۱: راه‌اندازی Android Studio
این سند محیط توسعه نرم‌افزار را بااستفاده از Android Studio Hedgehog و افزونه Android Gradle نسخه ۸.۲ شرح می‌دهد.
مرحله ۲. راه‌اندازی کیت توسعه نرم‌افزار
کتابخانه «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android» ازطریق مخزن Maven متعلق به Google دردسترس است. برای افزودن کیت توسعه نرم‌افزار به برنامه‌تان، کارهای زیر را انجام دهید:
- در فایل
settings.gradle.ktsسطح بالا، درگاه افزایه Gradle، مخزن Google Maven، و مخزن مرکزی Maven را در بلوکpluginManagementاضافه کنید. بلوکpluginManagementباید قبل‌از هر عبارت دیگری در اسکریپت ظاهر شود.pluginManagement { repositories { google() mavenCentral() gradlePluginPortal() } }
- در فایل
settings.gradle.ktsسطح بالا، مخزن Maven متعلق به Google و مخزن مرکزی Maven را در بلوکdependencyResolutionManagementاضافه کنید:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { google() mavenCentral() } }
-
در بخش
dependenciesفایلbuild.gradle.ktsدر سطح واحد، وابستگی‌ای به Places SDK for Android اضافه کنید: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:6.0.2") }
- در فایل
build.gradle.ktsسطح ماژول،compileSdkوminSdkرا روی مقادیر زیر تنظیم کنید:Groovy
android { compileSdk 34 defaultConfig { minSdk 23 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 23 // ... } }
- در بخش
buildFeaturesفایلbuild.gradleدر سطح ماژول، کلاسBuildConfigرا اضافه کنید که از آن برای دسترسی به مقادیر فراداده تعریف‌شده در ادامه این رویه استفاده می‌کنید:Groovy
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
مرحله ۳: کلید میانای API را به پروژه اضافه کنید
این بخش نحوه ذخیره کردن کلید میانای برنامه‌سازی کاربردی را شرح می‌دهد تا برنامه‌تان بتواند به‌طور ایمن به آن ارجاع دهد. نباید کلید میانای برنامه‌سازی کاربردی را در سیستم کنترل نسخه بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل secrets.properties در دایرکتوری ریشه پروژه‌تان ذخیره کنید و آن فایل را از کنترل نسخه مستثنی کنید. برای اطلاعات بیشتر درباره
فایل‌های ویژگی‌های Gradle، به
فایل‌های ویژگی‌های Gradle مراجعه کنید.
برای ساده کردن این کار، توصیه می‌کنیم از افزایه Secrets Gradle ویژه Android استفاده کنید.
برای نصب افزایه Secrets Gradle ویژه Android و ذخیره کلید میانای برنامه‌سازی کاربردی:
-
در Android Studio، فایل سطح بالای
build.gradle.ktsیاbuild.gradleرا باز کنید و کد زیر را به بلوکpluginsاضافه کنید.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
-
فایل
build.gradle.ktsیاbuild.gradleدر سطح ماژول را باز کنید و کد زیر را به عنصرpluginsاضافه کنید.Kotlin
plugins { id("com.android.application") // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { id 'com.android.application' // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
-
فایل
secrets.propertiesرا در دایرکتوری سطح بالا باز کنید، سپس کد زیر را اضافه کنید.YOUR_API_KEYرا با کلید میانای API خودتان جایگزین کنید. حتماًsecrets.propertiesرا به فایل.gitignoreخود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید.PLACES_API_KEY=YOUR_API_KEY
-
فایل
local.defaults.propertiesرا در دایرکتوری سطح بالا، همان پوشه فایلsecrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.PLACES_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه مکان پشتیبان‌گیری برای کلید میانای برنامه‌سازی کاربردی است تا اگر فایل
secrets.propertiesپیدا نشد، ساخت‌ها ناموفق نباشند. این مشکل زمانی رخ می‌دهد که برنامه را از سیستم کنترل نسخه‌ای شبیه‌سازی کنید کهsecrets.propertiesرا حذف می‌کند و هنوز فایلsecrets.propertiesرا به‌صورت محلی برای ارائه کلید میانای برنامه‌سازی کاربردی خود ایجاد نکرده‌اید. -
در 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 root directory (the same folder as the root 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 root directory (the same folder as the root 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" }
مرحله ۴. مقداردهی اولیه کارخواه Places API
برای مقداردهی اولیه Places SDK for Android در یک فعالیت یا قطعه، کلید API را هنگام فراخوانی
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)
جاوا
// 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);
اکنون آماده‌اید تا استفاده از Places SDK for Android را شروع کنید!
مرحله ۵: راه‌اندازی دستگاه Android
برای اجرای برنامه‌ای که از «کیت توسعه نرم‌افزار Places برای Android» استفاده می‌کند، باید آن را در دستگاه Android یا شبیه‌ساز Android که مبتنی بر Android نسخه ۶.۰ یا بالاتر است و Google API را دربرمی‌گیرد مستقر کنید.
- برای استفاده از دستگاه Android، دستورالعمل‌های اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
- برای استفاده از شبیه‌ساز Android، می‌توانید دستگاهی مجازی ایجاد کنید و شبیه‌ساز را بااستفاده از مدیر دستگاه که همراه با Android Studio ارائه می‌شود نصب کنید.