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

برای پیکربندی کردن برنامه‌تان جهت استفاده از «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android»، این مراحل را دنبال کنید. این مجوزها برای همه برنامه‌هایی که از «کیت توسعه نرم‌افزار مکان‌ها ویژه Android» استفاده می‌کنند الزامی است.

مرحله ۱: راه‌اندازی Android Studio

این سند محیط توسعه‌ای را بااستفاده از Android Studio Hedgehog و افزایه Android Gradle نسخه ۸.۲ توصیف می‌کند.

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

کتابخانه «کیت توسعه نرم‌افزار مکان‌ها ویژه Android» ازطریق مخزن Maven Google دردسترس است. برای افزودن کیت توسعه نرم‌افزار به برنامه‌تان، کارهای زیر را انجام دهید:

  1. در فایل settings.gradle.kts سطح بالای خود، درگاه افزایه Gradle، مخزن Google Maven، و مخزن مرکزی Maven را در بلوک pluginManagement بگنجانید. بلوک pluginManagement باید قبل‌از هر عبارت دیگری در اسکریپت ظاهر شود. 
    pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
  2. در فایل settings.gradle.kts سطح بالای خود، مخزن Maven Google و مخزن مرکزی Maven را در بلوک dependencyResolutionManagement اضافه کنید: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
    }
}

  3. در بخش dependencies فایل build.gradle.kts در سطح واحد، وابستگی‌ای به Places SDK for Android اضافه کنید:

    Groovy

    dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
    implementation("com.google.android.libraries.places:places:3.5.0")
}

    Kotlin

              dependencies {

    // Places and Maps SDKs
    implementation("com.google.android.libraries.places:places:6.0.2")
}
  4. در فایل build.gradle.kts سطح واحد، compileSdk و minSdk را روی مقادیر زیر تنظیم کنید:

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}
  5. در بخش buildFeatures فایل build.gradle سطح واحد، کلاس BuildConfig را اضافه کنید، که از آن برای دسترسی به مقادیر فراداده تعریف‌شده در ادامه این رویه استفاده می‌کنید:

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}

    Kotlin

    android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}

مرحله ۳: کلید میانای API را به پروژه اضافه کنید

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

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

برای نصب افزایه Secrets Gradle ویژه Android و ذخیره کلید میانای برنامه‌سازی کاربردی:

  1. در Android Studio، فایل build.gradle.kts سطح بالا یا build.gradle را باز کنید و کد زیر را به بلوک plugins اضافه کنید.

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. فایل build.gradle.kts یا build.gradle در سطح ماژول را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

    Kotlin

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

    Groovy

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
  4. فایل secrets.properties را در فهرست سطح بالای خود باز کنید، و سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید. حتماً secrets.properties را به فایل .gitignore خود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید. 
    PLACES_API_KEY=YOUR_API_KEY

  5. فایل local.defaults.properties را در دایرکتوری سطح بالا، همان پوشه فایل secrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.

    PLACES_API_KEY=DEFAULT_API_KEY

    هدف این فایل ارائه مکان پشتیبان برای کلید API است اگر فایل secrets.properties پیدا نشود تا ساخت‌ها ناموفق نباشند. این وضعیت می‌تواند زمانی روی دهد که برنامه را از سیستم کنترل نسخه که secrets.properties را حذف می‌کند شبیه‌سازی کنید و هنوز فایل secrets.properties را به‌صورت محلی برای ارائه کلید میانای API خود ایجاد نکرده باشید.

  6. در Android Studio، فایل build.gradle.kts یا build.gradle سطح ماژول را باز کنید و ویژگی secrets را ویرایش کنید. اگر دارایی secrets وجود ندارد، آن را اضافه کنید.

    ویژگی‌های افزونه را ویرایش کنید تا propertiesFileName روی "secrets.properties" تنظیم شود، defaultPropertiesFileName روی "local.defaults.properties" تنظیم شود، و هر ویژگی دیگری را تنظیم کنید.

    Kotlin

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

    Groovy

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

مرحله ۴. راه‌اندازی مشتری Places API

برای مقداردهی اولیه Places SDK for Android در یک فعالیت یا قطعه، کلید API را هنگام فراخوانی Places.initializeWithNewPlacesApiEnabled() ارسال کنید:

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)

جاوا

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);

اکنون آماده‌اید تا استفاده از Places SDK for Android را شروع کنید!

مرحله ۵: راه‌اندازی دستگاه Android

برای اجرای برنامه‌ای که از «کیت توسعه نرم‌افزار مکان‌ها برای Android» استفاده می‌کند، باید آن را در دستگاه Android یا شبیه‌ساز Android که مبتنی بر Android 6.0 یا بالاتر است و شامل «میاناهای برنامه‌سازی کاربردی Google» است مستقر کنید.

  • برای استفاده از دستگاه Android، دستورالعمل‌های اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
  • برای استفاده از شبیه‌ساز Android، می‌توانید دستگاهی مجازی ایجاد کنید و شبیه‌ساز را بااستفاده از مدیر دستگاه که همراه با Android Studio ارائه می‌شود نصب کنید.

مراحل بعدی

پس‌از پیکربندی پروژه، می‌توانید برنامه‌های نمونه را کاوش کنید.