إعداد مشروع في "استوديو Android"

لضبط تطبيقك لاستخدام Places SDK for Android، اتّبِع الخطوات التالية. وهي مطلوبة لجميع التطبيقات التي تستخدم حزمة تطوير البرامج Places SDK لنظام التشغيل Android.

الخطوة 1: إعداد "استوديو Android"

يوضّح هذا المستند بيئة تطوير تستخدم استوديو Android Hedgehog والمكوّن الإضافي لنظام Gradle المتوافق مع Android الإصدار 8.2.

الخطوة 2: إعداد حزمة تطوير البرامج (SDK)

تتوفّر مكتبة Places SDK for Android من خلال مستودع Maven من Google. لإضافة حزمة SDK إلى تطبيقك، اتّبِع الخطوات التالية:

  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:5.1.1")
}
  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
    // ...
  }
}

الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بشكل آمن. ننصحك بعدم إدخال مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدارات، بل بتخزينه في الملف secrets.properties الذي يقع في الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف secrets.properties، راجِع ملفات خصائص Gradle.

ولتسهيل هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android وتخزين مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

  1. في "استوديو Android"، افتح ملف build.gradle على مستوى الجذر وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

    Groovy

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

    Kotlin

    buildscript {
    dependencies {
        // ...
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
  2. افتح ملف build.gradle على مستوى التطبيق وأضِف الرمز التالي إلى العنصر plugins.

    Groovy

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

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. إذا كنت تستخدم "استوديو Android"، زامِن مشروعك مع Gradle.
  4. افتح ملف local.properties في دليل مستوى مشروعك، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. 
    PLACES_API_KEY=YOUR_API_KEY

الخطوة 4: إعداد برنامج Places API

لبدء استخدام Places SDK for Android ضمن نشاط أو جزء، مرِّر مفتاح واجهة برمجة التطبيقات عند استدعاء 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.

الخطوة 5: إعداد جهاز Android

لتشغيل تطبيق يستخدم Places SDK for Android، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 5.0 من نظام التشغيل Android أو إصدار أحدث ويتضمّن واجهات Google API.

  • لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
  • لاستخدام Android Emulator، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام أداة إدارة أجهزة Android الافتراضية المضمّنة في "استوديو Android".

الخطوات التالية

بعد إعداد مشروعك، يمكنك استكشاف التطبيقات النموذجية.