در روز انجمن توسعه‌دهندگان Google Maps Platform بعدی ما در ماه دسامبر در سانفرانسیسکو به ما بپیوندید! برای شرکت کردن، اکنون درخواست دهید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

تنظیم

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

مرحله ۱

کنسول

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

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

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

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

gcloud projects create "PROJECT"

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

gcloud projects create

مرحله ۲

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

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

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

کنسول

با رفتن به صفحه «کتابخانه Maps API» در کنسول Cloud، میاناهای برنامه‌سازی کاربردی و کیت‌های توسعه نرم‌افزار Google Maps Platform را که می‌توانید فعال کنید ببینید:

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

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

فرمان زیر همه میاناهای برنامه‌سازی کاربردی Maps،‏ Routes، و Places را فعال می‌کند:

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"

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

از این فرمان برای فعال کردن Environment APIs استفاده کنید:

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

مرحله ۳

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

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

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

کنسول

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

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

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

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

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

gcloud services api-keys create

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

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

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

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

بااستفاده از الگوی Empty Views Activity، پروژه جدیدی در «استودیو Android» ایجاد کنید. در پیکربندی پروژه، حداقل کیت توسعه نرم‌افزار را روی میانای برنامه‌سازی کاربردی ۲۴ یا بالاتر تنظیم کنید.
اگر از Git برای کنترل منبع استفاده می‌کنید، فایل پروژه .gitignore را اصلاح کنید تا از ارسال فایل اطلاعات محرمانه شما به کنترل نسخه جلوگیری شود:
- در دایرکتوری ریشه پروژه‌تان، فایل .gitignore را باز کنید.
- خط زیر را اضافه کنید:
```
secrets.properties
```
فایل 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
}
```
فایل 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" }
```

فایل 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 به پروژه

ایجاد فایل secrets.properties:
- در دایرکتوری ریشه ماژول برنامه (معمولاً دایرکتوری app)، فایل جدیدی با نام secrets.properties ایجاد کنید.
- کلید میانای API خود را به فایل اضافه کنید:
```
MAPS3D_API_KEY=YOUR_API_KEY_HERE
```
توجه: حتماً YOUR_API_KEY_HERE را با کلید میانای برنامه‌سازی کاربردی که برای استفاده با «کیت توسعه نرم‌افزار ۳ بعدی نقشه برای Android» پیکربندی کرده‌اید جایگزین کنید.
فایل local.defaults.properties ایجاد کنید: - در دایرکتوری ریشه ماژول برنامه، فایل جدیدی با نام local.defaults.properties ایجاد کنید. - کلید میانای برنامه‌سازی کاربردی پیش‌فرض یا جای‌بان را به فایل اضافه کنید. این فایل را می‌توان در کنترل نسخه بررسی کرد:
```
MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
```

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

فایل app/src/main/AndroidManifest.xml را باز کنید.
در داخل برچسب <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» را برای استفاده با «کیت توسعه نرم‌افزار سه‌بعدی Maps برای Android» راه‌اندازی کرده‌اید، می‌توانید نقشه سه‌بعدی به برنامه‌تان اضافه کنید.

تنظیم با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیش‌نیازها

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

مرحله ۱

کنسول

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

مرحله ۲

کنسول

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

مرحله ۳

کنسول

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

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

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

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

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

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

مراحل بعدی

تنظیم

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