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

این صفحه نحوه پیکربندی یک پروژه اندروید استودیو را برای استفاده از Maps SDK برای اندروید بدون استفاده از الگوی Google Maps که در Quickstart به تفصیل شرح داده شده است، شرح می‌دهد.

الگوی نقشه‌های گوگل به طور خودکار یک نقشه اولیه را به یک پروژه جدید اندروید استودیو پیکربندی و اضافه می‌کند. با این حال، می‌توانید یک نقشه را به یک پروژه اندروید که از یک الگوی اندروید استودیو متفاوت استفاده می‌کند نیز اضافه کنید. برای انجام این کار، باید پروژه خود را به صورت دستی پیکربندی کرده و سپس نقشه را اضافه کنید .

مرحله ۱: راه‌اندازی اندروید استودیو

این سند یک محیط توسعه با استفاده از Android Studio Hedgehog و افزونه Android Gradle نسخه 8.2 را شرح می‌دهد.

مرحله ۲. راه‌اندازی SDK

کتابخانه Maps SDK برای اندروید از طریق مخزن Maven گوگل در دسترس است. برای افزودن SDK به برنامه خود، مراحل زیر را انجام دهید:

1. در فایل سطح بالای settings.gradle.kts خود، Gradle plugin portal ، Google Maven repository و Maven central repository را در زیر بلوک pluginManagement قرار دهید. بلوک pluginManagement باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.

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

2. در فایل سطح بالای settings.gradle.kts ، مخزن Maven گوگل و مخزن مرکزی Maven را در زیر بلوک dependencyResolutionManagement قرار دهید:

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

3. در فایل build.gradle.kts یا build.gradle در سطح ماژول، وابستگی سرویس‌های Google Play را برای Maps SDK برای اندروید اضافه کنید.

   کاتلین

   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
       // ...
     }
   }

6. در فایل libs.versions.toml خود، موارد زیر را اضافه کنید:

   [versions]
   play-services-maps = "19.2.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

مرحله ۳: کلید API خود را به پروژه اضافه کنید

این بخش نحوه ذخیره کلید API شما را توضیح می‌دهد تا برنامه شما بتواند به طور ایمن به آن مراجعه کند. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل secrets.properties که در دایرکتوری ریشه پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties ، به Gradle properties files مراجعه کنید.

برای ساده‌سازی این کار، توصیه می‌کنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.

برای نصب افزونه Secrets Gradle برای اندروید و ذخیره کلید API خود:

1. در اندروید استودیو، فایل 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")
       }
   }

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

   گرووی

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

   کاتلین

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. اگر از اندروید استودیو استفاده می‌کنید، پروژه خود را با Gradle همگام‌سازی کنید .
4. فایل local.properties را در دایرکتوری سطح پروژه خود باز کنید و سپس کد زیر را اضافه کنید. به جای YOUR_API_KEY ، کلید API خود را قرار دهید.

   MAPS_API_KEY=YOUR_API_KEY

5. در فایل AndroidManifest.xml خود، به com.google.android.geo.API_KEY بروید و ویژگی android:value به صورت زیر به‌روزرسانی کنید:

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

   توجه: com.google.android.geo.API_KEY نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Maps SDK برای اندروید، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

مرحله ۴: به‌روزرسانی مانیفست برنامه

این بخش تنظیماتی را که باید به فایل AndroidManifest.xml خود اضافه کنید، شرح می‌دهد.

شماره نسخه سرویس‌های گوگل پلی

اعلان زیر را درون عنصر 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"/>

مجوز ذخیره‌سازی خارجی

اگر نسخه ۸.۳ یا بالاتر از SDK سرویس‌های گوگل پلی را هدف قرار می‌دهید، نیازی به مجوز WRITE_EXTERNAL_STORAGE ندارید. اگر نسخه‌های قبلی SDK سرویس‌های گوگل پلی را هدف قرار می‌دهید، باید مجوز WRITE_EXTERNAL_STORAGE را در عنصر manifest درخواست کنید.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

کتابخانه قدیمی HTTP آپاچی

اگر از com.google.android.gms:play-services-maps:16.0.0 یا پایین‌تر استفاده می‌کنید و برنامه شما API سطح ۲۸ (اندروید ۹.۰) یا بالاتر را هدف قرار می‌دهد، باید اعلان زیر را در عنصر <application> از AndroidManifest.xml قرار دهید. در غیر این صورت، از این اعلان صرف نظر کنید.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

مرحله ۵: راه‌اندازی دستگاه اندروید

برای اجرای برنامه‌ای که از Maps SDK برای اندروید استفاده می‌کند، باید آن را روی یک دستگاه اندروید یا شبیه‌ساز اندروید که مبتنی بر اندروید ۵.۰ یا بالاتر است و شامل APIهای گوگل است، مستقر کنید.

• برای استفاده از دستگاه اندروید، دستورالعمل‌های موجود در «اجرای برنامه‌ها روی دستگاه سخت‌افزاری» را دنبال کنید.
• برای استفاده از شبیه‌ساز اندروید، می‌توانید یک دستگاه مجازی ایجاد کنید و با استفاده از Android Virtual Device Manager (AVD) که همراه با اندروید استودیو ارائه می‌شود، شبیه‌ساز را نصب کنید.

مرحله ۶: در صورت تمایل، پشتیبانی سرویس Play را بررسی کنید

کیت توسعه نرم‌افزار نقشه برای اندروید (Maps SDK) مستلزم آن است که دستگاهی که برنامه خود را روی آن مستقر می‌کنید، سرویس‌های گوگل پلی (Google Play services) را نصب داشته باشد. گوگل روشی را ارائه می‌دهد که می‌توانید از طریق برنامه خود آن را فراخوانی کنید تا بررسی شود. برای اطلاعات بیشتر، به بررسی نصب بودن سرویس‌های گوگل پلی مراجعه کنید.

مراحل بعدی

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