Maps SDK برای Android Quick Start

با استفاده از الگوی Google Maps Views برای Android Studio، یک برنامه اندرویدی ایجاد کنید که یک نقشه را نمایش دهد. اگر پروژه Android Studio موجودی دارید که می‌خواهید آن را راه‌اندازی کنید، به تنظیم پروژه Android Studio مراجعه کنید.

این شروع سریع برای توسعه دهندگانی در نظر گرفته شده است که با توسعه پایه اندروید با Kotlin یا Java آشنا هستند.

درباره محیط توسعه

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

یک دستگاه اندرویدی راه اندازی کنید

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

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

یک پروژه Google Maps در Android Studio ایجاد کنید

رویه ایجاد یک پروژه Google Maps در Android Studio در Flamingo و نسخه‌های بعدی اندروید استودیو تغییر کرد.

1. Android Studio را باز کنید و روی New Project در پنجره Welcome to Android Studio کلیک کنید.

2. در پنجره پروژه جدید ، در زیر دسته تلفن و تبلت ، بدون فعالیت را انتخاب کنید و سپس روی Next کلیک کنید.

3. تکمیل فرم پروژه جدید :

   • Language را روی Java یا Kotlin قرار دهید. هر دو زبان به طور کامل توسط Maps SDK برای اندروید پشتیبانی می شوند. برای کسب اطلاعات بیشتر در مورد Kotlin، به توسعه برنامه‌های Android با Kotlin مراجعه کنید.

   • حداقل SDK را روی یک نسخه SDK سازگار با دستگاه آزمایشی خود تنظیم کنید. باید نسخه ای بزرگتر از حداقل نسخه مورد نیاز Maps SDK برای نسخه Android 19.0.x، که Android API سطح 21 ("Lollipop"؛ Android 5.0) یا بالاتر است، انتخاب کنید. برای آخرین اطلاعات در مورد الزامات نسخه SDK به یادداشت های انتشار مراجعه کنید.

   • زبان پیکربندی Build را روی Kotlin DSL یا Groovy DSL قرار دهید. قطعات برای هر دو زبان پیکربندی ساخت در مراحل زیر نشان داده شده است.

4. روی Finish کلیک کنید.

   اندروید استودیو Gradle را راه اندازی کرده و پروژه را می سازد. این ممکن است کمی طول بکشد.

5. افزودن فعالیت مشاهده نقشه های Google :

   1. روی پوشه app در پروژه خود کلیک راست کنید.

   2. New > Google > Google Maps Views Activity را انتخاب کنید.

      

   3. در کادر گفتگوی New Android Activity ، چک باکس Launcher Activity را انتخاب کنید.

   4. Finish را انتخاب کنید.

      برای اطلاعات بیشتر، به افزودن کد از یک الگو مراجعه کنید

6. پس از اتمام ساخت، Android Studio فایل‌های AndroidManifest.xml و MapsActivity را باز می‌کند. فعالیت شما ممکن است نام دیگری داشته باشد، اما نامی است که در حین راه اندازی پیکربندی کرده اید.

پروژه Google Cloud خود را راه اندازی کنید

با کلیک کردن روی برگه های زیر، مراحل تنظیم کنسول Cloud مورد نیاز را تکمیل کنید:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

کلید API را به برنامه خود اضافه کنید

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

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

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

1. در Android Studio، فایل build.gradle.kts یا build.gradle سطح بالای خود را باز کنید و کد زیر را به عنصر 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.kts یا 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.kts یا 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}" />

   توجه: 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 یک استثنا ایجاد می کند.

10. در Android Studio، فایل 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"
    
        // 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 {
        // 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"
    
        // 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.*"
    }
            

به کد نگاه کنید

کد ارائه شده توسط الگو را بررسی کنید. به طور خاص، به فایل های زیر در پروژه Android Studio خود نگاه کنید.

فایل فعالیت نقشه ها

فایل فعالیت نقشه ها فعالیت اصلی برنامه است و حاوی کد مدیریت و نمایش نقشه است. به‌طور پیش‌فرض، فایلی که فعالیت را تعریف می‌کند MapsActivity.java نام دارد یا اگر Kotlin را به عنوان زبان برنامه خود تنظیم کنید، MapsActivity.kt .

