تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

في ملف settings.gradle ذي المستوى الأعلى، ضمِّن بوابة المكوّنات الإضافية في Gradle، مستودع Google Maven ومستودع Maven المركزي ضمن جزء pluginManagement. جزء pluginManagement قبل أي عبارات أخرى في النص البرمجي.
```
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
} 
```
في ملف settings.gradle ذي المستوى الأعلى، ضمِّن مستودع Maven من Google ومستودع Maven المركزي ضمن مجموعة dependencyResolutionManagement:
```
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
} 
```
في dependencies في ملف build.gradle على مستوى الوحدة، أضِف تبعية. إلى حزمة تطوير برامج الأماكن لأجهزة Android:

ملاحظة: حزمة تطوير برامج الأماكن لإصدار Android يتطلب الإصدار 3.5.0 kotlin-bom 1.8.0 أو إصدارًا أحدث. بالنسبة لمزيد من المعلومات حول تبعية kotlin-bom، يمكنك مراجعة استخدام أحدث إصدار من kotlin-stdlib في التبعيات المتعدِّدة:
Groovy
```
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'
}
```
Kotlin
```
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 على 21 أو أعلى.
Groovy
```
android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}
```
Kotlin
```
android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}
```
في القسم buildFeatures من ملف build.gradle على مستوى الوحدة، أضِف الفئة BuildConfig التي تستخدمها للوصول إلى قيم البيانات الوصفية المحدّدة لاحقًا. في هذا الإجراء:
Groovy
```
android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
```
Kotlin
```
android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}
```

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

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

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

لتثبيت مكوّن Secrets Gradle الإضافي لنظام التشغيل Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:

في "استوديو Android"، افتح build.gradle أو build.gradle.kts المستوى الأعلى. وإضافة التعليمة البرمجية التالية إلى العنصر 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")
    }
}

افتح ملف build.gradle على مستوى الوحدة وأضِف الرمز التالي إلى العنصر plugins

Groovy

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

Kotlin

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

وفي ملف build.gradle على مستوى الوحدة، تأكد من أن targetSdk تَمَّ ضَبْطُ compileSdk عَلَى 34.
احفظ الملف، مزامنة مشروعك مع Gradle
افتح ملف secrets.properties في دليل المستوى الأعلى، ثم أضِف الملف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك. تخزين مفتاحك في هذا الملف لأنّه تم استبعاد secrets.properties من التحقق من عنصر تحكّم الإصدار .
ملاحظة: إذا لم يكن ملف secrets.properties: عليك إنشاؤها، وعليك إنشاؤها في المجلد نفسه الذي يتضمّن ملف local.properties.
```
PLACES_API_KEY=YOUR_API_KEY
```
احفظ الملف.
أنشئ الملف local.defaults.properties في دليل المستوى الأعلى، بالطريقة نفسها كملف secrets.properties، ثم أضف الرمز التالي.

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

في "استوديو Android"، افتح build.gradle على مستوى الوحدة أو build.gradle.kts وعدِّل السمة secrets. إذا كانت لم يتم العثور على سمة واحدة (secrets). يُرجى إضافتها.

عدِّل خصائص المكوِّن الإضافي لضبط propertiesFileName على secrets.properties، ضبط 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 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.*"
}

Kotlin

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

تهيئة حزمة تطوير برامج الأماكن لأجهزة Android داخل نشاط أو جزء. يجب أولاً تحديد إصدار حزمة تطوير البرامج (SDK) المطلوب استخدامه: حزمة Places SDK لنظام التشغيل Android حزمة تطوير برامج الأماكن لأجهزة Android (جديد). لمزيد من المعلومات حول إصدارات المنتجات، يُرجى الاطّلاع على مقالة اختيار إصدار حزمة SDK.

يوضّح المثال التالي كيفية إعداد حزمة 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)

Java

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

تمرير مفتاح واجهة برمجة التطبيقات عند الاتصال Places.initialize():

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.initialize(applicationContext, apiKey)

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

Java

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

أنت الآن جاهز لبدء استخدام حزمة تطوير برامج الأماكن لأجهزة Android!

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

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

لاستخدام جهاز Android، يُرجى اتّباع التعليمات الواردة في تشغيل التطبيقات على جهاز
لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال أداة إدارة الأجهزة الافتراضية التي تعمل بنظام التشغيل Android (AVD) المتوفّرة ضمن "استوديو Android"
ملاحظة: إذا اخترت استخدام محاكي Android، تأكَّد من يمكنك اختيار جهاز يعرض رمز Play، ، ويظهر ضمن العمود متجر Play. يشير هذا الرمز إلى أن هذه الملفات الشخصية عبارة عن CTS بالكامل. متوافق ويجوز له استخدام صور النظام التي تتضمّن تطبيق "متجر Play":

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

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