الإعداد

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

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

قبل البدء في إنشاء تطبيقات باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android، يجب إعداد مشروع على السحابة الإلكترونية ومفتاح واجهة برمجة تطبيقات لاستخدامهما مع حزمة تطوير البرامج (SDK) من خلال إكمال الخطوات التالية:

الخطوة 1

وحدة التحكّم

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

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

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

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

SDK للسحاب

gcloud projects create "PROJECT"

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

الخطوة 2

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

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

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

وحدة التحكّم

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

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

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

SDK للسحاب

يؤدي الأمر التالي إلى تفعيل جميع واجهات برمجة التطبيقات Maps وRoutes وPlaces:

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 APIs:

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.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 Console. لمزيد من المعلومات حول إكمال هذه الخطوات، يُرجى الاطّلاع على مقالة البدء في استخدام "منصة خرائط 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 ضمن دليل جذر المشروع.
    • في قسم [versions]، أضِف أرقام إصدارات حزمة تطوير البرامج (SDK) والمكوّن الإضافي Secrets Gradle:
    # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
maps3dSdk = "0.2.0"
# See https://github.com/google/secrets-gradle-plugin/releases for available releases
secretsGradlePlugin = "2.0.1"
    • في قسم [library]، أضِف مكتبة حزمة تطوير البرامج (SDK):
    play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
    • في قسم [plugins]، أضِف المكوّن الإضافي Secrets Gradle:
    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
}
    • في حزمة dependencies، أضِف حزمة تطوير البرامج (SDK):
    dependencies {
    // ... other dependencies
    implementation(libs.play.services.maps3d) // Add this line
}
    • في نهاية الملف، خارج حزمتَي android وdependencies، أضِف إعدادات الأسرار:
    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

  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>

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

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

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