Maps SDK برای Android Quick Start

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

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

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

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

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

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

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

ایجاد پروژه نقشه گوگل در اندروید استودیو

روش ایجاد یک پروژه نقشه گوگل در اندروید استودیو در نسخه Flamingo و نسخه‌های بعدی اندروید استودیو تغییر کرد.

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

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

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

    • زبان را روی جاوا یا کاتلین تنظیم کنید. هر دو زبان به طور کامل توسط Maps SDK برای اندروید پشتیبانی می‌شوند. برای کسب اطلاعات بیشتر در مورد کاتلین، به بخش «توسعه برنامه‌های اندروید با کاتلین» مراجعه کنید.

    • حداقل SDK را روی نسخه SDK سازگار با دستگاه آزمایشی خود تنظیم کنید. شما باید نسخه‌ای بزرگتر از حداقل نسخه مورد نیاز Maps SDK برای اندروید نسخه 20.0.x، که Android API Level 23 ("Marshmallow"؛ اندروید 6.0) یا بالاتر است، انتخاب کنید. برای آخرین اطلاعات در مورد الزامات نسخه SDK، به یادداشت‌های انتشار مراجعه کنید.

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

  4. روی پایان کلیک کنید.

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

  5. فعالیت Views نقشه‌های گوگل را اضافه کنید:

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

    2. گزینه جدید > گوگل > فعالیت بازدیدهای نقشه‌های گوگل را انتخاب کنید.

      یک فعالیت نقشه اضافه کنید.

    3. در کادر محاوره‌ای «فعالیت جدید اندروید» ، کادر انتخاب «فعالیت لانچر» را علامت بزنید.

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

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

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

پروژه گوگل کلود خود را راه‌اندازی کنید

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

مرحله ۱

کنسول

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

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

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

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

SDK ابری 

gcloud projects create "PROJECT"

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

مرحله ۲

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

کنسول

فعال کردن SDK نقشه‌ها برای اندروید

SDK ابری 

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

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

مرحله ۳

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

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

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

کنسول

  1. به صفحه Google Maps Platform > Credentials بروید.

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

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

SDK ابری 

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

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

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

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

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

برای نصب افزونه Secrets Gradle برای اندروید و ذخیره کلید API خود:

  1. در اندروید استودیو، فایل 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 سطح برنامه خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

    گرووی 

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    کاتلین 

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. اگر از اندروید استودیو استفاده می‌کنید، پروژه خود را با 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 نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Maps SDK برای اندروید، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

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

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

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

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

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

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

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

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

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

فایل گرادل ماژول

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

