Maps SDK برای Android Quick Start

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

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

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

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

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

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

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

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

  

یک پروژه 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 به یادداشت های انتشار مراجعه کنید.

     توجه: اگر مطمئن نیستید که چه نسخه SDK را انتخاب کنید، پیوند کمک به من را انتخاب کنید تا اطلاعات توزیع برای کیت‌های توسعه نرم‌افزار پشتیبانی‌شده Android نمایش داده شود. به عنوان مثال، اگر Android API سطح 21 ("Lollipop"؛ Android 5.0) را انتخاب کنید، برنامه شما باید در بیش از 99٪ از دستگاه های Android اجرا شود.

   • زبان پیکربندی 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 را باز می‌کند. فعالیت شما ممکن است نام دیگری داشته باشد، اما نامی است که در حین راه اندازی پیکربندی کرده اید.

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

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

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

مرحله 1

کنسول

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

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

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

   Google Cloud یک شارژ آزمایشی 0.00 دلاری ارائه می دهد. دوره آزمایشی در پایان 90 روز یا پس از جمع‌آوری هزینه‌های 300 دلاری، هر کدام که زودتر اتفاق بیفتد، منقضی می‌شود. هر زمان خواستید لغو کنید. پلتفرم نقشه های گوگل دارای اعتبار ماهیانه 200 دلاری است. برای اطلاعات بیشتر، اعتبارات حساب صورت‌حساب و صورت‌حساب را ببینید.

Cloud SDK

gcloud projects create "PROJECT"

درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:

• gcloud projects create

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

مرحله 2

برای استفاده از پلتفرم نقشه های گوگل، باید API ها یا SDK هایی را که قصد دارید در پروژه خود استفاده کنید، فعال کنید.

کنسول

Maps SDK را برای اندروید فعال کنید

Cloud SDK

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

درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:

• gcloud services enable
• gcloud services disable

مرحله 3

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

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

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

کنسول

1. به صفحه پلتفرم نقشه های گوگل > اعتبارنامه بروید.

   به صفحه اعتبارنامه بروید

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

Cloud SDK

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

درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:

• gcloud alpha services api-keys create

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

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

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

توجه: برای اطلاع از آخرین مورد نیاز سیستم و دستورالعمل‌های نصب، به مستندات Android Secrets Gradle Plugin در GitHub مراجعه کنید.

برای نصب افزونه 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 در سیستم کنترل نسخه بررسی نمی شود.
   توجه: اگر فایل secrets.properties وجود ندارد، آن را در همان پوشه ای که فایل local.properties وجود دارد ایجاد کنید.

   MAPS_API_KEY=YOUR_API_KEY

6. فایل را ذخیره کنید.

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

   توجه: کد را مطابق شکل وارد کنید. DEFAULT_API_KEY با کلید API خود جایگزین نکنید.

   MAPS_API_KEY=DEFAULT_API_KEY

   هدف این فایل این است که در صورت یافت نشدن فایل secrets.properties ، یک مکان پشتیبان برای کلید API فراهم کند تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه که 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 Maps در پلتفرم 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 SDK برای Android تغییر کند.

برای کسب اطلاعات بیشتر در مورد مدیریت وابستگی 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 استفاده کنید.