یک پروژه اندروید استودیو راه اندازی کنید

این صفحه نحوه پیکربندی یک پروژه 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 به برنامه خود، موارد زیر را انجام دهید:

1. در فایل settings.gradle.kts سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی 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. در فایل build.gradle.kts یا build.gradle در سطح ماژول خود، وابستگی خدمات Google Play را برای Maps SDK برای Android اضافه کنید.

   کاتلین

   dependencies {
   
       // Maps SDK for Android
       implementation(libs.play.services.maps)
   }

   شیار

   dependencies {
   
       // Maps SDK for Android
       implementation "com.google.android.gms:play-services-maps:19.0.0"
   }

4. در فایل build.gradle.kts یا build.gradle سطح ماژول خود، compileSdk و minSdk را روی مقادیر زیر تنظیم کنید:

   کاتلین

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

   شیار

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

5. در بخش 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:

1. در Android Studio، فایل build.gradle.kts یا build.gradle سطح بالای خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.

   کاتلین

   plugins {
       alias(libs.plugins.android.application) apply false
       alias(libs.plugins.jetbrains.kotlin.android) apply false
       alias(libs.plugins.kotlin.compose) apply false
       alias(libs.plugins.secrets.gradle.plugin) apply false
   }

   شیار

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. فایل build.gradle.kts یا build.gradle سطح ماژول خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

   کاتلین

   plugins {
       // ...
       alias(libs.plugins.secrets.gradle.plugin)
   }

   شیار

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

3. در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی 34 تنظیم شده اند.
4. پروژه خود را با Gradle همگام سازی کنید .
5. فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی سیستم کنترل نسخه حذف شده است.

   MAPS_API_KEY=YOUR_API_KEY

6. فایل local.defaults.properties را در پوشه سطح بالای خود، همان پوشه فایل secrets.properties ایجاد کنید و سپس کد زیر را اضافه کنید.

   MAPS_API_KEY=DEFAULT_API_KEY

   هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل secrets.properties است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه که secrets.properties حذف می کند و هنوز فایل secrets.properties را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.

7. در فایل 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 یک استثنا ایجاد می کند.

8. در 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"
   }
           

   شیار

   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: مانیفست برنامه را به روز کنید

این بخش تنظیماتی را برای افزودن به فایل 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 مراجعه کنید.

مراحل بعدی

هنگامی که پروژه شما پیکربندی شد، می توانید یک نقشه اضافه کنید .