شروع سریع کیت توسعه نرم‌افزار Maps ویژه Android

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

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

درباره محیط توسعه نرم‌افزار

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

توجه: اگر محیط توسعه شما از نسخه دیگری از Android Studio یا Gradle استفاده می‌کند، ممکن است لازم باشد مراحل را براساس محیط خود تغییر دهید. برای اطلاعات بیشتر درباره نسخه‌های Android Studio و Gradle، سازگاری افزایه Android Gradle و Android Studio را ببینید.

راه‌اندازی دستگاه Android

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

• برای استفاده از دستگاه Android، دستورالعمل‌های اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
• برای استفاده از شبیه‌ساز Android، می‌توانید دستگاهی مجازی ایجاد کنید و شبیه‌ساز را بااستفاده از مدیر دستگاه مجازی Android (AVD) که همراه با Android Studio ارائه می‌شود نصب کنید.
  توجه: اگر تصمیم گرفتید از شبیه‌ساز Android استفاده کنید، مطمئن شوید دستگاهی را انتخاب کنید که نماد Play، ، در زیر ستون فروشگاه Play نمایش داده شود. این نماد نشان می‌دهد که این نمایه‌ها کاملاً با CTS مطابقت دارند و می‌توانند از تصاویر سیستم که شامل برنامه «فروشگاه Play» است استفاده کنند:

  

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

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

1. «استودیو Android» را باز کنید و در پنجره به «استودیو Android» خوش آمدید، روی پروژه جدید کلیک کنید.

2. در پنجره پروژه جدید، در دسته تلفن و رایانه لوحی، No Activity (بدون فعالیت) را انتخاب کنید و سپس روی Next (بعدی) کلیک کنید.

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

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

   • حداقل کیت توسعه نرم‌افزار را روی نسخه کیت توسعه نرم‌افزاری تنظیم کنید که با دستگاه آزمایشی شما سازگار باشد. باید نسخه‌ای را انتخاب کنید که از حداقل نسخه موردنیاز «کیت توسعه نرم‌افزار Maps ویژه Android نسخه ۲۰.۰.x» بالاتر باشد. حداقل نسخه موردنیاز «کیت توسعه نرم‌افزار Maps ویژه Android نسخه ۲۰.۰.x» «سطح میانای برنامه کاربردی ۲۳» ‏(Marshmallow؛‏ Android 6.0) یا بالاتر است. برای دریافت جدیدترین اطلاعات درباره الزامات نسخه کیت توسعه نرم‌افزار، یادداشت‌های انتشار را ببینید.

     توجه: اگر مطمئن نیستید که کدام نسخه کیت توسعه نرم‌افزار را انتخاب کنید، پیوند به من کمک کنید انتخاب کنم را انتخاب کنید تا اطلاعات توزیع برای کیت‌های توسعه نرم‌افزار Android پشتیبانی‌شده نمایش داده شود. برای مثال، اگر سطح میانای برنامه کاربردی Android نسخه ۲۳ («Marshmallow»؛ Android نسخه ۶.۰) را انتخاب کنید، برنامه‌تان باید در بیش‌از ۹۹٪ دستگاه‌های Android اجرا شود.

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

4. روی تمام کلیک کنید؛

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

5. فعالیت بازدیدهای Google Maps را اضافه کنید:

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

   2. جدید > Google > فعالیت بازدیدهای Google Maps را انتخاب کنید.

      

   3. در چارگوش گفتگوی فعالیت جدید Android، چارگوش انتخاب فعالیت راه‌انداز را انتخاب کنید.

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

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

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

   احتیاط: فایل AndroidManifest.xml حاوی دستورالعمل‌هایی درباره دریافت کلید Google Maps API و سپس افزودن آن به فایل local.properties است. کلید API خود را به فایل local.properties اضافه نکنید. با این کار، کلید میانای API شما با ایمنی کمتری ذخیره می‌شود. به‌جای آن، دستورالعمل‌های راه‌اندازی پروژه Google Cloud را برای ایجاد پروژه Cloud و پیکربندی کلید میانای برنامه‌سازی کاربردی دنبال کنید.

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

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

مرحله ۱

کنسول

1. در کنسول Google Cloud، در صفحه انتخابگر پروژه، روی ایجاد پروژه کلیک کنید تا ایجاد پروژه Cloud جدیدی را شروع کنید.

   به صفحه انتخابگر پروژه بروید

2. مطمئن شوید که صورت‌حساب برای پروژه Cloud شما فعال است. مطمئن شوید که صدور صورت‌حساب برای پروژه‌تان فعال باشد.

   ‫Google Cloud دوره آزمایشی با کارمزد ۰٫۰۰ دلار ارائه می‌دهد. دوره آزمایشی پس‌از ۹۰ روز یا پس‌از اینکه حساب ۳۰۰ دلار هزینه جمع کرد، هرکدام زودتر باشد، منقضی می‌شود. هرزمان بخواهید می‌توانید لغو کنید. برای اطلاعات بیشتر، به اعتبارات حساب صورت‌حساب و صورت‌حساب مراجعه کنید.

کیت توسعه نرم‌افزار Cloud

gcloud projects create "PROJECT"

