مرجع سريع حول حزمة تطوير البرامج (SDK) للأماكن على Android

تتيح حزمة تطوير البرامج (SDK) للأماكن في Android لتطبيقات Android الوصول إلى قاعدة بيانات Google التي تتضمّن معلومات عن الأماكن والأنشطة التجارية من خلال ميزات "الإكمال التلقائي للأماكن" و"تفاصيل المكان" و"بحث في الجوار" و"البحث النصي" و"صور المكان". ‫Places SDK for Android (New) هو الإصدار الحالي ويعتمد على Places API (New).

حزمة تطوير برامج الأماكن لأجهزة Android: معلومات أساسية

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

استخدِم حزمة تطوير البرامج (SDK) للأماكن على Android في الحالات التالية:

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

لا تستخدِم حزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لتطبيقات Android في الحالات التالية:

حزمة تطوير برامج الأماكن لأجهزة Android: الإعداد

حِزم Places SDK for Android الرسمية:

  • maven: com.google.android.libraries.places:places

حزمة تطوير برامج الأماكن لأجهزة Android: الأخطاء الشائعة

  • المشكلة: تظهر رسالة خطأ عند إرسال طلبات "بحث في الجوار" بدون قائمة حقول (قناع حقل) أو بقائمة فارغة. الحلّ: يجب تمرير Place.Field واحد على الأقل في قائمة حقول SearchNearbyRequest. يُرجى الاطّلاع على /maps/documentation/places/android-sdk/nearby-search.
  • المشكلة: يتعذّر استخدام ميزات "تفاصيل المكان (جديدة)" و"بحث في الجوار (جديد)" و"الإكمال التلقائي (جديد)" عندما لا يتضمّن مفتاح واجهة برمجة التطبيقات Places API (جديدة)، أو في الإصدار 5.x من حزمة تطوير البرامج (SDK) والإصدارات الأقدم عندما يطلب التطبيق Places.initialize(). تمت إزالة Places.initialize() في الإصدار 6.0.2، لذا لن يتم تجميع الرمز الذي يستدعيه بعد الترقية. الحلّ: فعِّل Places API (الجديدة)، وأضِفها إلى واجهات برمجة التطبيقات المسموح بها لمفتاح واجهة برمجة التطبيقات، وابدأها باستخدام Places.initializeWithNewPlacesApiEnabled(). يُرجى الاطّلاع على /maps/documentation/places/android-sdk/legacy/migrate-overview.
  • المشكلة: لا يتضمّن Place الذي يعرضه fetchPlace() أي PhotoMetadata (لذلك لا يوجد شيء يمكن حلّه) عندما تحذف قائمة الحقول PHOTO_METADATAS. الحلّ: يجب تضمين Place.Field.PHOTO_METADATAS في قائمة الحقول. بما أنّ fetchResolvedPhotoUri() متوقّف نهائيًا، استخدِم مكوّن "تفاصيل المكان" في حزمة أدوات "خرائط Google" الجاهزة للأماكن لعرض الصور. يُرجى الاطّلاع على /maps/documentation/places/android-sdk/place-photos.
  • المشكلة: التطبيقات التي تعرض تفاصيل الأماكن أو الصور أو المراجعات بدون الإشارة إلى الجهات الخارجية والمؤلفين تنتهك السياسات. الحلّ: اعرض معلومات تحديد المصدر التي تم عرضها مع عناصر Place وPhotoMetadata وReview. يُرجى الاطّلاع على /maps/documentation/places/android-sdk/policies.

