راه اندازی

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

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

قبل از اینکه بتوانید با Maps 3D SDK برای اندروید شروع به ساخت برنامه کنید، باید با انجام مراحل زیر، یک پروژه Google Cloud و کلید API برای استفاده با Maps 3D SDK برای اندروید راه‌اندازی کنید:

مرحله ۱

کنسول

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

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

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

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

SDK ابری 

gcloud projects create "PROJECT"

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

مرحله ۲

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

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

برای فعال کردن یک یا چند API یا SDK:

کنسول

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

    به صفحه کتابخانه API نقشه‌ها بروید

  2. روی API یا SDK که می‌خواهید فعال کنید کلیک کنید.
    • اگر روی دکمه عبارت ENABLE نوشته شده بود، برای فعال کردن API یا SDK روی آن کلیک کنید.
    • اگر روی دکمه نوشته شده باشد «مدیریت» ، یعنی API یا SDK از قبل فعال شده است و نیازی به انجام کار بیشتری نیست.
    • با کلیک بر روی هر یک از دکمه‌ها، داشبورد مربوط به API یا SDK نمایش داده می‌شود. (برای حذف API یا SDK از این پروژه، روی دکمه غیرفعال کردن (DISABLE) کلیک کنید.)

SDK ابری

دستور زیر تمام APIهای نقشه‌ها، مسیرها و مکان‌ها را فعال می‌کند:

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 SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:

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

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

مرحله ۳

این مرحله فقط فرآیند ایجاد کلید 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 و دستورات زیر بیشتر بخوانید:

برای فعال کردن SDK، به صفحه Maps 3D SDK for Android در کنسول Google Cloud مراجعه کنید. برای اطلاعات بیشتر در مورد انجام این مراحل، به شروع به کار با پلتفرم Google Maps مراجعه کنید.

راه اندازی پروژه اندروید استودیو

این بخش نحوه ایجاد و پیکربندی یک پروژه اندروید استودیو برای استفاده با Maps 3D SDK برای اندروید را توضیح می‌دهد.

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

  1. با استفاده از الگوی Empty Views Activity، یک پروژه جدید اندروید استودیو ایجاد کنید.

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

    • در دایرکتوری ریشه پروژه خود، فایل .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 در پوشه ریشه پروژه قرار دارد، باز کنید. - در بخش نسخه‌ها، نسخه‌های SDK و افزونه Secrets Gradle را اضافه کنید:

    maps3dSdk = "0.0.1" # Update this value to match the SDK version to include
secretsGradlePlugin = "2.0.1"

    -   In the library section, add the SDK library:

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

    -   In the plugin section, add the Secrets Gradle plugin:

    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
}

    -   In the `dependencies` block, add the SDK:

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

    -   At the end of the file, outside of the `android` and `dependencies`
    blocks, add the secrets configuration:

    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 (معمولاً دایرکتوری app )، یک فایل جدید با نام secrets.properties ایجاد کنید.
    • کلید API خود را به فایل اضافه کنید: 
    MAPS3D_API_KEY=YOUR_API_KEY_HERE
``` Note: Make sure you
    replace `YOUR_API_KEY_HERE` with the API key that you configured for use
with the Maps 3D SDK for Android.

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

    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 شما جایگزین می‌کند.

مراحل بعدی

حالا که یک پروژه گوگل کلود، کلید API و یک پروژه اندروید استودیو برای استفاده با Maps 3D SDK برای اندروید تنظیم کرده‌اید، می‌توانید یک نقشه سه‌بعدی به برنامه خود اضافه کنید .