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

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

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

الخطوة 1: إعداد Android Studio

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

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

تتوفّر مكتبة حزمة تطوير البرامج (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.kts على مستوى الوحدة، أضِف ملفًا تابعًا إلى حزمة تطوير برامج "الأماكن" لنظام التشغيل Android:

ملاحظة: يتطلب الإصدار 3.5.0 من حزمة تطوير برامج "الأماكن" لأجهزة Android kotlin-bom 1.8.0 أو إصدار أحدث. للحصول على المزيد من المعلومات عن التبعية kotlin-bom، اطّلِع على استخدام أحدث إصدار من kotlin-stdlib في التبعيات الانتقالية.
رائع
```
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:4.1.0")
}
```

في ملف build.gradle.kts على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية:

ملاحظة: تأكَّد من ضبط compileSdk ليكون 34 أو أعلى وminSdk ليكون 23 أو أعلى.

رائع

android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}

Kotlin

android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}

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

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

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

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

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

في Android Studio، افتح ملف build.gradle.kts أو build.gradle الأولي وأضِف الرمز البرمجي التالي إلى عنصر dependencies ضمن buildscript.

Kotlin

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.

Kotlin

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 في الدليل من المستوى الأعلى، ثم أضِف الرمز التالي: استبدِل 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 Studio، افتح ملف 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 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"
}

رائع

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"
}

الخطوة 4. إعداد برنامج واجهة برمجة التطبيقات Places API

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

أنت الآن جاهز لبدء استخدام حزمة تطوير البرامج (SDK) لميزة "الأماكن" على أجهزة Android.

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

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

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

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

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