این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

مرحله 1: Android Studio را راه اندازی کنید

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

مرحله 2. SDK را تنظیم کنید

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

در فایل settings.gradle.kts سطح بالای خود، پورتال پلاگین Gradle ، مخزن Google Maven و مخزن مرکزی Maven را در بلوک pluginManagement قرار دهید. بلوک pluginManagement باید قبل از هر عبارت دیگری در اسکریپت ظاهر شود.
```
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
} 
```

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

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

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

توجه: Places SDK برای اندروید نسخه 3.5.0 به kotlin-bom 1.8.0 یا جدیدتر نیاز دارد. برای اطلاعات بیشتر در مورد وابستگی kotlin-bom ، به استفاده از آخرین نسخه kotlin-stdlib در وابستگی های متعدی مراجعه کنید.

شیار

dependencies {
    // If updating kotlin-bom version number above, also edit project-level build.gradle definition of $kotlin_version variable
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
    implementation 'com.google.android.libraries.places:places:3.3.0'
}

کاتلین

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

در فایل build.gradle سطح ماژول خود، compileSdk و minSdk را روی مقادیر زیر تنظیم کنید:
توجه: مطمئن شوید که compileSdk روی 34 یا بالاتر و minSdk روی 23 یا بالاتر تنظیم شده است.
شیار
```
android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}
```
کاتلین
```
android {
    compileSdk = 34

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

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

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

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

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

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

کاتلین

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

شیار

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

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

کاتلین

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

شیار

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

در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی 34 تنظیم شده اند.
فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی سیستم کنترل نسخه حذف شده است.
توجه: اگر فایل secrets.properties وجود ندارد، آن را در همان پوشه ای که فایل local.properties وجود دارد ایجاد کنید.
```
PLACES_API_KEY=YOUR_API_KEY
```
فایل را ذخیره کنید.
فایل local.defaults.properties را در پوشه سطح بالای خود، همان پوشه فایل secrets.properties ایجاد کنید و سپس کد زیر را اضافه کنید.
توجه: کد را مطابق شکل وارد کنید. DEFAULT_API_KEY با کلید API خود جایگزین نکنید.
```
PLACES_API_KEY=DEFAULT_API_KEY
```
هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل secrets.properties است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه که secrets.properties حذف می کند و هنوز فایل secrets.properties را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.
فایل را ذخیره کنید.

در Android Studio، فایل 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"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

شیار

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"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

مرحله 4. کلاینت Places API را راه اندازی کنید

Places SDK برای Android را در یک فعالیت یا قطعه راه‌اندازی کنید. ابتدا باید تصمیم بگیرید که از کدام نسخه SDK استفاده کنید: Places SDK برای Android یا Places SDK برای Android (جدید). برای اطلاعات بیشتر در مورد نسخه‌های محصول، به انتخاب نسخه SDK خود مراجعه کنید.

مثال زیر نحوه مقداردهی اولیه SDK را برای هر دو نسخه نشان می دهد.

Places SDK برای Android (جدید)

هنگام فراخوانی Places.initializeWithNewPlacesApiEnabled() کلید API را پاس دهید:

کاتلین

    // 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);

مکان‌های SDK برای Android

هنگام فراخوانی Places.initialize() کلید API را پاس دهید:

کاتلین

    // 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.initialize(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.initialize(getApplicationContext(), apiKey);

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

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

مرحله 5: یک دستگاه Android را راه اندازی کنید

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

برای استفاده از دستگاه Android، دستورالعمل‌های موجود در اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
برای استفاده از شبیه ساز اندروید، می توانید با استفاده از مدیریت دستگاه مجازی اندروید (AVD) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
توجه: اگر می خواهید از شبیه ساز اندروید استفاده کنید، مطمئن شوید که دستگاهی را با نماد Play انتخاب کرده اید، ، در زیر ستون Play Store نمایش داده می شود. این نماد نشان می‌دهد که این نمایه‌ها کاملاً با CTS سازگار هستند و ممکن است از تصاویر سیستمی استفاده کنند که شامل برنامه Play Store می‌شود:

مراحل بعدی

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