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

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

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

مرحله ۱: راه‌اندازی اندروید استودیو

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

مرحله ۲. راه‌اندازی SDK

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

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

    کاتلین 

    dependencies {

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

    گرووی 

    dependencies {

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

    کاتلین 

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

    گرووی 

    android {
    compileSdk 34

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

    کاتلین 

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

    گرووی 

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

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

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

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

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

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

    کاتلین 

    plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.jetbrains.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.secrets.gradle.plugin) apply false
}

    گرووی 

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

    کاتلین 

    plugins {
    // ...
    alias(libs.plugins.secrets.gradle.plugin)
}

    گرووی 

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

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

    MAPS_API_KEY=DEFAULT_API_KEY

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

  7. در فایل 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}" />

    توجه: com.google.android.geo.API_KEY نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Maps SDK برای اندروید، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

  8. در اندروید استودیو، فایل build.gradle.kts یا build.gradle در سطح ماژول خود را باز کنید و ویژگی secrets را ویرایش کنید. اگر ویژگی secrets وجود ندارد، آن را اضافه کنید.

    ویژگی‌های افزونه را ویرایش کنید تا propertiesFileName روی secrets.properties ، defaultPropertiesFileName را روی local.defaults.properties و سایر ویژگی‌ها تنظیم کنید.

    کاتلین 

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"
}

    گرووی 

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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 خود اضافه کنید، شرح می‌دهد.

شماره نسخه سرویس‌های گوگل پلی

اعلان زیر را درون عنصر 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"/>

مجوز ذخیره‌سازی خارجی

اگر نسخه ۸.۳ یا بالاتر از SDK سرویس‌های گوگل پلی را هدف قرار می‌دهید، نیازی به مجوز WRITE_EXTERNAL_STORAGE ندارید. اگر نسخه‌های قبلی SDK سرویس‌های گوگل پلی را هدف قرار می‌دهید، باید مجوز WRITE_EXTERNAL_STORAGE را در عنصر manifest درخواست کنید. 

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

کتابخانه قدیمی HTTP آپاچی

اگر از com.google.android.gms:play-services-maps:16.0.0 یا پایین‌تر استفاده می‌کنید و برنامه شما API سطح ۲۸ (اندروید ۹.۰) یا بالاتر را هدف قرار می‌دهد، باید اعلان زیر را در عنصر <application> از AndroidManifest.xml قرار دهید. در غیر این صورت، از این اعلان صرف نظر کنید. 

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

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

برای اجرای برنامه‌ای که از Maps SDK برای اندروید استفاده می‌کند، باید آن را روی یک دستگاه اندروید یا شبیه‌ساز اندروید که مبتنی بر اندروید ۵.۰ یا بالاتر است و شامل APIهای گوگل است، مستقر کنید.

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

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

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

مراحل بعدی

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