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

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

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

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

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

الخطوة 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:

ملاحظة: تتطلب حزمة "SDK للأماكن" لنظام التشغيل Android الإصدار 3.5.0 الإصدار 3.5.0 من kotlin-bom أو إصدار أحدث. لمزيد من المعلومات حول اعتمادية 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'
}
```
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 أو أعلى.
رائع
```
android {
    compileSdk 34

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

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

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

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

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

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

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

رائع

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.

رائع

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، وضبط أي سمات أخرى.

رائع

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 الذي تريد استخدامه: حزمة تطوير برامج الأماكن لأجهزة 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

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

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

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

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