الإعداد

توضّح هذه الصفحة الإجراءات التي يجب اتّخاذها للبدء في إنشاء التطبيقات باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android. تتضمّن عملية الإعداد ضبط مشروع Google Cloud وواجهة برمجة التطبيقات لاستخدامهما مع حزمة تطوير البرامج (SDK)، ثم إعداد مشروع IDE في Android Studio. أكمِل هذه الخطوات قبل إضافة أول خريطة ثلاثية الأبعاد إلى تطبيقك.

إعداد مشروع على Google Cloud ومفتاح واجهة برمجة التطبيقات

قبل أن تتمكّن من بدء الإنشاء باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android، عليك إعداد مشروع على Google Cloud ومفتاح واجهة برمجة التطبيقات لاستخدامهما مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android من خلال completing the following steps:

الخطوة 1

وحدة التحكّم

  1. في Google Cloud Console، في صفحة أداة اختيار المشاريع، انقر على إنشاء مشروع لبدء إنشاء مشروع جديد في Cloud.

    الانتقال إلى صفحة اختيار المشروع

  2. تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تأكَّد من تفعيل الفوترة لمشروعك.

    تقدّم Google Cloud فترة تجريبية بدون أي رسوم. تنتهي الفترة التجريبية بعد 90 يومًا أو بعد تحصيل رسوم بقيمة 300 دولار أمريكي من الحساب، أيهما أقرب. يمكنك الإلغاء في أي وقت. لمزيد من المعلومات، يُرجى الاطّلاع على أرصدة حسابات الفوترة والفوترة.

SDK للسحاب

gcloud projects create "PROJECT"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت حزمة Cloud SDK والأوامر التالية:

الخطوة 2

لاستخدام Google Maps Platform، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تخطّط لاستخدامها مع مشروعك.

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

لتفعيل واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) واحدة أو أكثر:

وحدة التحكّم

  1. اطّلِع على واجهات برمجة التطبيقات وحِزم تطوير البرامج (SDK) لمنصّة "خرائط Google" التي يمكنك تفعيلها من خلال الانتقال إلى صفحة مكتبة واجهة برمجة التطبيقات للخرائط في وحدة تحكّم Cloud:

    انتقِل إلى صفحة مكتبة Maps API.

  2. انقر على واجهة برمجة التطبيقات أو حزمة SDK التي تريد تفعيلها.
    • إذا كان الزر يظهر عليه تفعيل، انقر عليه لتفعيل واجهة برمجة التطبيقات أو حِزم تطوير البرامج (SDK).
    • إذا كان الزر يظهر عليه النص إدارة، يعني ذلك أنّ واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) مفعّلة، وبالتالي ليس عليك اتّخاذ أي إجراء آخر.
    • سيؤدي النقر على أي من الزرَّين إلى عرض لوحة بيانات واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK). (انقر على الزر إيقاف لإزالة واجهة برمجة التطبيقات أو حِزم تطوير البرامج (SDK) من هذا المشروع).

SDK للسحاب

يُفعِّل الأمر التالي جميع واجهات برمجة التطبيقات في "خرائط Google" و"الطرق" و"الأماكن":

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت حزمة Cloud SDK والأوامر التالية:

استخدِم هذا الأمر لتفعيل واجهات برمجة تطبيقات Environment API:

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com"

الخطوة 3

لا تؤدي هذه الخطوة إلا إلى تنفيذ عملية إنشاء مفتاح واجهة برمجة التطبيقات. إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات في مرحلة الإنتاج، ننصحك بشدة بتقييد مفتاح واجهة برمجة التطبيقات. يمكنك العثور على مزيد من المعلومات في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.

مفتاح واجهة برمجة التطبيقات هو معرّف فريد يُستخدم لمصادقة الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.

لإنشاء مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

وحدة التحكّم

  1. انتقِل إلى صفحة منصة خرائط Google > بيانات الاعتماد.

    الانتقال إلى صفحة "بيانات الاعتماد"

  2. في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
    يعرض مربّع الحوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا.
  3. انقر على إغلاق.
    يظهر مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
    (تذكَّر فرض قيود على مفتاح واجهة برمجة التطبيقات قبل استخدامه في مرحلة الإنتاج).

SDK للسحاب

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت حزمة Cloud SDK والأوامر التالية:

