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

برای پیکربندی برنامه خود برای استفاده از Places SDK برای اندروید، این مراحل را دنبال کنید. این مراحل برای همه برنامه‌هایی که از Places SDK برای اندروید استفاده می‌کنند، الزامی است.

مرحله ۱: راه‌اندازی اندروید استودیو

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

مرحله ۲. راه‌اندازی SDK

کتابخانه Places SDK برای اندروید از طریق مخزن Maven گوگل در دسترس است. برای افزودن SDK به برنامه خود، موارد زیر را انجام دهید:

1. در فایل سطح بالای settings.gradle.kts خود، Gradle plugin portal ، Google Maven repository و Maven central repository را در زیر بلوک pluginManagement قرار دهید. بلوک pluginManagement باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. در فایل سطح بالای settings.gradle.kts ، مخزن Maven گوگل و مخزن مرکزی Maven را در زیر بلوک dependencyResolutionManagement قرار دهید:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. در بخش dependencies فایل module -level build.gradle.kts ، یک وابستگی به Places SDK برای اندروید اضافه کنید:

   گرووی

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

   کاتلین

             dependencies {
   
       // Places and Maps SDKs
       implementation("com.google.android.libraries.places:places:5.0.0")
   }

4. در فایل build.gradle.kts در سطح ماژول، compileSdk و minSdk را روی مقادیر زیر تنظیم کنید:

   گرووی

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 23
           // ...
       }
   }

   کاتلین

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 23
           // ...
       }
   }

5. در بخش buildFeatures از فایل build.gradle در سطح ماژول، کلاس BuildConfig اضافه کنید که برای دسترسی به مقادیر متادیتای تعریف شده در ادامه این رویه استفاده می‌شود:

   گرووی

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

   کاتلین

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

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

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

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

برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps خود:

1. در اندروید استودیو، فایل سطح بالای build.gradle.kts یا build.gradle خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.

   کاتلین

   plugins {
       alias(libs.plugins.android.application) apply false
       alias(libs.plugins.jetbrains.kotlin.android) apply false
       alias(libs.plugins.kotlin.compose) apply false
       alias(libs.plugins.secrets.gradle.plugin) apply false
   }

   گرووی

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. فایل build.gradle.kts یا build.gradle سطح ماژول خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

   کاتلین

   plugins {
       // ...
       alias(libs.plugins.secrets.gradle.plugin)
   }

   گرووی

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی ۳۴ تنظیم شده‌اند.
4. پروژه خود را با Gradle همگام‌سازی کنید .
5. فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. YOUR_API_KEY با کلید API خود جایگزین کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی در سیستم کنترل نسخه مستثنی است.

   PLACES_API_KEY=YOUR_API_KEY

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

   PLACES_API_KEY=DEFAULT_API_KEY

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

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

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

   کاتلین

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"
   }
           

   گرووی

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the 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 برای اندروید درون یک اکتیویتی یا فرگمنت، کلید API را هنگام فراخوانی Places.initializeWithNewPlacesApiEnabled() ارسال کنید:

    // 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 برای اندروید استفاده کنید!

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

برای اجرای برنامه‌ای که از Places SDK برای اندروید استفاده می‌کند، باید آن را روی یک دستگاه اندروید یا شبیه‌ساز اندروید که مبتنی بر اندروید ۵.۰ یا بالاتر است و شامل APIهای گوگل است، مستقر کنید.

• برای استفاده از دستگاه اندروید، دستورالعمل‌های موجود در «اجرای برنامه‌ها روی دستگاه سخت‌افزاری» را دنبال کنید.
• برای استفاده از شبیه‌ساز اندروید، می‌توانید یک دستگاه مجازی ایجاد کنید و با استفاده از Android Virtual Device Manager (AVD) که همراه با اندروید استودیو ارائه می‌شود، شبیه‌ساز را نصب کنید.

مراحل بعدی