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

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

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

مرحله 1: Android Studio را راه اندازی کنید

  1. Android Studio Arctic Fox یا جدیدتر مورد نیاز است. اگر قبلا این کار را نکرده اید، آن را دانلود و نصب کنید .
  2. مطمئن شوید که از افزونه Android Gradle نسخه 7.0 یا بالاتر در Android Studio استفاده می کنید.

    مرحله 2. SDK را تنظیم کنید

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

    1. در فایل settings.gradle سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی Maven را در بلوک pluginManagement قرار دهید. بلوک pluginManagement باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.
      pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
    2. در فایل settings.gradle سطح بالای خود، مخزن Maven Google و مخزن مرکزی Maven را تحت بلوک dependencyResolutionManagement قرار دهید:
      dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
    3. در فایل build.gradle در سطح ماژول خود، وابستگی خدمات Google Play را برای Maps SDK برای Android اضافه کنید.
      dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}
    4. در فایل build.gradle سطح ماژول خود، compileSdk و minSdk را روی مقادیر زیر تنظیم کنید:
      android {
    compileSdk 31

    defaultConfig {
        minSdk 19
        // ...
    }

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

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

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

    1. در Android Studio، فایل build.gradle در سطح پروژه خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.
      plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
    2. سپس، فایل build.gradle در سطح ماژول خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید. 
      id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    3. فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
    4. local.properties را در دایرکتوری سطح پروژه خود باز کنید و کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. 
      MAPS_API_KEY=YOUR_API_KEY
    5. فایل را ذخیره کنید.
    6. در فایل AndroidManifest.xml خود، به com.google.android.geo.API_KEY بروید و android:value attribute به صورت زیر به روز کنید: 
      <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 یک استثنا ایجاد می کند.

    مرحله 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 نسخه 4.0 یا بالاتر است و شامل APIهای Google است، مستقر کنید.

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

    مراحل بعدی

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