راه‌اندازی پروژه «استودیو 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 را برای «کیت توسعه نرم‌افزار 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.0.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.0.0"

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

مرحله ۳: افزودن کلید میانای برنامه‌سازی کاربردی به پروژه

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

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

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

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

    Groovy

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

    Kotlin

    buildscript {
    dependencies {
        // ...
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
  2. فایل build.gradle سطح برنامه را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

    Groovy

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

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با 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 نام فراداده توصیه‌شده برای کلید میانای برنامه‌سازی کاربردی است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله «کیت توسعه نرم‌افزار Maps برای Android»، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه فقط می‌تواند یکی از نام‌های فراداده کلید میانای برنامه‌سازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند.

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

این بخش تنظیماتی را که باید به فایل 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 6.0 یا بالاتر است و شامل Google APIs می‌شود مستقر کنید.

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

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

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

مراحل بعدی

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