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

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

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

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

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

تتوفّر مكتبة "حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل Android" من خلال مستودع Maven من Google. لإضافة حزمة تطوير البرامج (SDK) إلى تطبيقك، اتّبِع الخطوات التالية:

  1. في ملف settings.gradle.kts ذي المستوى الأعلى، أدرِج بوابة المكوّنات الإضافية في Gradle ومستودع Maven من Google ومستودع 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
    // ...
  }
}

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

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

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

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

  1. في استوديو Android، افتح ملف 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 بمفتاح واجهة برمجة التطبيقات الخاص بك. احرص على إضافة secrets.properties إلى ملف .gitignore (أو استبعاده من نظام التحكّم في الإصدارات) حتى لا يتم إدراج مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدارات. 
    PLACES_API_KEY=YOUR_API_KEY

  5. أنشئ ملف local.defaults.properties في الدليل ذي المستوى الأعلى، وهو المجلد نفسه الذي يحتوي على ملف secrets.properties، ثم أضِف الرمز التالي.

    PLACES_API_KEY=DEFAULT_API_KEY

    الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على الملف secrets.properties، وذلك لتجنُّب تعذُّر إنشاء التطبيقات. قد يحدث ذلك إذا استنسخت التطبيق من نظام للتحكّم في الإصدارات يحذف secrets.properties ولم تنشئ بعد ملف secrets.properties محليًا لتوفير مفتاح واجهة برمجة التطبيقات.

  6. في استوديو Android، افتح ملف 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"
}

الخطوة 4: إعداد عميل Places API

لإعداد حزمة تطوير البرامج (SDK) للأماكن على 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);

أنت الآن جاهز لبدء استخدام حزمة تطوير البرامج بالاستناد إلى الأماكن لنظام التشغيل Android.

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

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

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

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

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