تنظیم

این صفحه توضیح می‌دهد که برای آماده شدن برای شروع ساخت با کیت توسعه نرم‌افزار ۳ بعدی نقشه برای Android چه کاری باید انجام دهید. فرایند راه‌اندازی شامل پیکربندی پروژه Google Cloud و API برای استفاده با SDK، و سپس راه‌اندازی پروژه Android Studio است. این مراحل را قبل‌از افزودن اولین نقشه سه‌بعدی به برنامه‌تان تکمیل کنید.

پیش‌نیازها

برای استفاده از «کیت توسعه نرم‌افزار ۳ بعدی نقشه برای Android»، پروژه و دستگاه‌های هدف شما باید پیش‌نیازهای زیر را داشته باشند:

• حداقل سطح API: سطح API Android 24 (Android 7.0) یا بالاتر. برنامه شما باید minSdk 24 یا بالاتر را هدف‌یابی کند.
• خدمات Google Play: «کیت توسعه نرم‌افزار ۳ بعدی Maps برای Android» به خدمات Google Play وابسته است. دستگاه‌های هدف (و شبیه‌سازهای دارای «میاناهای برنامه‌سازی کاربردی Google») باید «خدمات Google Play» را نصب کرده باشند.

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

قبل‌از اینکه بتوانید با «کیت توسعه نرم‌افزار ۳ بعدی Maps برای Android» بسازید، باید با تکمیل مراحل زیر، پروژه Google Cloud و کلید API را برای استفاده با «کیت توسعه نرم‌افزار ۳ بعدی Maps برای Android» راه‌اندازی کنید:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

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

برای فعال کردن کیت توسعه نرم‌افزار، به صفحه کیت توسعه نرم‌افزار سه‌بعدی Maps برای Android در کنسول Google Cloud مراجعه کنید. برای اطلاعات بیشتر درباره تکمیل این مراحل، به شروع به کار با Google Maps Platform مراجعه کنید.

راه‌اندازی پروژه «استودیو Android»

این بخش نحوه ایجاد و پیکربندی پروژه Android Studio را برای استفاده با «کیت توسعه نرم‌افزار سه‌بعدی Maps برای Android» توضیح می‌دهد.

بخش ۱: راه‌اندازی پروژه و پیکربندی Gradle

1. بااستفاده از الگوی Empty Views Activity، پروژه «استودیو Android» جدیدی ایجاد کنید. در پیکربندی پروژه، حداقل کیت توسعه نرم‌افزار را روی میانای برنامه‌سازی کاربردی ۲۴ یا بالاتر تنظیم کنید.

2. اگر از Git برای کنترل منبع استفاده می‌کنید، فایل پروژه .gitignore را تغییر دهید تا از تعهد فایل رمزهایتان به کنترل نسخه جلوگیری کنید:

   • در دایرکتوری ریشه پروژه‌تان، فایل .gitignore را باز کنید.
   • خط زیر را اضافه کنید:

   secrets.properties
   

3. فایل build.gradle.kts سطح پروژه را به‌روز کنید:

   • در دایرکتوری ریشه پروژه‌تان، فایل build.gradle.kts را باز کنید.
   • در بلوک plugins، افزایه Secrets Gradle را اضافه کنید:

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. به‌روزرسانی فایل gradle/libs.versions.toml:

   • فایل gradle/libs.versions.toml را باز کنید، که معمولاً در دایرکتوری gradle در دایرکتوری ریشه پروژه قرار دارد.
   • در بخش [versions]، نسخه‌های کیت توسعه نرم‌افزار و افزایه Secrets Gradle را اضافه کنید:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.0"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • در بخش [library]، کتابخانه کیت توسعه نرم‌افزار را اضافه کنید:

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • در بخش [plugins]، افزایه Secrets Gradle را اضافه کنید:

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. فایل app/build.gradle.kts سطح واحد را به‌روز کنید:

   • فایل build.gradle.kts در سطح ماژول را باز کنید که معمولاً در فهرست راهنمای app قرار دارد.
   • در بالای فایل، افزایه Secrets Gradle را به plugins بلوک اضافه کنید:

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • در بلوک dependencies، وابستگی خدمات Google Play را برای کیت توسعه نرم‌افزار سه‌بعدی Maps برای Android اضافه کنید:

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • در انتهای فایل، خارج از بلوک‌های android و dependencies، پیکربندی اطلاعات محرمانه را اضافه کنید:

   secrets {
       // Optionally specify a different filename containing your secrets.
       // The plugin defaults to "local.properties"
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
   

بخش ۲: افزودن کلید میانای برنامه‌سازی کاربردی به پروژه

1. ایجاد فایل secrets.properties:

   • در دایرکتوری ریشه ماژول برنامه (معمولاً دایرکتوری app)، فایل جدیدی با نام secrets.properties ایجاد کنید.
   • کلید میانای API خود را به فایل اضافه کنید:

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

2. فایل local.defaults.properties ایجاد کنید: - در دایرکتوری ریشه ماژول برنامه، فایل جدیدی با نام local.defaults.properties ایجاد کنید. - یک کلید API پیش‌فرض یا جای‌بان به فایل اضافه کنید. این فایل را می‌توان در کنترل نسخه بررسی کرد:

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

بخش ۳: به‌روزرسانی فایل AndroidManifest.xml

1. فایل app/src/main/AndroidManifest.xml را باز کنید.

2. در داخل برچسب <application>، قبل‌از برچسب <activity>، عنصر <meta-data> زیر را برای اعلام کلید API خود اضافه کنید:

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   درطول فرایند ساخت، «افزایه Secrets Gradle» جای‌بان ${MAPS3D_API_KEY} را با کلید موجود در فایل secrets.properties جایگزین خواهد کرد.

مقداردهی اولیه نمای برنامه‌ریزی‌شده (اختیاری)

اگر ترجیح می‌دهید نمای نقشه را به‌جای چیدمان‌های XML به‌صورت برنامه‌نویسی‌شده مقداردهی اولیه کنید، از Map3DInitConfig استفاده کنید.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

مراحل بعدی

اکنون که پروژه Google Cloud، کلید API، و پروژه Android Studio را برای استفاده با Maps 3D SDK ویژه Android راه‌اندازی کرده‌اید، می‌توانید نقشه سه‌بعدی به برنامه‌تان اضافه کنید.