عناصر اصلی فعالیت نقشه ها:

• شی SupportMapFragment چرخه حیات نقشه را مدیریت می کند و عنصر اصلی رابط کاربری برنامه است.

• شی GoogleMap دسترسی به داده ها و نمای نقشه را فراهم می کند. این کلاس اصلی Maps SDK برای اندروید است. راهنمای Map Objects اشیاء SupportMapFragment و GoogleMap را با جزئیات بیشتری شرح می دهد.

• تابع moveCamera نقشه را در مختصات LatLng برای سیدنی استرالیا متمرکز می کند. اولین تنظیماتی که هنگام افزودن نقشه باید پیکربندی شود، معمولاً مکان نقشه و تنظیمات دوربین است. مانند زاویه دید، جهت نقشه و سطح زوم. برای جزئیات به راهنمای دوربین و مشاهده مراجعه کنید.

• تابع addMarker یک نشانگر به مختصات سیدنی اضافه می کند. برای جزئیات به راهنمای نشانگرها مراجعه کنید.

فایل Gradle ماژول

فایل Module build.gradle.kts شامل وابستگی نقشه‌های زیر است که توسط Maps SDK برای Android مورد نیاز است.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

برای کسب اطلاعات بیشتر در مورد مدیریت وابستگی Maps، به نسخه‌سازی مراجعه کنید.

فایل طرح بندی XML

فایل activity_maps.xml فایل طرح بندی XML است که ساختار رابط کاربری برنامه را تعریف می کند. فایل در دایرکتوری res/layout قرار دارد. فایل activity_maps.xml قطعه ای را اعلام می کند که شامل عناصر زیر است:

• tools:context فعالیت پیش‌فرض قطعه را روی MapsActivity تنظیم می‌کند که در فایل فعالیت نقشه‌ها تعریف شده است.
• android:name نام کلاس قطعه را روی SupportMapFragment تنظیم می‌کند، که نوع قطعه مورد استفاده در فایل فعالیت نقشه‌ها است.

فایل طرح بندی XML حاوی کد زیر است:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

برنامه را اجرا و اجرا کنید

هنگامی که برنامه را با موفقیت اجرا می کنید، نقشه ای را نشان می دهد که در مرکز سیدنی استرالیا با یک نشانگر روی شهر است، همانطور که در تصویر زیر مشاهده می کنید.

برای استقرار و اجرای برنامه:

1. در اندروید استودیو، روی گزینه منوی Run (یا نماد دکمه پخش) کلیک کنید تا برنامه خود اجرا شود.
2. هنگامی که از شما خواسته می شود دستگاهی را انتخاب کنید، یکی از گزینه های زیر را انتخاب کنید:
   • دستگاه Android متصل به رایانه شما را انتخاب کنید.
   • همچنین، دکمه رادیویی Launch emulator را انتخاب کنید و دستگاه مجازی را که تنظیم کرده‌اید انتخاب کنید.
3. روی OK کلیک کنید. اندروید استودیو Gradle را برای ساخت اپلیکیشن شما راه اندازی می کند و سپس نتایج را در دستگاه یا شبیه ساز شما نمایش می دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه اندازی شود.

مراحل بعدی

• تنظیم نقشه : این سند نحوه تنظیم تنظیمات اولیه و زمان اجرا را برای نقشه خود، مانند موقعیت دوربین، نوع نقشه، اجزای رابط کاربری، و ژست‌ها شرح می‌دهد.

• افزودن یک نقشه به برنامه اندرویدی خود (Kotlin) : این لبه کد شما را از طریق برنامه ای راهنمایی می کند که برخی از ویژگی های اضافی Maps SDK برای Android را نشان می دهد.

• از کتابخانه Maps Android KTX استفاده کنید : این کتابخانه برنامه‌های افزودنی Kotlin (KTX) به شما امکان می‌دهد از چندین ویژگی زبان Kotlin هنگام استفاده از Maps SDK برای Android استفاده کنید.