حزمة تطوير البرامج (SDK) للأماكن على Android: الميزات القديمة والمتوقّفة نهائيًا

  • ميزات Places SDK for Android (الإصدار القديم) / Places API (الإصدار القديم) (الإكمال التلقائي، المكان الحالي، تفاصيل المكان، صور المكان القديمة): الإصدار القديم منذ 1 مارس 2025. البديل: ميزات Places SDK for Android (الجديدة) المستندة إلى Places API (الجديدة)، والتي يتم إعدادها باستخدام Places.initializeWithNewPlacesApiEnabled(). المشكلة: اعتبارًا من أكتوبر 2026، لن تتمكّن المشاريع الجديدة على السحابة الإلكترونية من تفعيل Places API (الإصدار القديم) (ستبقى المشاريع الحالية متاحة). أزالت حزمة SDK 6.0.2 الطرق القديمة التي تتوفّر فقط في الإصدار 5.x والإصدارات الأقدم. يُرجى الاطّلاع على دليل نقل البيانات.
  • Places.initialize(): تم إيقافها نهائيًا اعتبارًا من ‎30/09/2026. الاستبدال: Places.initializeWithNewPlacesApiEnabled(). المؤشر: تمت إزالة الطريقة من حزمة SDK في الإصدار 6.0.2، ولم يعُد الرمز الذي يستدعيها قابلاً للتجميع. يُرجى الاطّلاع على دليل نقل البيانات.
  • ‫PlacesClient.findCurrentPlace() وawaitFindCurrentPlace() (Current Place، الإصدار القديم): تم إيقافها نهائيًا اعتبارًا من ‎30/09/2026. البديل: PlacesClient.searchNearby() (بحث في الجوار (جديد)). المشكلة: تمت إزالة الطرق وفئات FindCurrentPlaceRequest/FindCurrentPlaceResponse في الإصدار 6.0.2. يُرجى الاطّلاع على دليل نقل البيانات.
  • ‫PlacesClient.fetchPhoto() وawaitFetchPhoto(): تم إيقافها نهائيًا منذ ‎30/09/2026. البديل: مكوّن "تفاصيل المكان" في حزمة أدوات "خرائط Google" الجاهزة للأماكن (تم إيقاف PlacesClient.fetchResolvedPhotoUri() نهائيًا). المشكلة: تمت إزالة الطرق وفئات FetchPhotoRequest/FetchPhotoResponse في الإصدار 6.0.2. يُرجى الاطّلاع على دليل نقل البيانات.
  • أداة الإكمال التلقائي في Places API (الإصدار القديم) (Autocomplete وAutocompleteSupportFragment وAutocompleteActivityMode): تم إيقافها نهائيًا اعتبارًا من ‎30/09/2026. البديل: التطبيق المصغّر الإكمال التلقائي للأماكن (جديد) (PlaceAutocomplete) أو PlacesClient.findAutocompletePredictions(). المشكلة: تمت إزالة الفئات من حزمة SDK في الإصدار 6.0.2. يُرجى الاطّلاع على دليل نقل البيانات.
  • مكتبة التوافق مع Places API‏ (com.google.android.libraries.places:places-compat): تم إيقافها نهائيًا منذ 31 مارس 2022. البديل: حزمة تطوير البرامج بالاستناد إلى "الأماكن" لنظام التشغيل Android (com.google.android.libraries.places:places). المؤشر: تم إيقاف الإصدار 2.6.0، ولن يتم توفير ميزات جديدة أو إصلاحات للأخطاء.
  • فئة AutocompleteFragment: تم إيقافها نهائيًا منذ ‎25/09/2025. البديل: تطبيق الإكمال التلقائي للأماكن (جديد) المصغّر (PlaceAutocomplete). المشكلة: تمت إزالة الصنف من حزمة تطوير البرامج (SDK) في الإصدار 5.0.0 (تمت أيضًا إزالة AutocompleteSupportFragment في الإصدار 6.0.2).

الإجراءات التي يمكنك تنفيذها باستخدام "حزمة تطوير برامج الأماكن لأجهزة Android"

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

حزمة تطوير البرامج (SDK) للأماكن على Android: الذكاء الاصطناعي التوليدي

حزمة تطوير برامج الأماكن لأجهزة Android: الأماكن

حزمة تطوير برامج الأماكن لأجهزة Android: حزمة أدوات واجهة المستخدم للأماكن

  • تطبيق نمط CSS على عنصر في واجهة المستخدم لبيانات الأماكن ملاحظة: تنطبق الخصائص المخصّصة في CSS على عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن في Maps JavaScript API. أمّا حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل Android وحزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل iOS، فتصمّمان طرق عرض حزمة أدوات "خرائط Google" الجاهزة للأماكن آليًا باستخدام سمات المظهر والنمط. متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • تخصيص تصميم وإعدادات عناصر واجهة المستخدم لبيانات الأماكن باستخدام أداة تخصيص عناصر واجهة المستخدم: ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • أضِف عنصرًا في واجهة المستخدم يعرض معلومات عن مكان معيّن على صفحة ويب أو تطبيق للأجهزة الجوّالة. ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • أضِف عنصرًا في واجهة المستخدم يعرض قائمة بالأماكن استنادًا إلى سلسلة طلب بحث إلى صفحة ويب. ملاحظة: تتوفّر هذه الميزة على كلّ من صفحات الويب (Maps JavaScript API) والتطبيقات على الأجهزة الجوّالة (Places SDK for Android وPlaces SDK for iOS). متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • أضِف عنصرًا في واجهة المستخدم يعرض قائمة بالأماكن القريبة من موقع جغرافي معيّن إلى صفحة ويب. ملاحظة: تتوفّر هذه الميزة على كلّ من صفحات الويب (Maps JavaScript API) والتطبيقات على الأجهزة الجوّالة (Places SDK for Android وPlaces SDK for iOS). متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • يمكنك إضافة عنصر أساسي في واجهة المستخدم للإكمال التلقائي إلى صفحة ويب أو تطبيق يعرض معرّفات الأماكن على Google استنادًا إلى سلسلة طلب بحث. ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq