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

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

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

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

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

مرحله 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 {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

    کاتلین

    dependencies {

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

    شیار

    android {
    compileSdk 34

    defaultConfig {
        minSdk 19
        // ...
    }
}

    کاتلین

    android {
    compileSdk = 34

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

    شیار

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

    کاتلین

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

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

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

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

برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:

  1. در Android Studio، فایل build.gradle یا build.gradle.kts سطح بالای خود را باز کنید و کد زیر را به عنصر 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.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    کاتلین

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. در فایل build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی 34 تنظیم شده اند.
  4. فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
  5. فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی سیستم کنترل نسخه حذف شده است. 
    MAPS_API_KEY=YOUR_API_KEY
  6. فایل را ذخیره کنید.

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

    MAPS_API_KEY=DEFAULT_API_KEY

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

  8. فایل را ذخیره کنید.
  9. در فایل AndroidManifest.xml خود، به com.google.android.geo.API_KEY بروید و android:value attribute به روز کنید. اگر تگ <meta-data> وجود ندارد، آن را به عنوان فرزند تگ <application> ایجاد کنید. 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

    کاتلین

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

مرحله 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) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.

مرحله 6: به صورت اختیاری پشتیبانی از Play Service را بررسی کنید

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

مراحل بعدی

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