راه‌اندازی پروژه «استودیو Android»

این صفحه نحوه پیکربندی پروژه «استودیو Android» را برای استفاده از کیت توسعه نرم‌افزار Google Maps برای Android بدون استفاده از الگوی Google Maps که در شروع سریع شرح داده شده است، توضیح می‌دهد.

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

مرحله ۱: راه‌اندازی Android Studio

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

مرحله ۲. راه‌اندازی کیت توسعه نرم‌افزار

کتابخانه «کیت توسعه نرم‌افزار Google Maps برای Android» ازطریق مخزن Maven متعلق به Google دردسترس است. برای افزودن کیت توسعه نرم‌افزار به برنامه‌تان، کارهای زیر را انجام دهید:

  1. در فایل settings.gradle.kts سطح بالا، درگاه افزایه Gradle، مخزن Google Maven، و مخزن مرکزی Maven را در بلوک pluginManagement اضافه کنید. بلوک pluginManagement باید قبل‌از هر عبارت دیگری در اسکریپت ظاهر شود. 
    pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
  2. در فایل settings.gradle.kts سطح بالا، مخزن Maven متعلق به Google و مخزن مرکزی Maven را در بلوک dependencyResolutionManagement اضافه کنید: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. در فایل build.gradle.kts یا build.gradle سطح ماژول، وابستگی خدمات Google Play را برای «کیت توسعه نرم‌افزار Google Maps برای Android» اضافه کنید.

    Kotlin

    dependencies {

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

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.1.0"
}
  4. در فایل build.gradle.kts یا build.gradle سطح واحد، compileSdk و minSdk را روی مقادیر زیر تنظیم کنید:

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}
  5. در بخش buildFeatures از فایل build.gradle.kts یا build.gradle در سطح ماژول، کلاس BuildConfig را اضافه کنید که می‌توانید از آن برای دسترسی به مقادیر فراداده تعریف‌شده در ادامه این روش استفاده کنید:

    Kotlin

    android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
  6. در فایل libs.versions.toml، موارد زیر را اضافه کنید: 
    [versions]
play-services-maps = "20.1.0"

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

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

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

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

برای نصب افزایه Secrets Gradle ویژه Android و ذخیره کلید میانای برنامه‌سازی کاربردی:

  1. در 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
}
  2. فایل 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'
}
  3. اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
  4. فایل secrets.properties را در دایرکتوری سطح بالا باز کنید، سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید. حتماً secrets.properties را به فایل .gitignore خود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید. 
    MAPS_API_KEY=YOUR_API_KEY

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

    MAPS_API_KEY=DEFAULT_API_KEY

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

  6. در فایل 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 نام فراداده توصیه‌شده برای کلید میانای برنامه‌سازی کاربردی است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله کیت توسعه نرم‌افزار Maps برای Android، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه فقط می‌تواند یکی از نام‌های فراداده کلید میانای برنامه‌سازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند.

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

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

این بخش تنظیماتی را که باید به فایل 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"/>

اجازه فضای ذخیره‌سازی خارجی

اگر نسخه ۸.۳ یا جدیدتر کیت توسعه نرم‌افزار خدمات Google Play را هدف قرار می‌دهید، به اجازه WRITE_EXTERNAL_STORAGE نیاز ندارید. اگر نسخه‌های قبلی کیت توسعه نرم‌افزار خدمات 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 یا نسخه‌های پایین‌تر استفاده می‌کنید و برنامه‌تان میانای برنامه‌سازی کاربردی سطح ۲۸ (Android 9.0) یا بالاتر را هدف‌یابی می‌کند، باید اعلامیه زیر را در عنصر <application> AndroidManifest.xml اضافه کنید. درغیراین‌صورت، این اظهارنامه را رد کنید.

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

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

برای اجرای برنامه‌ای که از «کیت توسعه نرم‌افزار Maps برای Android» استفاده می‌کند، باید آن را در دستگاه Android یا شبیه‌ساز Android که مبتنی بر Android نسخه ۶.۰ یا بالاتر است و Google APIs را دربرمی‌گیرد مستقر کنید.

  • برای استفاده از دستگاه Android، دستورالعمل‌های اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
  • برای استفاده از شبیه‌ساز Android، می‌توانید دستگاهی مجازی ایجاد کنید و شبیه‌ساز را بااستفاده از مدیر دستگاه که همراه با Android Studio ارائه می‌شود نصب کنید.

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

«کیت توسعه نرم‌افزار Maps برای Android» مستلزم این است که دستگاهی که برنامه‌تان را در آن مستقر می‌کنید «خدمات Google Play» را نصب کرده باشد. Google روشی ارائه می‌دهد که می‌توانید از برنامه‌تان برای بررسی کردن آن را فراخوانی کنید. برای اطلاعات بیشتر، بررسی نصب بودن خدمات Google Play را ببینید.

مراحل بعدی

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