لتفعيل حزمة SDK، يُرجى الاطّلاع على صفحة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android في وحدة تحكّم Google Cloud. لمزيد من المعلومات حول إكمال هذه الخطوات، يُرجى الاطّلاع على البدء في استخدام "منصة خرائط Google".

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

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

الجزء 1: إعداد المشروع وإعدادات Gradle

  1. أنشئ مشروعًا جديدًا في "استوديو Android" باستخدام نموذج نشاط المشاهدات الفارغة.

  2. إذا كنت تستخدم Git للتحكم في المصدر، عدِّل .gitignoreملف المشروع لمنع التزامن مع نظام التحكم في الإصدارات لملف الأسرار:

    • في الدليل الجذر لمشروعك، افتح الملف .gitignore.
    • أضِف السطر التالي:
    secrets.properties

  3. عدِّل ملف build.gradle.kts على مستوى المشروع:

    • في الدليل الجذر لمشروعك، افتح الملف build.gradle.kts.
    • في مجموعة plugins، أضِف المكوّن الإضافي Secrets Gradle:
    plugins {
  alias(libs.plugins.android.application) apply false
  alias(libs.plugins.kotlin.android) apply false
  alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
}

  4. تعديل ملف gradle/libs.versions.toml: - افتح ملف gradle/libs.versions.toml الذي يقع عادةً في الدليل gradle ضمن الدليل الجذر للمشروع. - في قسم "الإصدارات"، أضِف إصدارات حزمة SDK ومكوّن Gradle الإضافي لـ "أسرار Google":

    maps3dSdk = "0.0.1" # Update this value to match the SDK version to include
secretsGradlePlugin = "2.0.1"

    -   In the library section, add the SDK library:

    play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }

    -   In the plugin section, add the Secrets Gradle plugin:

    secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }

  5. تعديل ملف app/build.gradle.kts على مستوى الوحدة: - افتح ملف build.gradle.kts على مستوى الوحدة، والذي يقع عادةً ضمن الدليل app. - في أعلى الملف، أضِف المكوّن الإضافي Secrets Gradle إلى العنصر plugins:

    plugins {
  alias(libs.plugins.android.application)
  alias(libs.plugins.kotlin.android)
  alias(libs.plugins.secrets.gradle.plugin) // Add this line
}

    -   In the `dependencies` block, add the SDK:

    dependencies {
  // ... other dependencies
  implementation(libs.play.services.maps3d) // Add this line
}

    -   At the end of the file, outside of the `android` and `dependencies`
    blocks, add the secrets configuration:

    secrets {
  // Optionally specify a different filename 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"
}

الجزء 2: إضافة مفتاح واجهة برمجة التطبيقات إلى مشروعك

  1. أنشئ ملف secrets.properties:

    • في الدليل الجذر لوحدة التطبيق (عادةً الدليل app)، أنشئ ملفًا جديدًا باسم secrets.properties.
    • أضِف مفتاح واجهة برمجة التطبيقات إلى الملف:
    MAPS3D_API_KEY=YOUR_API_KEY_HERE
``` Note: Make sure you
    replace `YOUR_API_KEY_HERE` with the API key that you configured for use
with the Maps 3D SDK for Android.

  2. أنشئ ملف local.defaults.properties: - في الدليل الجذر لوحدة التطبيق، أنشئ ملفًا جديدًا باسم secrets.properties. - أضِف مفتاح واجهة برمجة تطبيقات تلقائيًا أو نائبًا إلى الملف. يمكن التحقّق من هذا الملف في نظام التحكّم بالإصدارات:

    MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER

الجزء 3: تعديل ملف AndroidManifest.xml

  1. افتح ملف app/src/main/AndroidManifest.xml.

  2. داخل علامة <application>، قبل علامة <activity>، أضِف العنصر<meta-data> التالي للإشارة إلى مفتاح واجهة برمجة التطبيقات:

    <application
  ...>

  <meta-data
      android:name="com.google.android.geo.maps3d.API_KEY"
      android:value="${MAPS3D_API_KEY}" />

  <activity
      ...>
  </activity>
</application>

    أثناء عملية التصميم، سيستبدِل المكوّن الإضافي Gradle لميزة "أسرار Google" العنصر النائب ${MAPS3D_API_KEY} بالمفتاح من ملفsecrets.properties.

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

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