حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات السريعة على Android

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

إنّ دليل البدء السريع هذا موجَّه إلى المطوّرين الذين لديهم دراية بتطوير Android الأساسي باستخدام لغة Java أو Kotlin.

إعداد بيئة التطوير

  1. يجب توفّر الإصدار Android Studio Arctic Fox أو إصدار أحدث. ننصحك بتنزيله وتثبيته إذا لم يسبق لك تنزيله.
  2. تأكَّد من استخدام الإصدار 7.0 أو الإصدارات الأحدث من مكوّن Gradle الإضافي لنظام التشغيل Android في "استوديو Android".

إعداد جهاز Android

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

إنشاء مشروع على "خرائط Google" في "استوديو Android"

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

  1. افتح "استوديو Android" وانقر على إنشاء مشروع جديد في نافذة مرحبًا بك في استوديو Android.

  2. في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، اختَر نشاط فارغ، ثم انقر على التالي.

  3. املأ نموذج نشاط "خرائط Google":

    • اضبط اللغة على Java أو Kotlin. يتم دعم كلتا اللغتين بالكامل من خلال حزمة SDK للخرائط لنظام Android. للاطّلاع على مزيد من المعلومات حول لغة Kotlin، يُرجى الاطّلاع على مقالة تطوير تطبيقات Android باستخدام لغة Kotlin.

    • اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة SDK متوافق مع جهاز الاختبار. يجب اختيار إصدار أعلى من الحدّ الأدنى المطلوب للإصدار 18.0.x من حزمة "SDK للخرائط" لنظام التشغيل Android، وهو المستوى 19 لواجهة برمجة تطبيقات Android (Android 4.4 أو KitKat) أو الإصدارات الأحدث. راجع ملاحظات الإصدار للحصول على أحدث المعلومات حول متطلبات إصدار SDK.

  4. انقر على إنهاء.

    يشغّل "استوديو Android" مشروع Gradle ويُنشئ المشروع. وقد تستغرق هذه العملية بعض الوقت.

  5. عند انتهاء الإصدار، سيفتح "استوديو Android" ملفَّي AndroidManifest.xml وMapsActivity. قد يكون لنشاطك اسم مختلف، ولكنّه هو الاسم الذي ضبطته أثناء الإعداد.

  6. أضف نشاط المشاهَدات في "خرائط Google":

    1. انقر بزر الماوس الأيمن على الحزمة التي تريد إضافة نشاط طرق عرض خرائط Google إليها.
    2. حدد جديد > Google > نشاط بانوراميات في خرائط Google.

    إضافة نشاط خرائط.

    لمزيد من المعلومات، اطّلِع على مقالة إضافة رمز من نموذج.

  7. يحتوي الملف AndroidManifest.xml على إرشادات حول الحصول على مفتاح واجهة برمجة التطبيقات لخرائط Google ثم إضافته إلى ملف local.properties. لا تضِف مفتاح واجهة برمجة التطبيقات إلى ملف AndroidManifest.xml. يؤدي هذا الإجراء إلى تخزين مفتاح واجهة برمجة التطبيقات بشكل أقل أمانًا. بدلاً من ذلك، اتّبِع التعليمات الواردة في الأقسام التالية لإنشاء مشروع على السحابة الإلكترونية وضبط مفتاح واجهة برمجة التطبيقات.

إعداد مشروعك على Google Cloud

أكمِل خطوات إعداد Cloud Console المطلوبة بالنقر على علامات التبويب التالية:

الخطوة 1

وحدة التحكم

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

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

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

الخطوة 2

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

وحدة التحكم

تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

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

الخطوة 3

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

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

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

وحدة التحكم

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

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

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

Cloud SDK

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

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

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

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

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

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

  1. في "استوديو Android"، افتح ملف build.gradle على مستوى المشروع وأضِف الرمز التالي إلى العنصر 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")
        }
    }
    
  2. Open your module-level build.gradle file and add the following code to the plugins element.

    Groovy

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. Save the file and sync your project with Gradle.
  4. Open the secrets.properties in your project level directory, and then add the following code. Replace YOUR_API_KEY with your API key.
    MAPS_API_KEY=YOUR_API_KEY