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

این صفحه نحوه پیکربندی پروژه Android Studio برای استفاده از کیت توسعه نرم‌افزار 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 را برای «کیت توسعه نرم‌افزار 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 را با کلید میانای برنامه‌سازی کاربردی خود جایگزین کنید. حتماً secrets.properties را به فایل .gitignore اضافه کنید (یا آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید API خود را در کنترل نسخه بررسی نکنید. 
    MAPS_API_KEY=YOUR_API_KEY

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

    MAPS_API_KEY=DEFAULT_API_KEY

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

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

  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

اگر از 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» را ببینید.

مراحل بعدی

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