تنظیم

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

پیش‌نیازها

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

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

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

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

مرحله ۱: راه‌اندازی پروژه

gcloud projects create "PROJECT"

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

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

توجه داشته باشید که برخی‌از ادغام‌ها مستلزم آن است که چندین میانای برنامه‌سازی کاربردی/ کیت توسعه نرم‌افزار را فعال کنید. اگر مطمئن نیستید کدام میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار را فعال کنید، از کاوشگر قابلیت‌ها استفاده کنید یا اسناد مربوط به میانای برنامه‌سازی کاربردی/کیت توسعه نرم‌افزار موردنظرتان را بررسی کنید.

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

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"

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

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

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

برای فعال کردن کیت توسعه نرم‌افزار، به صفحه کیت توسعه نرم‌افزار ۳ بعدی نقشه برای 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]، نسخه‌های کیت توسعه نرم‌افزار و افزونه Gradle Secrets را اضافه کنید:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # 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"
   }
   

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

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

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

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

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

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

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

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

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

   <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» را برای استفاده با «کیت توسعه نرم‌افزار سه‌بعدی Maps برای Android» راه‌اندازی کرده‌اید، می‌توانید نقشه سه‌بعدی به برنامه‌تان اضافه کنید.