dependencies {

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

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

فایل طرح‌بندی 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. در اندروید استودیو، برای اجرای برنامه خود، روی گزینه منوی Run (یا نماد دکمه پخش) کلیک کنید.
  2. وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
    • دستگاه اندرویدی که به رایانه شما متصل است را انتخاب کنید.
    • روش دیگر این است که دکمه رادیویی Launch emulator را انتخاب کنید و دستگاه مجازی که راه‌اندازی کرده‌اید را انتخاب کنید.
  3. روی تأیید کلیک کنید. اندروید استودیو Gradle را برای ساخت برنامه شما شروع می‌کند و سپس نتایج را روی دستگاه یا شبیه‌ساز شما نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه اجرا شود.

مراحل بعدی

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

  • اضافه کردن نقشه به برنامه اندروید (کاتلین) : این آزمایشگاه کد، شما را با برنامه‌ای آشنا می‌کند که برخی از ویژگی‌های اضافی Maps SDK برای اندروید را نشان می‌دهد.

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

،

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

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

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

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

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

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

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

ایجاد پروژه نقشه گوگل در اندروید استودیو

روش ایجاد یک پروژه نقشه گوگل در اندروید استودیو در نسخه Flamingo و نسخه‌های بعدی اندروید استودیو تغییر کرد.

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

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

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

    • زبان را روی جاوا یا کاتلین تنظیم کنید. هر دو زبان به طور کامل توسط Maps SDK برای اندروید پشتیبانی می‌شوند. برای کسب اطلاعات بیشتر در مورد کاتلین، به بخش «توسعه برنامه‌های اندروید با کاتلین» مراجعه کنید.

    • حداقل SDK را روی نسخه SDK سازگار با دستگاه آزمایشی خود تنظیم کنید. شما باید نسخه‌ای بزرگتر از حداقل نسخه مورد نیاز Maps SDK برای اندروید نسخه 20.0.x، که Android API Level 23 ("Marshmallow"؛ اندروید 6.0) یا بالاتر است، انتخاب کنید. برای آخرین اطلاعات در مورد الزامات نسخه SDK، به یادداشت‌های انتشار مراجعه کنید.

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

  4. روی پایان کلیک کنید.

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

  5. فعالیت Views نقشه‌های گوگل را اضافه کنید:

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

    2. گزینه جدید > گوگل > فعالیت بازدیدهای نقشه‌های گوگل را انتخاب کنید.

      یک فعالیت نقشه اضافه کنید.

    3. در کادر محاوره‌ای «فعالیت جدید اندروید» ، کادر انتخاب «فعالیت لانچر» را علامت بزنید.

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

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

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

پروژه گوگل کلود خود را راه‌اندازی کنید

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

مرحله ۱

کنسول

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

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

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

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

SDK ابری 

gcloud projects create "PROJECT"

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

مرحله ۲

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

کنسول

فعال کردن SDK نقشه‌ها برای اندروید

SDK ابری 

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

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

مرحله ۳

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

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

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

کنسول

  1. به صفحه Google Maps Platform > Credentials بروید.

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

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

SDK ابری 

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

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

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

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

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

برای نصب افزونه Secrets Gradle برای اندروید و ذخیره کلید API خود:

  1. در اندروید استودیو، فایل 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 سطح برنامه خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

    گرووی 

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    کاتلین 

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. اگر از اندروید استودیو استفاده می‌کنید، پروژه خود را با 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 نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Maps SDK برای اندروید، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

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

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

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

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

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

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

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

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

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

فایل گرادل ماژول

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

dependencies {

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

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

فایل طرح‌بندی 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. در اندروید استودیو، برای اجرای برنامه خود، روی گزینه منوی Run (یا نماد دکمه پخش) کلیک کنید.
  2. وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
    • دستگاه اندرویدی که به رایانه شما متصل است را انتخاب کنید.
    • روش دیگر این است که دکمه رادیویی Launch emulator را انتخاب کنید و دستگاه مجازی که راه‌اندازی کرده‌اید را انتخاب کنید.
  3. روی تأیید کلیک کنید. اندروید استودیو Gradle را برای ساخت برنامه شما شروع می‌کند و سپس نتایج را روی دستگاه یا شبیه‌ساز شما نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه اجرا شود.

مراحل بعدی

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

  • اضافه کردن نقشه به برنامه اندروید (کاتلین) : این آزمایشگاه کد، شما را با برنامه‌ای آشنا می‌کند که برخی از ویژگی‌های اضافی Maps SDK برای اندروید را نشان می‌دهد.

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

،

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

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

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

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

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

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

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

ایجاد پروژه نقشه گوگل در اندروید استودیو

روش ایجاد یک پروژه نقشه گوگل در اندروید استودیو در نسخه Flamingo و نسخه‌های بعدی اندروید استودیو تغییر کرد.

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

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

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

    • زبان را روی جاوا یا کاتلین تنظیم کنید. هر دو زبان به طور کامل توسط Maps SDK برای اندروید پشتیبانی می‌شوند. برای کسب اطلاعات بیشتر در مورد کاتلین، به بخش «توسعه برنامه‌های اندروید با کاتلین» مراجعه کنید.

    • حداقل SDK را روی نسخه SDK سازگار با دستگاه آزمایشی خود تنظیم کنید. شما باید نسخه‌ای بزرگتر از حداقل نسخه مورد نیاز Maps SDK برای اندروید نسخه 20.0.x، که Android API Level 23 ("Marshmallow"؛ اندروید 6.0) یا بالاتر است، انتخاب کنید. برای آخرین اطلاعات در مورد الزامات نسخه SDK، به یادداشت‌های انتشار مراجعه کنید.

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

  4. روی پایان کلیک کنید.

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

  5. فعالیت Views نقشه‌های گوگل را اضافه کنید:

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

    2. گزینه جدید > گوگل > فعالیت بازدیدهای نقشه‌های گوگل را انتخاب کنید.

      یک فعالیت نقشه اضافه کنید.

    3. در کادر محاوره‌ای «فعالیت جدید اندروید» ، کادر انتخاب «فعالیت لانچر» را علامت بزنید.

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

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

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

پروژه گوگل کلود خود را راه‌اندازی کنید

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

مرحله ۱

کنسول

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

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

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

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

SDK ابری 

gcloud projects create "PROJECT"

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

مرحله ۲

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

کنسول

فعال کردن SDK نقشه‌ها برای اندروید

SDK ابری 

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

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

مرحله ۳

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

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

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

کنسول

  1. به صفحه Google Maps Platform > Credentials بروید.

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

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

SDK ابری 

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

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

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

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

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

برای نصب افزونه Secrets Gradle برای اندروید و ذخیره کلید API خود:

  1. در اندروید استودیو، فایل 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 سطح برنامه خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

    گرووی 

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    کاتلین 

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. اگر از اندروید استودیو استفاده می‌کنید، پروژه خود را با 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 نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Maps SDK برای اندروید، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

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

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

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

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

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

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

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

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

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

فایل گرادل ماژول

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

dependencies {

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

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

فایل طرح‌بندی 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. در اندروید استودیو، برای اجرای برنامه خود، روی گزینه منوی Run (یا نماد دکمه پخش) کلیک کنید.
  2. وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
    • دستگاه اندرویدی که به رایانه شما متصل است را انتخاب کنید.
    • روش دیگر این است که دکمه رادیویی Launch emulator را انتخاب کنید و دستگاه مجازی که راه‌اندازی کرده‌اید را انتخاب کنید.
  3. روی تأیید کلیک کنید. اندروید استودیو Gradle را برای ساخت برنامه شما شروع می‌کند و سپس نتایج را روی دستگاه یا شبیه‌ساز شما نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه اجرا شود.

مراحل بعدی

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

  • اضافه کردن نقشه به برنامه اندروید (کاتلین) : این آزمایشگاه کد، شما را با برنامه‌ای آشنا می‌کند که برخی از ویژگی‌های اضافی Maps SDK برای اندروید را نشان می‌دهد.

  • Use the Maps Android KTX library : This Kotlin extensions (KTX) library lets you take advantage of several Kotlin language features while using the Maps SDK for Android.

،

Create an Android app that displays a map by using the Google Maps Views template for Android Studio. If you have an existing Android Studio project that you'd like to set up, see Set up an Android Studio project .

This quickstart is intended for developers who are familiar with basic Android development with Kotlin or Java.

About the development environment

This quickstart was developed using Android Studio Hedgehog and the Android Gradle plugin version 8.2.

Set up an Android device

To run an app that uses the Maps SDK for Android, you must deploy it to an Android device or Android emulator that is based on Android 6.0 or higher and includes the Google APIs.

  • To use an Android device, follow the instructions at Run apps on a hardware device .
  • To use an Android emulator, you can create a virtual device and install the emulator by using the Android Virtual Device (AVD) Manager that comes with Android Studio.

Create a Google Maps project in Android Studio

The procedure to create a Google Maps project in Android Studio was changed in the Flamingo and later releases of Android Studio.

  1. Open Android Studio, and click New Project in the Welcome to Android Studio window.

  2. In the New Project window, under the Phone and Tablet category, select No Activity , and then click Next .

  3. Complete the New Project form:

    • Set Language to Java or Kotlin. Both languages are fully supported by the Maps SDK for Android. To learn more about Kotlin, see Develop Android apps with Kotlin .

    • Set Minimum SDK to an SDK version compatible with your test device. You must select a version greater than the minimum version required by the Maps SDK for Android version 20.0.x, which is Android API Level 23 ("Marshmallow"; Android 6.0) or higher. See the Release Notes for the latest information on the SDK version requirements.

    • Set the Build configuration language to Kotlin DSL or Groovy DSL. Snippets for both build configurations languages are shown in the following procedures.

  4. روی پایان کلیک کنید.

    Android Studio starts Gradle and builds the project. This may take some time.

  5. Add the Google Maps Views Activity :

    1. Right-click on the app folder in your project.

    2. Select New > Google > Google Maps Views Activity .

      Add a maps activity.

    3. In the New Android Activity dialog box, select the Launcher Activity checkbox.

    4. Select Finish .

      For more information, see Add code from a template

  6. When the build is finished, Android Studio opens the AndroidManifest.xml and MapsActivity files. Your activity may have a different name, but it is the one you configured during setup.

Set up your Google Cloud project

Complete the required Cloud console setup steps by clicking through the following tabs:

مرحله ۱

کنسول

  1. In the Google Cloud console, on the project selector page, click Create Project to begin creating a new Cloud project.

    Go to the project selector page

  2. Make sure that billing is enabled for your Cloud project. Confirm that billing is enabled for your project .

    Google Cloud offers a $0.00 charge trial. The trial expires at either end of 90 days or after the account has accrued $300 worth of charges, whichever comes first. Cancel anytime. For more information, see Billing account credits and Billing .

Cloud SDK 

gcloud projects create "PROJECT"

Read more about the Google Cloud SDK , Cloud SDK installation , and the following commands:

مرحله ۲

To use Google Maps Platform, you must enable the APIs or SDKs you plan to use with your project.

کنسول

Enable the Maps SDK for Android

Cloud SDK 

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

Read more about the Google Cloud SDK , Cloud SDK installation , and the following commands:

مرحله ۳

This step only goes through the API Key creation process. If you use your API Key in production, we strongly recommend that you restrict your API key. You can find more information in the product-specific Using API Keys page.

The API key is a unique identifier that authenticates requests associated with your project for usage and billing purposes. You must have at least one API key associated with your project.

To create an API key:

کنسول

  1. Go to the Google Maps Platform > Credentials page.

    Go to the Credentials page

  2. On the Credentials page, click Create credentials > API key .
    The API key created dialog displays your newly created API key.
  3. Click Close.
    The new API key is listed on the Credentials page under API keys .
    (Remember to restrict the API key before using it in production.)

Cloud SDK 

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

Read more about the Google Cloud SDK , Cloud SDK installation , and the following commands:

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

This section describes how to store your API key so that it can be securely referenced by your app. You shouldn't check your API key into your version control system, so we recommend storing it in the secrets.properties file, which is located in the root directory of your project. For more information about the secrets.properties file, see Gradle properties files .

To streamline this task, we recommend that you use the Secrets Gradle Plugin for Android .

To install the Secrets Gradle Plugin for Android and store your API key:

  1. In Android Studio, open your root-level build.gradle file and add the following code to the dependencies element under 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.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    کاتلین 

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. If you use Android Studio, sync your project with 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}" />

    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.

Look at the code

Examine the code supplied by the template. In particular, look at the following files in your Android Studio project.

Maps activity file

The maps activity file is the main activity for the app, and contains the code to manage and display the map. By default, the file that defines the activity is named MapsActivity.java or if you set Kotlin as the language for your app, MapsActivity.kt .

The main elements of the maps activity:

  • The SupportMapFragment object manages the lifecycle of the map and is the parent element of the app's UI.

  • The GoogleMap object provides access to the map data and view. This is the main class of the Maps SDK for Android. The Map Objects guide describes the SupportMapFragment and GoogleMap objects in more detail.

  • The moveCamera function centers the map at the LatLng coordinates for Sydney Australia. The first settings to configure when adding a map are usually the map location and camera settings; such as viewing angle, map orientation, and zoom level. See the Camera and View guide for details.

  • The addMarker function adds a marker to the coordinates for Sydney. See the Markers guide for details.

Module Gradle file

The Module build.gradle.kts file includes the following maps dependency, which is required by the Maps SDK for Android. 

dependencies {

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

To learn more about managing the Maps dependency, see Versioning .

XML layout file

The activity_maps.xml file is the XML layout file that defines the structure of the app's UI. The file is located in the res/layout directory. The activity_maps.xml file declares a fragment that includes the following elements:

  • tools:context sets the default activity of the fragment to MapsActivity , which is defined in the maps activity file.
  • android:name sets the class name of the fragment to SupportMapFragment , which is the fragment type used in the maps activity file.

The XML layout file contains the following code: 

<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" />

Deploy and run the app

Screenshot with the map and marker centered on Syndney Australia.

When you run the app successfully, it will display a map that is centered on Sydney Australia with a marker on the city as seen in the following screenshot.

To deploy and run the app:

  1. In Android Studio, click the Run menu option (or the play button icon) to run your app.
  2. When prompted to choose a device, choose one of the following options:
    • Select the Android device that's connected to your computer.
    • Alternatively, select the Launch emulator radio button and choose the virtual device that you set up.
  3. Click OK . Android Studio will start Gradle to build your app, and then display the results on your device or emulator. It can take several minutes before the app launches.

مراحل بعدی

  • Set up a map : This document describes how to set up the initial and runtime settings for your map, such as the camera position, map type, UI components, and gestures.

  • Add a map to your Android app (Kotlin) : This codelab walks you through an app that demonstrates some additional features of the Maps SDK for Android.

  • Use the Maps Android KTX library : This Kotlin extensions (KTX) library lets you take advantage of several Kotlin language features while using the Maps SDK for Android.