درباره کیت توسعه نرم‌افزار Google Cloud ، نصب کیت توسعه نرم‌افزار Cloud ، و دستورات زیر بیشتر بخوانید:

• gcloud projects create

توجه: اگر قصد ندارید منابعی را که در تمرین یادگیری ایجاد می‌کنید نگه دارید، به‌جای انتخاب پروژه موجود، پروژه جدیدی ایجاد کنید. پس‌از اتمام تمرین، می‌توانید پروژه را حذف کنید و همه منابع منسوب به پروژه را بردارید.

مرحله ۲

برای استفاده از Google Maps Platform، باید میاناهای برنامه‌سازی کاربردی یا کیت‌های توسعه نرم‌افزاری را که قصد دارید با پروژه‌تان استفاده کنید فعال کنید.

کنسول

فعال کردن کیت توسعه نرم‌افزار Google Maps برای Android

Cloud SDK

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

درباره کیت توسعه نرم‌افزار Google Cloud ، نصب کیت توسعه نرم‌افزار Cloud ، و فرمان‌های زیر بیشتر بخوانید:

• gcloud services enable
• gcloud services disable

مرحله ۳

این مرحله فقط فرایند ایجاد کلید میانای API را طی می‌کند. اگر از «کلید API» خود در تولید استفاده می‌کنید، اکیداً توصیه می‌کنیم «کلید API» خود را محدود کنید. می‌توانید اطلاعات بیشتری در صفحه استفاده از کلیدهای API مخصوص محصول پیدا کنید.

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

برای ایجاد کلید میانای API:

کنسول

1. به صفحه پلاتفرم Google Maps > اطلاعات کاربری بروید.

   به صفحه «اطلاعات اعتباری» بروید

2. در صفحه اعتبارنامه‌ها، روی ایجاد اعتبارنامه > کلید میانای برنامه‌سازی کاربردی کلیک کنید.
   کادر گفتگوی کلید میانای API ایجاد شد کلید میانای API جدیداً ایجادشده را نمایش می‌دهد.
3. روی بستن کلیک کنید.
   کلید میانای API جدید در صفحه اطلاعات کاربری در بخش کلیدهای میانای API فهرست شده است.
   (به‌یاد داشته باشید که قبل‌از استفاده از کلید در دسته هدف تولید، میانای برنامه‌سازی کاربردی را محدود کنید.)

کیت توسعه نرم‌افزار Cloud

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

درباره کیت توسعه نرم‌افزار Google Cloud ، نصب کیت توسعه نرم‌افزار Cloud ، و فرمان‌های زیر بیشتر بخوانید:

• gcloud services api-keys create

کلید میانای برنامه‌سازی کاربردی را به برنامه‌تان اضافه کنید

این بخش نحوه ذخیره کردن کلید میانای برنامه‌سازی کاربردی را شرح می‌دهد تا برنامه شما بتواند به‌طور ایمن به آن ارجاع دهد. نباید کلید میانای برنامه‌سازی کاربردی را در سیستم کنترل نسخه بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل 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 SDK برای Android، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط اصالت‌سنجی را برای Android Maps API v2 امکان‌پذیر می‌کند. برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند.

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

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

فایل فعالیت‌های Maps

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

عناصر اصلی فعالیت‌های Maps:

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

• شیء GoogleMap دسترسی به داده‌ها و نمای نقشه را فراهم می‌کند. این کلاس اصلی «کیت توسعه نرم‌افزار Google Maps برای Android» است. راهنمای اشیاء نقشه اشیاء SupportMapFragment و GoogleMap را با جزئیات بیشتر شرح می‌دهد.

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

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

فایل Gradle واحد

فایل «واحد» build.gradle.kts شامل وابستگی نقشه‌های زیر است که برای «کیت توسعه نرم‌افزار Google Maps برای Android» لازم است.

dependencies {

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

توجه: نسخه دقیق می‌تواند براساس نسخه فعلی کیت توسعه نرم‌افزار Google Maps برای Android تغییر کند.

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

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

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

• tools:context فعالیت پیش‌فرض قطعه را روی MapsActivity تنظیم می‌کند که در فایل فعالیت Maps تعریف شده است.
• ‫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. در Android Studio، روی گزینه منو اجرا (یا نماد دکمه پخش) کلیک کنید تا برنامه‌تان اجرا شود.
2. وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
   • دستگاه Android متصل به رایانه‌تان را انتخاب کنید.
   • یا دکمه رادیویی راه‌اندازی شبیه‌ساز را انتخاب کنید و دستگاه مجازی‌ای را که راه‌اندازی کرده‌اید انتخاب کنید.
3. روی تأیید کلیک کنید. Android Studio برای ساختن برنامه‌تان Gradle را راه‌اندازی می‌کند و سپس نتایج را در دستگاه یا شبیه‌سازتان نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه‌اندازی شود.

مراحل بعدی

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

• افزودن نقشه به برنامه Android (‏Kotlin): این codelab شما را با برنامه‌ای که برخی‌از ویژگی‌های اضافی «کیت توسعه نرم‌افزار Google Maps برای Android» را نشان می‌دهد آشنا می‌کند.

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