این صفحه نحوه پیکربندی یک پروژه Android Studio را برای استفاده از Maps SDK برای Android بدون استفاده از الگوی Google Maps که در Quickstart به تفصیل آمده است، شرح میدهد.
الگوی Google Maps به طور خودکار یک نقشه اولیه را به پروژه جدید Android Studio پیکربندی و اضافه می کند. با این حال، میتوانید نقشهای را نیز به پروژه اندروید اضافه کنید که از قالب Android Studio متفاوتی استفاده میکند. برای انجام این کار، باید پروژه خود را به صورت دستی پیکربندی کنید و سپس نقشه را اضافه کنید .
مرحله 1: Android Studio را راه اندازی کنید
این سند یک محیط توسعه را با استفاده از Android Studio Hedgehog و افزونه Android Gradle نسخه 8.2 توصیف می کند.
مرحله 2. SDK را تنظیم کنید
کتابخانه Maps SDK برای Android از طریق مخزن Maven Google در دسترس است. برای افزودن SDK به برنامه خود، موارد زیر را انجام دهید:
- در فایل
settings.gradle.kts
سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی Maven را در بلوکpluginManagement
قرار دهید. بلوکpluginManagement
باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- در فایل سطح بالای
settings.gradle.kts
خود، مخزن Maven Google و مخزن مرکزی Maven را در بلوکdependencyResolutionManagement
قرار دهید:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود، وابستگی خدمات Google Play را برای Maps SDK برای Android اضافه کنید.کاتلین
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
شیار
dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:19.0.0" }
- در فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود،compileSdk
وminSdk
را روی مقادیر زیر تنظیم کنید:کاتلین
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
شیار
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
- در بخش
buildFeatures
فایلbuild.gradle.kts
یاbuild.gradle
در سطح ماژول، کلاسBuildConfig
را اضافه کنید، که می توانید از آن برای دسترسی به مقادیر فراداده تعریف شده در این روش استفاده کنید:کاتلین
android { // ... buildFeatures { buildConfig = true // ... } }
شیار
android { // ... buildFeatures { buildConfig true // ... } }
مرحله 3: کلید API خود را به پروژه اضافه کنید
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند به طور ایمن توسط برنامه شما ارجاع داده شود. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می کنیم آن را در فایل secrets.properties
که در فهرست اصلی پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties
، به فایلهای خصوصیات Gradle مراجعه کنید.
برای سادهسازی این کار، توصیه میکنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.
برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:
- در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
سطح بالای خود را باز کنید و کد زیر را به عنصرdependencies
در زیرbuildscript
اضافه کنید.کاتلین
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
شیار
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
- فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود را باز کنید و کد زیر را به عنصرplugins
اضافه کنید.کاتلین
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
شیار
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول، مطمئن شوید کهtargetSdk
وcompileSdk
روی 34 تنظیم شده اند. - فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
- فایل
secrets.properties
را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزینYOUR_API_KEY
کنید. کلید خود را در این فایل ذخیره کنید زیراsecrets.properties
از بررسی سیستم کنترل نسخه حذف شده است.MAPS_API_KEY=YOUR_API_KEY
- فایل را ذخیره کنید.
فایل
local.defaults.properties
را در پوشه سطح بالای خود، همان پوشه فایلsecrets.properties
ایجاد کنید و سپس کد زیر را اضافه کنید.MAPS_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل
secrets.properties
است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه کهsecrets.properties
حذف می کند و هنوز فایلsecrets.properties
را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.- فایل را ذخیره کنید.
- در فایل
AndroidManifest.xml
خود، بهcom.google.android.geo.API_KEY
بروید وandroid:value attribute
به روز کنید. اگر تگ<meta-data>
وجود ندارد، آن را به عنوان فرزند تگ<application>
ایجاد کنید.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
توجه:
com.google.android.geo.API_KEY
نام ابرداده توصیه شده برای کلید API است. کلیدی با این نام میتواند برای احراز هویت چندین API مبتنی بر نقشههای Google در پلتفرم Android، از جمله Maps SDK برای Android استفاده شود. برای سازگاری به عقب، API از نامcom.google.android.maps.v2.API_KEY
نیز پشتیبانی می کند. این نام قدیمی فقط به Android Maps API نسخه 2 امکان احراز هویت را می دهد. یک برنامه کاربردی می تواند تنها یکی از نام های ابرداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، API یک استثنا ایجاد می کند. در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود را باز کنید و ویژگیsecrets
را ویرایش کنید. اگر ویژگیsecrets
وجود ندارد، آن را اضافه کنید.ویژگی های افزونه را ویرایش کنید تا
propertiesFileName
رویsecrets.properties
تنظیم کنید،defaultPropertiesFileName
رویlocal.defaults.properties
تنظیم کنید و هر ویژگی دیگری را تنظیم کنید.کاتلین
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.*" }
شیار
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: مانیفست برنامه را به روز کنید
این بخش تنظیماتی را برای افزودن به فایل AndroidManifest.xml
شما شرح می دهد.
شماره نسخه خدمات Google Play
اعلان زیر را در عنصر application
اضافه کنید. این نسخه خدمات Google Play را که برنامه با آن کامپایل شده است جاسازی می کند.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
مجوز مکان
اگر برنامه شما نیاز به دسترسی به موقعیت مکانی کاربر دارد، باید مجوز مکان را در فایل AndroidManifest.xml
خود درخواست کنید. گزینهها ACCESS_FINE_LOCATION
هستند که مکان دقیق دستگاه را ارائه میکند و ACCESS_COARSE_LOCATION
که دقت کمتری دارد. برای جزئیات، به راهنمای داده های مکان مراجعه کنید.
برای درخواست مجوز ACCESS_FINE_LOCATION
، این کد را به عنصر manifest
اضافه کنید:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
مجوز ذخیره سازی خارجی
اگر نسخه 8.3 یا جدیدتر SDK خدمات Google Play را هدف قرار می دهید، به مجوز WRITE_EXTERNAL_STORAGE
نیاز ندارید. اگر نسخههای قبلی SDK خدمات Google Play را هدف قرار میدهید، باید مجوز WRITE_EXTERNAL_STORAGE را در عنصر manifest
درخواست کنید.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
کتابخانه Apache HTTP Legacy
اگر از com.google.android.gms:play-services-maps:16.0.0
یا پایین تر استفاده می کنید و برنامه شما سطح API 28 (Android 9.0) یا بالاتر را هدف قرار می دهد، باید اعلان زیر را در عنصر <application>
وارد کنید. از AndroidManifest.xml
. در غیر این صورت، از این اعلامیه صرف نظر کنید.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
مرحله 5: یک دستگاه Android را راه اندازی کنید
برای اجرای برنامهای که از Maps SDK برای Android استفاده میکند، باید آن را در دستگاه Android یا شبیهساز Android که مبتنی بر Android نسخه 5.0 یا بالاتر است و شامل APIهای Google است، مستقر کنید.
- برای استفاده از دستگاه Android، دستورالعملهای موجود در اجرای برنامهها در دستگاه سختافزاری را دنبال کنید.
- برای استفاده از شبیه ساز اندروید، می توانید با استفاده از مدیریت دستگاه مجازی اندروید (AVD) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
مرحله 6: به صورت اختیاری پشتیبانی از Play Service را بررسی کنید
Maps SDK برای Android نیاز دارد که دستگاهی که برنامه خود را روی آن نصب میکنید، سرویسهای Google Play را نصب کرده باشد. Google روشی را ارائه می دهد که می توانید از برنامه خود برای بررسی آن تماس بگیرید. برای اطلاعات بیشتر، به بررسی نصب سرویسهای Google Play مراجعه کنید.
مراحل بعدی
هنگامی که پروژه شما پیکربندی شد، می توانید یک نقشه اضافه کنید .
،این صفحه نحوه پیکربندی یک پروژه Android Studio را برای استفاده از Maps SDK برای Android بدون استفاده از الگوی Google Maps که در Quickstart به تفصیل آمده است، شرح میدهد.
الگوی Google Maps به طور خودکار یک نقشه اولیه را به پروژه جدید Android Studio پیکربندی و اضافه می کند. با این حال، میتوانید نقشهای را نیز به پروژه اندروید اضافه کنید که از قالب Android Studio متفاوتی استفاده میکند. برای انجام این کار، باید پروژه خود را به صورت دستی پیکربندی کنید و سپس نقشه را اضافه کنید .
مرحله 1: Android Studio را راه اندازی کنید
این سند یک محیط توسعه را با استفاده از Android Studio Hedgehog و افزونه Android Gradle نسخه 8.2 توصیف می کند.
مرحله 2. SDK را تنظیم کنید
کتابخانه Maps SDK برای Android از طریق مخزن Maven Google در دسترس است. برای افزودن SDK به برنامه خود، موارد زیر را انجام دهید:
- در فایل
settings.gradle.kts
سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی Maven را در بلوکpluginManagement
قرار دهید. بلوکpluginManagement
باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- در فایل سطح بالای
settings.gradle.kts
خود، مخزن Maven Google و مخزن مرکزی Maven را در بلوکdependencyResolutionManagement
قرار دهید:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود، وابستگی خدمات Google Play را برای Maps SDK برای Android اضافه کنید.کاتلین
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
شیار
dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:19.0.0" }
- در فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود،compileSdk
وminSdk
را روی مقادیر زیر تنظیم کنید:کاتلین
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
شیار
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
- در بخش
buildFeatures
فایلbuild.gradle.kts
یاbuild.gradle
در سطح ماژول، کلاسBuildConfig
را اضافه کنید، که می توانید از آن برای دسترسی به مقادیر فراداده تعریف شده در این روش استفاده کنید:کاتلین
android { // ... buildFeatures { buildConfig = true // ... } }
شیار
android { // ... buildFeatures { buildConfig true // ... } }
مرحله 3: کلید API خود را به پروژه اضافه کنید
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند به طور ایمن توسط برنامه شما ارجاع داده شود. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می کنیم آن را در فایل secrets.properties
که در فهرست اصلی پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties
، به فایلهای خصوصیات Gradle مراجعه کنید.
برای سادهسازی این کار، توصیه میکنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.
برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:
- در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
سطح بالای خود را باز کنید و کد زیر را به عنصرdependencies
در زیرbuildscript
اضافه کنید.کاتلین
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
شیار
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
- فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود را باز کنید و کد زیر را به عنصرplugins
اضافه کنید.کاتلین
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
شیار
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول، مطمئن شوید کهtargetSdk
وcompileSdk
روی 34 تنظیم شده اند. - فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
- فایل
secrets.properties
را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزینYOUR_API_KEY
کنید. کلید خود را در این فایل ذخیره کنید زیراsecrets.properties
از بررسی سیستم کنترل نسخه حذف شده است.MAPS_API_KEY=YOUR_API_KEY
- فایل را ذخیره کنید.
فایل
local.defaults.properties
را در پوشه سطح بالای خود، همان پوشه فایلsecrets.properties
ایجاد کنید و سپس کد زیر را اضافه کنید.MAPS_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل
secrets.properties
است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه کهsecrets.properties
حذف می کند و هنوز فایلsecrets.properties
را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.- فایل را ذخیره کنید.
- در فایل
AndroidManifest.xml
خود، بهcom.google.android.geo.API_KEY
بروید وandroid:value attribute
به روز کنید. اگر تگ<meta-data>
وجود ندارد، آن را به عنوان فرزند تگ<application>
ایجاد کنید.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
توجه:
com.google.android.geo.API_KEY
نام ابرداده توصیه شده برای کلید API است. کلیدی با این نام میتواند برای احراز هویت چندین API مبتنی بر نقشههای Google در پلتفرم Android، از جمله Maps SDK برای Android استفاده شود. برای سازگاری به عقب، API از نامcom.google.android.maps.v2.API_KEY
نیز پشتیبانی می کند. این نام قدیمی فقط به Android Maps API نسخه 2 امکان احراز هویت را می دهد. یک برنامه کاربردی می تواند تنها یکی از نام های ابرداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، API یک استثنا ایجاد می کند. در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود را باز کنید و ویژگیsecrets
را ویرایش کنید. اگر ویژگیsecrets
وجود ندارد، آن را اضافه کنید.ویژگی های افزونه را ویرایش کنید تا
propertiesFileName
رویsecrets.properties
تنظیم کنید،defaultPropertiesFileName
رویlocal.defaults.properties
تنظیم کنید و هر ویژگی دیگری را تنظیم کنید.کاتلین
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.*" }
شیار
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: مانیفست برنامه را به روز کنید
این بخش تنظیماتی را برای افزودن به فایل AndroidManifest.xml
شما شرح می دهد.
شماره نسخه خدمات Google Play
اعلان زیر را در عنصر application
اضافه کنید. این نسخه خدمات Google Play را که برنامه با آن کامپایل شده است جاسازی می کند.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
مجوز مکان
اگر برنامه شما نیاز به دسترسی به موقعیت مکانی کاربر دارد، باید مجوز مکان را در فایل AndroidManifest.xml
خود درخواست کنید. گزینهها ACCESS_FINE_LOCATION
هستند که مکان دقیق دستگاه را ارائه میکند و ACCESS_COARSE_LOCATION
که دقت کمتری دارد. برای جزئیات، به راهنمای داده های مکان مراجعه کنید.
برای درخواست مجوز ACCESS_FINE_LOCATION
، این کد را به عنصر manifest
اضافه کنید:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
مجوز ذخیره سازی خارجی
اگر نسخه 8.3 یا جدیدتر SDK خدمات Google Play را هدف قرار می دهید، به مجوز WRITE_EXTERNAL_STORAGE
نیاز ندارید. اگر نسخههای قبلی SDK خدمات Google Play را هدف قرار میدهید، باید مجوز WRITE_EXTERNAL_STORAGE را در عنصر manifest
درخواست کنید.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
کتابخانه Apache HTTP Legacy
اگر از com.google.android.gms:play-services-maps:16.0.0
یا پایین تر استفاده می کنید و برنامه شما سطح API 28 (Android 9.0) یا بالاتر را هدف قرار می دهد، باید اعلان زیر را در عنصر <application>
وارد کنید. از AndroidManifest.xml
. در غیر این صورت، از این اعلامیه صرف نظر کنید.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
مرحله 5: یک دستگاه Android را راه اندازی کنید
برای اجرای برنامهای که از Maps SDK برای Android استفاده میکند، باید آن را در دستگاه Android یا شبیهساز Android که مبتنی بر Android نسخه 5.0 یا بالاتر است و شامل APIهای Google است، مستقر کنید.
- برای استفاده از دستگاه Android، دستورالعملهای موجود در اجرای برنامهها در دستگاه سختافزاری را دنبال کنید.
- برای استفاده از شبیه ساز اندروید، می توانید با استفاده از مدیریت دستگاه مجازی اندروید (AVD) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
مرحله 6: به صورت اختیاری پشتیبانی از Play Service را بررسی کنید
Maps SDK برای Android نیاز دارد که دستگاهی که برنامه خود را روی آن نصب میکنید، سرویسهای Google Play را نصب کرده باشد. Google روشی را ارائه می دهد که می توانید از برنامه خود برای بررسی آن تماس بگیرید. برای اطلاعات بیشتر، به بررسی نصب سرویسهای Google Play مراجعه کنید.
مراحل بعدی
هنگامی که پروژه شما پیکربندی شد، می توانید یک نقشه اضافه کنید .
،این صفحه نحوه پیکربندی یک پروژه Android Studio را برای استفاده از Maps SDK برای Android بدون استفاده از الگوی Google Maps که در Quickstart به تفصیل آمده است، شرح میدهد.
الگوی Google Maps به طور خودکار یک نقشه اولیه را به پروژه جدید Android Studio پیکربندی و اضافه می کند. با این حال، میتوانید نقشهای را نیز به پروژه اندروید اضافه کنید که از قالب Android Studio متفاوتی استفاده میکند. برای انجام این کار، باید پروژه خود را به صورت دستی پیکربندی کنید و سپس نقشه را اضافه کنید .
مرحله 1: Android Studio را راه اندازی کنید
این سند یک محیط توسعه را با استفاده از Android Studio Hedgehog و افزونه Android Gradle نسخه 8.2 توصیف می کند.
مرحله 2. SDK را تنظیم کنید
کتابخانه Maps SDK برای Android از طریق مخزن Maven Google در دسترس است. برای افزودن SDK به برنامه خود، موارد زیر را انجام دهید:
- در فایل
settings.gradle.kts
سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی Maven را در بلوکpluginManagement
قرار دهید. بلوکpluginManagement
باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- در فایل سطح بالای
settings.gradle.kts
خود، مخزن Maven Google و مخزن مرکزی Maven را در بلوکdependencyResolutionManagement
قرار دهید:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود، وابستگی خدمات Google Play را برای Maps SDK برای Android اضافه کنید.کاتلین
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
شیار
dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:19.0.0" }
- در فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود،compileSdk
وminSdk
را روی مقادیر زیر تنظیم کنید:کاتلین
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
شیار
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
- در بخش
buildFeatures
فایلbuild.gradle.kts
یاbuild.gradle
در سطح ماژول، کلاسBuildConfig
را اضافه کنید، که می توانید از آن برای دسترسی به مقادیر فراداده تعریف شده در این روش استفاده کنید:کاتلین
android { // ... buildFeatures { buildConfig = true // ... } }
شیار
android { // ... buildFeatures { buildConfig true // ... } }
مرحله 3: کلید API خود را به پروژه اضافه کنید
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند به طور ایمن توسط برنامه شما ارجاع داده شود. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می کنیم آن را در فایل secrets.properties
که در فهرست اصلی پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties
، به فایلهای خصوصیات Gradle مراجعه کنید.
برای سادهسازی این کار، توصیه میکنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.
برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:
- در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
سطح بالای خود را باز کنید و کد زیر را به عنصرdependencies
در زیرbuildscript
اضافه کنید.کاتلین
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
شیار
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
- فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود را باز کنید و کد زیر را به عنصرplugins
اضافه کنید.کاتلین
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
شیار
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول، مطمئن شوید کهtargetSdk
وcompileSdk
روی 34 تنظیم شده اند. - فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
- فایل
secrets.properties
را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزینYOUR_API_KEY
کنید. کلید خود را در این فایل ذخیره کنید زیراsecrets.properties
از بررسی سیستم کنترل نسخه حذف شده است.MAPS_API_KEY=YOUR_API_KEY
- فایل را ذخیره کنید.
فایل
local.defaults.properties
را در پوشه سطح بالای خود، همان پوشه فایلsecrets.properties
ایجاد کنید و سپس کد زیر را اضافه کنید.MAPS_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل
secrets.properties
است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه کهsecrets.properties
حذف می کند و هنوز فایلsecrets.properties
را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.- فایل را ذخیره کنید.
- در فایل
AndroidManifest.xml
خود، بهcom.google.android.geo.API_KEY
بروید وandroid:value attribute
به روز کنید. اگر تگ<meta-data>
وجود ندارد، آن را به عنوان فرزند تگ<application>
ایجاد کنید.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
توجه:
com.google.android.geo.API_KEY
نام ابرداده توصیه شده برای کلید API است. کلیدی با این نام میتواند برای احراز هویت چندین API مبتنی بر نقشههای Google در پلتفرم Android، از جمله Maps SDK برای Android استفاده شود. برای سازگاری به عقب، API از نامcom.google.android.maps.v2.API_KEY
نیز پشتیبانی می کند. این نام قدیمی فقط به Android Maps API نسخه 2 امکان احراز هویت را می دهد. یک برنامه کاربردی می تواند تنها یکی از نام های ابرداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، API یک استثنا ایجاد می کند. در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود را باز کنید و ویژگیsecrets
را ویرایش کنید. اگر ویژگیsecrets
وجود ندارد، آن را اضافه کنید.ویژگی های افزونه را ویرایش کنید تا
propertiesFileName
رویsecrets.properties
تنظیم کنید،defaultPropertiesFileName
رویlocal.defaults.properties
تنظیم کنید و هر ویژگی دیگری را تنظیم کنید.کاتلین
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.*" }
شیار
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: مانیفست برنامه را به روز کنید
این بخش تنظیماتی را برای افزودن به فایل AndroidManifest.xml
شما شرح می دهد.
شماره نسخه خدمات Google Play
اعلان زیر را در عنصر application
اضافه کنید. این نسخه خدمات Google Play را که برنامه با آن کامپایل شده است جاسازی می کند.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
مجوز مکان
اگر برنامه شما نیاز به دسترسی به موقعیت مکانی کاربر دارد، باید مجوز مکان را در فایل AndroidManifest.xml
خود درخواست کنید. گزینهها ACCESS_FINE_LOCATION
هستند که مکان دقیق دستگاه را ارائه میکند و ACCESS_COARSE_LOCATION
که دقت کمتری دارد. برای جزئیات، به راهنمای داده های مکان مراجعه کنید.
برای درخواست مجوز ACCESS_FINE_LOCATION
، این کد را به عنصر manifest
اضافه کنید:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
مجوز ذخیره سازی خارجی
اگر نسخه 8.3 یا جدیدتر SDK خدمات Google Play را هدف قرار می دهید، به مجوز WRITE_EXTERNAL_STORAGE
نیاز ندارید. اگر نسخههای قبلی SDK خدمات Google Play را هدف قرار میدهید، باید مجوز WRITE_EXTERNAL_STORAGE را در عنصر manifest
درخواست کنید.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
کتابخانه Apache HTTP Legacy
اگر از com.google.android.gms:play-services-maps:16.0.0
یا پایین تر استفاده می کنید و برنامه شما سطح API 28 (Android 9.0) یا بالاتر را هدف قرار می دهد، باید اعلان زیر را در عنصر <application>
وارد کنید. از AndroidManifest.xml
. در غیر این صورت، از این اعلامیه صرف نظر کنید.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
مرحله 5: یک دستگاه Android را راه اندازی کنید
برای اجرای برنامهای که از Maps SDK برای Android استفاده میکند، باید آن را در دستگاه Android یا شبیهساز Android که مبتنی بر Android نسخه 5.0 یا بالاتر است و شامل APIهای Google است، مستقر کنید.
- برای استفاده از دستگاه Android، دستورالعملهای موجود در اجرای برنامهها در دستگاه سختافزاری را دنبال کنید.
- برای استفاده از شبیه ساز اندروید، می توانید با استفاده از مدیریت دستگاه مجازی اندروید (AVD) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
مرحله 6: به صورت اختیاری پشتیبانی از Play Service را بررسی کنید
Maps SDK برای Android نیاز دارد که دستگاهی که برنامه خود را روی آن نصب میکنید، سرویسهای Google Play را نصب کرده باشد. Google روشی را ارائه می دهد که می توانید از برنامه خود برای بررسی آن تماس بگیرید. برای اطلاعات بیشتر، به بررسی نصب سرویسهای Google Play مراجعه کنید.
مراحل بعدی
هنگامی که پروژه شما پیکربندی شد، می توانید یک نقشه اضافه کنید .
،این صفحه نحوه پیکربندی یک پروژه Android Studio را برای استفاده از Maps SDK برای Android بدون استفاده از الگوی Google Maps که در Quickstart به تفصیل آمده است، شرح میدهد.
الگوی Google Maps به طور خودکار یک نقشه اولیه را به پروژه جدید Android Studio پیکربندی و اضافه می کند. با این حال، میتوانید نقشهای را نیز به پروژه اندروید اضافه کنید که از قالب Android Studio متفاوتی استفاده میکند. برای انجام این کار، باید پروژه خود را به صورت دستی پیکربندی کنید و سپس نقشه را اضافه کنید .
مرحله 1: Android Studio را راه اندازی کنید
این سند یک محیط توسعه را با استفاده از Android Studio Hedgehog و افزونه Android Gradle نسخه 8.2 توصیف می کند.
مرحله 2. SDK را تنظیم کنید
کتابخانه Maps SDK برای Android از طریق مخزن Maven Google در دسترس است. برای افزودن SDK به برنامه خود، موارد زیر را انجام دهید:
- در فایل
settings.gradle.kts
سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی Maven را در بلوکpluginManagement
قرار دهید. بلوکpluginManagement
باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- در فایل سطح بالای
settings.gradle.kts
خود، مخزن Maven Google و مخزن مرکزی Maven را در بلوکdependencyResolutionManagement
قرار دهید:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود، وابستگی خدمات Google Play را برای Maps SDK برای Android اضافه کنید.کاتلین
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
شیار
dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:19.0.0" }
- در فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود،compileSdk
وminSdk
را روی مقادیر زیر تنظیم کنید:کاتلین
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
شیار
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
- در بخش
buildFeatures
فایلbuild.gradle.kts
یاbuild.gradle
در سطح ماژول، کلاسBuildConfig
را اضافه کنید، که می توانید از آن برای دسترسی به مقادیر فراداده تعریف شده در این روش استفاده کنید:کاتلین
android { // ... buildFeatures { buildConfig = true // ... } }
شیار
android { // ... buildFeatures { buildConfig true // ... } }
مرحله 3: کلید API خود را به پروژه اضافه کنید
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند به طور ایمن توسط برنامه شما ارجاع داده شود. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می کنیم آن را در فایل secrets.properties
که در فهرست اصلی پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties
، به فایلهای خصوصیات Gradle مراجعه کنید.
برای سادهسازی این کار، توصیه میکنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.
برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:
- در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
سطح بالای خود را باز کنید و کد زیر را به عنصرdependencies
در زیرbuildscript
اضافه کنید.کاتلین
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
شیار
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
- فایل
build.gradle.kts
یاbuild.gradle
سطح ماژول خود را باز کنید و کد زیر را به عنصرplugins
اضافه کنید.کاتلین
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
شیار
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- در فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول، مطمئن شوید کهtargetSdk
وcompileSdk
روی 34 تنظیم شده اند. - فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
- فایل
secrets.properties
را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزینYOUR_API_KEY
کنید. کلید خود را در این فایل ذخیره کنید زیراsecrets.properties
از بررسی سیستم کنترل نسخه حذف شده است.MAPS_API_KEY=YOUR_API_KEY
- فایل را ذخیره کنید.
فایل
local.defaults.properties
را در پوشه سطح بالای خود، همان پوشه فایلsecrets.properties
ایجاد کنید و سپس کد زیر را اضافه کنید.MAPS_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل
secrets.properties
است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه کهsecrets.properties
حذف می کند و هنوز فایلsecrets.properties
را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.- فایل را ذخیره کنید.
- در فایل
AndroidManifest.xml
خود، بهcom.google.android.geo.API_KEY
بروید وandroid:value attribute
به روز کنید. اگر تگ<meta-data>
وجود ندارد، آن را به عنوان فرزند تگ<application>
ایجاد کنید.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
توجه:
com.google.android.geo.API_KEY
نام ابرداده توصیه شده برای کلید API است. کلیدی با این نام میتواند برای احراز هویت چندین API مبتنی بر نقشههای Google در پلتفرم Android، از جمله Maps SDK برای Android استفاده شود. برای سازگاری به عقب، API از نامcom.google.android.maps.v2.API_KEY
نیز پشتیبانی می کند. این نام قدیمی فقط به Android Maps API نسخه 2 امکان احراز هویت را می دهد. یک برنامه کاربردی می تواند تنها یکی از نام های ابرداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، API یک استثنا ایجاد می کند. در Android Studio، فایل
build.gradle.kts
یاbuild.gradle
در سطح ماژول خود را باز کنید و ویژگیsecrets
را ویرایش کنید. اگر ویژگیsecrets
وجود ندارد، آن را اضافه کنید.ویژگی های افزونه را ویرایش کنید تا
propertiesFileName
رویsecrets.properties
تنظیم کنید،defaultPropertiesFileName
رویlocal.defaults.properties
تنظیم کنید و هر ویژگی دیگری را تنظیم کنید.کاتلین
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.*" }
شیار
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: مانیفست برنامه را به روز کنید
این بخش تنظیماتی را برای افزودن به فایل AndroidManifest.xml
شما شرح می دهد.
شماره نسخه خدمات Google Play
اعلان زیر را در عنصر application
اضافه کنید. این نسخه خدمات Google Play را که برنامه با آن کامپایل شده است جاسازی می کند.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
مجوز مکان
اگر برنامه شما نیاز به دسترسی به موقعیت مکانی کاربر دارد، باید مجوز مکان را در فایل AndroidManifest.xml
خود درخواست کنید. گزینهها ACCESS_FINE_LOCATION
هستند که مکان دقیق دستگاه را ارائه میکند و ACCESS_COARSE_LOCATION
که دقت کمتری دارد. برای جزئیات، به راهنمای داده های مکان مراجعه کنید.
برای درخواست مجوز ACCESS_FINE_LOCATION
، این کد را به عنصر manifest
اضافه کنید:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
مجوز ذخیره سازی خارجی
اگر نسخه 8.3 یا جدیدتر SDK خدمات Google Play را هدف قرار می دهید، به مجوز WRITE_EXTERNAL_STORAGE
نیاز ندارید. اگر نسخههای قبلی SDK خدمات Google Play را هدف قرار میدهید، باید مجوز WRITE_EXTERNAL_STORAGE را در عنصر manifest
درخواست کنید.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
کتابخانه Apache HTTP Legacy
اگر از com.google.android.gms:play-services-maps:16.0.0
یا پایین تر استفاده می کنید و برنامه شما سطح API 28 (Android 9.0) یا بالاتر را هدف قرار می دهد، باید اعلان زیر را در عنصر <application>
وارد کنید. از AndroidManifest.xml
. در غیر این صورت، از این اعلامیه صرف نظر کنید.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
مرحله 5: یک دستگاه Android را راه اندازی کنید
برای اجرای برنامهای که از Maps SDK برای Android استفاده میکند، باید آن را در دستگاه Android یا شبیهساز Android که مبتنی بر Android نسخه 5.0 یا بالاتر است و شامل APIهای Google است، مستقر کنید.
- برای استفاده از دستگاه Android، دستورالعملهای موجود در اجرای برنامهها در دستگاه سختافزاری را دنبال کنید.
- برای استفاده از شبیه ساز اندروید، می توانید با استفاده از مدیریت دستگاه مجازی اندروید (AVD) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
مرحله 6: به صورت اختیاری پشتیبانی از Play Service را بررسی کنید
Maps SDK برای Android نیاز دارد که دستگاهی که برنامه خود را روی آن نصب میکنید، سرویسهای Google Play را نصب کرده باشد. Google روشی را ارائه می دهد که می توانید از برنامه خود برای بررسی آن تماس بگیرید. برای اطلاعات بیشتر، به بررسی نصب سرویسهای Google Play مراجعه کنید.
مراحل بعدی
هنگامی که پروژه شما پیکربندی شد، می توانید یک نقشه اضافه کنید .