يتوافق الإصدار 3.4.0 من حزمة تطوير برامج الأماكن لنظام التشغيل Android مع إصدارين من حزمة تطوير البرامج (SDK) وهما: حزمة SDK الخاصة بالأماكن لنظام التشغيل Android هي حزمة تطوير البرامج الحالية وحزمة SDK الخاصة بالأماكن لنظام التشغيل Android (جديدة) هي إصدار الجيل التالي من حزمة تطوير البرامج (SDK).
مع إطلاق الإصدار 3.4.0 من حزمة تطوير برامج الأماكن لنظام التشغيل Android، تتمثل مهمتك الأولى في تحديد حزمة تطوير البرامج التي تريد استخدامها. هذا صحيح إذا كنت عميلاً جديدًا أو عميلاً حاليًا يستخدم حزمة SDK. يمكنك استخدام هذا الدليل لفهم الاختلافات الرئيسية بين حزمتَي تطوير البرامج (SDK).
كيفية اختيار إصدار حزمة تطوير البرامج (SDK)
في الخلفية، تعتمد حزمة تطوير برامج الأماكن لأجهزة Android على خدمة Places API، إما خدمة Places API (جديدة) أو Places API. قبل أن تتمكن من استخدام حزمة تطوير برامج الأماكن لأجهزة Android، يجب تفعيل خدمة واجهة برمجة تطبيقات الأماكن في مشروعك على Google Cloud.
بالنسبة إلى نظام التشغيل Android، هناك إجراءان يمكنك اتخاذهما لتحديد واجهات برمجة التطبيقات التي يمكنك استخدامها في تطبيقك:
في مشروعك، يجب تفعيل واجهة Places API (جديدة) أو Places API، أو كليهما على مفتاح واجهة برمجة التطبيقات الخاص بك بناءً على ما تنوي استخدامه في تطبيقك.
يمكنك إعداد تطبيقك عن طريق استدعاء إما طريقة
Places.initializeWithNewPlacesApiEnabled()
أوPlaces.initialize()
.
اختيار حزمة تطوير البرامج (SDK)
يتحكم إصدار خدمة Places API الذي تفعِّله في إصدار حزمة تطوير البرامج (SDK) الذي يستخدمه تطبيقك:
كلا النوعين: يتيح تفعيل جميع الميزات لكل من حزمة SDK للأماكن لنظام التشغيل Android وحزمة SDK للأماكن لنظام التشغيل Android (جديد). استخدِم الطريقتَين
Places.initializeWithNewPlacesApiEnabled()
وPlaces.initialize()
للتحكّم في الميزات المتاحة.Places API: لتفعيل حزمة تطوير البرامج (SDK) الحالية لميزة "الأماكن" في نظام التشغيل Android لا يمكنك الوصول إلى الميزات الجديدة التي تمت إضافتها في حزمة "SDK للأماكن" لنظام التشغيل Android الإصدار 3.4.0.
واجهة برمجة تطبيقات الأماكن (جديدة): تفعِّل حزمة تطوير البرامج للأماكن (SDK) في الأماكن لنظام التشغيل Android (الجديدة) وجميع الميزات الجديدة الموضحة في الميزات الرئيسية التي تمت إضافتها إلى حزمة SDK للأماكن لنظام التشغيل Android (الجديدة)، ولكنها لا تفعِّل الميزات الحالية مثل "المكان الحالي" و"الإكمال التلقائي للأماكن".
للمزيد من المعلومات حول اختيار خدمة Places API، يُرجى الاطّلاع على المقالة إعداد مشروعك على Google Cloud.
تهيئة تطبيقك
عند إعداد تطبيقك، يجب طلب إما طريقة
Places.initializeWithNewPlacesApiEnabled()
أو طريقة Places.initialize()
.
يوضح الجدول التالي تأثيرات تمكين كل حزمة SDK واستدعاء كل طريقة إعداد. على سبيل المثال، إذا فعّلت حزمة تطوير البرامج للأماكن (جديدة) واستدعيت Places.initializeWithNewPlacesApiEnabled()
، يمكنك استخدام جميع واجهات برمجة التطبيقات الجديدة وجميع واجهات برمجة التطبيقات الحالية.
إذا فعّلت حزمة تطوير البرامج للأماكن (جديد) واستدعت Places.initialize()
، لا يمكنك استخدام الميزات الجديدة لـ "تفاصيل المكان" و"صور المكان"، ولكن يمكنك استدعاء ميزة "البحث النصي" الجديدة. إذا لم تمكن واجهة برمجة تطبيقات الأماكن، فلا يمكنك الوصول إلى الإصدار القديم من تفاصيل المكان ولكن لا يزال بإمكانك استدعاء البحث النصي الجديد.
الإصدار | واجهات برمجة التطبيقات | تم تفعيل حزمة تطوير البرامج (SDK) على مفتاح واجهة برمجة التطبيقات | طريقة الإعداد | ||
---|---|---|---|---|---|
واجهة برمجة تطبيقات الأماكن | Places API (جديدة) | initialize() |
initializeWithNewPlacesApiEnabled() |
||
v3.3.0 | تفاصيل الأماكن | ||||
تفاصيل الأماكن (جديد) | |||||
البيانات الوصفية للصور (جديدة) | |||||
البحث النصي (جديد) | أي من الطريقتين | ||||
v3.4.0 | صورة Uri (جديد) | ||||
صورة نقطية | أي من الطريقتين | ||||
CurrentPlace | أي من الطريقتين | ||||
الإكمال التلقائي | أي من الطريقتين |
ما هي حزمة تطوير البرامج (SDK) التي تختارها؟
للمساعدة في تحديد الإصدار الذي يجب اختياره:
إذا كنت عميلاً جديدًا، بدأت للتو في استخدام حزمة تطوير البرامج للأماكن (SDK) لنظام التشغيل Android، ثم ابدأ بـ واجهة برمجة تطبيقات الأماكن (جديدة) وحزمة تطوير البرامج (SDK) الجديدة.
إذا كنت من مطوري Kotlin، يمكنك استخدام إحدى حزمتي SDK، لكن الميزات الجديدة في Places SDK for Android (جديد) لا تتوفر إلا في Java الإصدار 3.4.0.
إذا كنت عميلاً حاليًا وكنت تستخدم الرموز المميّزة للجلسة، يمكنك مواصلة استخدام حزمة تطوير البرامج (SDK) الحالية. لا تتوافق حزمة تطوير برامج الأماكن لنظام التشغيل Android (الجديدة) في الوقت الحالي مع الرموز المميزة للجلسة.
إذا كنت عميلاً حاليًا، يمكنك مواصلة استخدام حزمة تطوير البرامج (SDK) الحالية. ومع ذلك، للاستفادة من تحسينات الأداء وتحسينات ميزات حزمة تطوير البرامج للأماكن المخصّصة لنظام التشغيل Android (جديد)، يمكنك استخدام حزمة تطوير البرامج (SDK) الجديدة.
وليس عليك نقل البيانات عند الانتقال إلى حزمة تطوير البرامج (SDK) الجديدة. عليك فقط إجراء ما يلي:
- فعِّل Places API (جديدة) على مفتاح واجهة برمجة التطبيقات المستخدَم في تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على استخدام مفاتيح واجهة برمجة التطبيقات.
في القسم
dependencies
من ملفbuild.gradle
على مستوى الوحدة، عدِّل تبعيةplaces
وأضِف التبعيةkotlin-bom
:dependencies { implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0")) implementation 'com.google.android.libraries.places:places:3.3.0' }
لمزيد من المعلومات حول تبعية
kotlin-bom
، راجِع استخدام أحدث إصدار من kotlin-stdlib في التبعيات المتعدّدة.- عليك تحديث تطبيقك الحالي لطلب طريقة
Places.initializeWithNewPlacesApiEnabled()
الجديدة لإعداد تطبيقك. لمزيد من المعلومات، يمكنك الاطّلاع على إعداد برنامج Places API.
ستظل تطبيقاتك الحالية تعمل بدون تغيير، ولكن يمكنك الآن الاستفادة من جميع ميزات حزمة SDK الجديدة.
الميزات الرئيسية التي تمت إضافتها إلى حزمة تطوير برامج الأماكن لأجهزة Android (جديدة)
يتناول هذا القسم الميزات الأساسية التي تمت إضافتها إلى حزمة "SDK للأماكن" على أجهزة Android (جديدة).
تم التنفيذ على منصة Google Cloud العادية
يتم تنفيذ حزمة تطوير برامج الأماكن لأجهزة Android (الجديدة) على البنية الأساسية للخدمة على Google Cloud. يوفر هذا التنفيذ منصة أكثر أمانًا وموثوقية. يضيف هذا التصميم القياسي مستوى من الاتساق على مستوى حزم SDK التي تعمل على تحسين كفاءة التطوير باستخدام حزمة "SDK للأماكن" على Android (جديد).
تحسين الأداء
تُوفّر حزمة تطوير برامج الأماكن لنظام التشغيل Android (الجديدة) أداءً محسنًا، مما يجعل من المفيد استبدال التطبيقات التي تستخدم حزمة تطوير البرامج (SDK) الحالية.
خدمة "البحث النصي" الجديدة
تعرض ميزة البحث النصي معلومات حول مجموعة من الأماكن استنادًا إلى سلسلة، على سبيل المثال "فطائر في دبي" أو "متاجر أحذية بالقرب من أوتاوا" أو "123 الشارع الرئيسي". تستجيب الخدمة بقائمة من الأماكن التي تطابق السلسلة النصية وأي تحيز للموقع تم تعيينه.
تمت إضافة بيانات رد جديدة إلى "تفاصيل المكان" و"صور المكان".
تتضمن تفاصيل المكان الآن فئة المراجعة الجديدة في كائن الاستجابة
Place
. تحتوي الفئة Place على طريقةgetReviews()
الجديدة لإتاحة هذا الحقل. اتصل بالرقمgetReviews()
لعرض ما يصل إلى خمس مراجعات عن مكان معيّن.تضيف ميزة صورة المكان السمة
AuthorAttributions
إلى الصفPhotoMetadata
. يحتويAuthorAttributions
علىList
منAuthorAttribution
كائنات.
تمت إضافة رد معرف موارد منتظم (URI) جديد إلى "صور المكان"
يمكنك الآن استخدام صور المكان لعرض عنوان URI لصورة نقطية. في السابق، لم يكن بإمكانك سوى إرجاع الصورة النقطية نفسها.
الأسعار المبسّطة
تم تبسيط الأسعار باستخدام حزمة "حزمة تطوير البرامج للأماكن" لنظام التشغيل Android (جديد) بحيث تدفع فقط مقابل البيانات التي تستخدمها. ويتم تطبيق الأسعار المبسَّطة باستخدام قوائم الحقول، التي تُعرَف أيضًا باسم أقنعة الحقول.
مع "تفاصيل المكان" و"البحث النصي"، يمكنك استخدام قوائم الحقول للتحكم في قائمة الحقول المطلوب عرضها في الرد. وعندئذٍ يتم تحصيل رسوم منك مقابل البيانات المطلوبة فقط. يعد استخدام قائمة حقول ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، مما يساعد على تجنب وقت المعالجة غير الضروري ورسوم الفوترة.
للحصول على معلومات مفصّلة حول الأسعار لكل من حزمتَي تطوير البرامج (SDK)، يُرجى الاطّلاع على الاستخدام والفوترة.
أنواع الأماكن الموسّعة
تضيف حزمة تطوير البرامج (SDK) الجديدة أنواع الأماكن الموضحة في الجدول التالي. يتم عرض هذه الأنواع كجزء من استجابة "تفاصيل المكان" و"البحث النصي". يمكنك أيضًا استخدام هذه الأنواع الجديدة والأنواع الحالية في البحث باستخدام "البحث النصي". ويتم إدراج الأنواع الجديدة في الجدول "أ".
النوع | |||
---|---|---|---|
american_restaurant | discount_store | ice_cream_shop | sandwich_shop |
amusement_center | dog_park | indian_restaurant | school_district |
athletic_field | electric_vehicle_charging_station | indonesian_restaurant | seafood_restaurant |
auto_parts_store | event_venue | italian_restaurant | ski_resort |
banquet_hall | extended_stay_hotel | japanese_restaurant | spanish_restaurant |
barbecue_restaurant | مزرعة | korean_restaurant | sporting_goods_store |
barber_shop | مزرعة | lebanese_restaurant | sports_club |
bed_and_breakfast | fast_food_restaurant | marina | sports_complex |
brazilian_restaurant | ferry_terminal | سوق | steak_house |
breakfast_restaurant | fitness_center | medical_lab | sushi_restaurant |
brunch_restaurant | french_restaurant | mediterranean_restaurant | swimming_pool |
bus_stop | gift_shop | mexican_restaurant | خياط |
camping_cabin | golf_course | middle_eastern_restaurant | telecommunications_service_provider |
cell_phone_store | greek_restaurant | موتيل | thai_restaurant |
child_care_agency | grocery_store | national_park | transit_depot |
chinese_restaurant | guest_house | park_and_ride | truck_stop |
coffee_shop | hair_salon | performing_arts_theater | turkish_restaurant |
community_center | hamburger_restaurant | pizza_restaurant | vegan_restaurant |
مستشار | مهبط طائرات هليكوبتر | playground | vegetarian_restaurant |
convention_center | hiking_area | أطفال الروضة | vietnamese_restaurant |
كوخ | historical_landmark | private_guest_room | visitor_center |
courier_service | home_improvement_store | ramen_restaurant | wedding_venue |
cultural_center | نزل | resort_hotel | تاجر جملة |
dental_clinic | hotel | rest_stop |
country
administrative_area_level_1
administrative_area_level_2
postal_code
locality