نسخه SDK خود را انتخاب کنید

Places SDK for Android نسخه 3.4.0 از دو نسخه SDK پشتیبانی می کند: Places SDK for Android SDK موجود است و Places SDK for Android (جدید) نسخه نسل بعدی SDK است.

توجه: همه ویژگی‌های جدید موجود در این نسخه بخشی از Places SDK برای Android (جدید) هستند و در Places SDK برای Android در دسترس نیستند.

با انتشار Places SDK برای اندروید نسخه 3.4.0، اولین وظیفه شما این است که تصمیم بگیرید از کدام SDK استفاده کنید. اگر شما یک مشتری جدید یا مشتری فعلی هستید که قبلاً از SDK استفاده می‌کنید، این درست است. از این راهنما برای درک تفاوت های کلیدی بین دو SDK استفاده کنید.

نحوه انتخاب نسخه SDK

در باطن، Places SDK برای Android به سرویس Places API، Places API (جدید) یا Places API متکی است. قبل از اینکه بتوانید از Places SDK برای Android استفاده کنید، باید سرویس Places API را در پروژه Google Cloud خود فعال کنید.

برای Android، برای تعیین اینکه کدام API را می‌توانید در برنامه خود استفاده کنید، دو اقدام انجام می‌دهید:

1. در پروژه خود، بسته به این که قصد دارید در برنامه خود استفاده کنید، باید Places API (جدید)، Places API یا هر دو را در کلید API خود فعال کنید.

2. برنامه خود را با فراخوانی متد Places.initializeWithNewPlacesApiEnabled() یا Places.initialize() راه اندازی کنید.

SDK خود را انتخاب کنید

نسخه سرویس Places API که فعال می کنید، نسخه SDK مورد استفاده برنامه شما را کنترل می کند:

• هر دو : همه ویژگی‌ها را برای Places SDK برای Android و Places SDK برای Android (جدید) فعال می‌کند. از متد Places.initializeWithNewPlacesApiEnabled() و Places.initialize() برای کنترل ویژگی های موجود استفاده کنید.

• Places API : Places SDK موجود برای Android را فعال می کند. شما به ویژگی های جدید اضافه شده در Places SDK برای Android نسخه 3.4.0 دسترسی ندارید.

• Places API (جدید) : Places SDK را برای Android (جدید) و همه ویژگی‌های جدید توضیح داده شده در ویژگی‌های کلیدی اضافه شده به Places SDK برای Android (جدید) را فعال می‌کند، اما ویژگی‌های موجود مانند مکان فعلی و تکمیل خودکار مکان را فعال نمی‌کند.

برای اطلاعات بیشتر در مورد انتخاب سرویس Places API، به راه اندازی پروژه Google Cloud خود مراجعه کنید.

برنامه خود را راه اندازی کنید

هنگامی که برنامه خود را مقداردهی اولیه می کنید، باید متد Places.initializeWithNewPlacesApiEnabled() یا Places.initialize() را فراخوانی کنید.

جدول زیر اثرات فعال کردن هر SDK و فراخوانی هر روش مقداردهی اولیه را نشان می دهد. به عنوان مثال، اگر Places SDK (جدید) را فعال کنید و Places.initializeWithNewPlacesApiEnabled() را فراخوانی کنید، می توانید از همه APIهای جدید و همه APIهای موجود استفاده کنید.

اگر Places SDK (جدید) را فعال کنید و Places.initialize() را فراخوانی کنید، نمی‌توانید از ویژگی‌های جدید جزئیات مکان و عکس‌های مکان استفاده کنید، اما می‌توانید جستجوی متن جدید را فراخوانی کنید. اگر Places API را فعال نکنید، نمی‌توانید به نسخه قدیمی Place Details دسترسی پیدا کنید، اما همچنان می‌توانید با جستجوی متن جدید تماس بگیرید.

نسخه	API ها	SDK روی کلید API فعال شد		روش مقداردهی اولیه
		Places API	Places API (جدید)	initialize()	initializeWithNewPlacesApiEnabled()
نسخه 3.3.0	جزئیات مکان ها
	جزئیات مکان ها (جدید)
	فراداده عکس (جدید)
	جستجوی متن (جدید)			هر دو روش
نسخه 3.4.0	عکس اوری (جدید)
	عکس بیت مپ			هر دو روش
	مکان فعلی			هر دو روش
	تکمیل خودکار			هر دو روش

کدام SDK را انتخاب می کنید؟

برای کمک به تصمیم گیری برای انتخاب نسخه:

1. اگر مشتری جدیدی هستید که به تازگی با Places SDK برای Android شروع کرده اید، با Places API (جدید) و SDK جدید شروع کنید.

2. اگر توسعه‌دهنده Kotlin هستید، می‌توانید از یکی از SDK استفاده کنید، اما ویژگی‌های جدید Places SDK برای Android (جدید) فقط در جاوا در نسخه 3.4.0 موجود است.

3. اگر مشتری فعلی هستید و از نشانه‌های جلسه استفاده می‌کنید، به استفاده از SDK موجود ادامه دهید. Places SDK برای Android (جدید) در حال حاضر از نشانه‌های جلسه پشتیبانی نمی‌کند.

4. اگر مشتری فعلی هستید، می توانید به استفاده از SDK موجود ادامه دهید. با این حال، برای استفاده از بهبود عملکرد و بهبود ویژگی‌های Places SDK برای Android (جدید)، می‌توانید از SDK جدید استفاده کنید.

   هنگام انتقال به SDK جدید، نیازی به مهاجرت نیست. شما فقط باید:

   1. Places API (جدید) را در کلید API مورد استفاده در برنامه خود فعال کنید. برای اطلاعات بیشتر، به استفاده از کلیدهای API مراجعه کنید.

   2. در بخش 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 در وابستگی های متعدی مراجعه کنید.

   3. برنامه موجود خود را برای فراخوانی متد جدید Places.initializeWithNewPlacesApiEnabled() برای مقداردهی اولیه برنامه خود به روز کنید. برای اطلاعات بیشتر، به Initialize the Places API Client مراجعه کنید.

   برنامه‌های موجود شما بدون تغییر کار می‌کنند، اما اکنون می‌توانید از همه ویژگی‌های جدید SDK استفاده کنید.

ویژگی‌های کلیدی اضافه شده به Places SDK برای Android (جدید)

این بخش ویژگی های کلیدی اضافه شده به Places SDK برای Android (جدید) را پوشش می دهد.

بر روی پلت فرم استاندارد Google Cloud پیاده سازی شده است

Places SDK برای Android (جدید) در زیرساخت خدمات در Google Cloud پیاده سازی شده است. این پیاده سازی یک پلت فرم امن تر و قابل اعتمادتر را به ارمغان می آورد. این طراحی استاندارد سطحی از سازگاری را در بین SDK ها به ارمغان می آورد که کارایی توسعه را با Places SDK برای Android (جدید) بهبود می بخشد.

عملکرد بهبود یافته است

Places SDK برای Android (جدید) عملکرد بهبود یافته ای را ارائه می دهد و جایگزینی برنامه هایی که از SDK موجود استفاده می کنند ارزشمند است.

سرویس جستجوی متن جدید

جستجوی متن اطلاعات مجموعه‌ای از مکان‌ها را بر اساس یک رشته برمی‌گرداند - برای مثال «پیتزا در نیویورک» یا «فروشگاه‌های کفش در نزدیکی اتاوا» یا «خیابان اصلی ۱۲۳». این سرویس با فهرستی از مکان‌های منطبق با رشته متن و هرگونه سوگیری مکان تنظیم شده پاسخ می‌دهد.

داده‌های پاسخ جدید به جزئیات قرار داده شده و عکس‌های مکان اضافه شد

• اکنون Place Details شامل کلاس Review جدید در شیء پاسخ Place می شود. کلاس Place حاوی متد getReviews() جدید برای پشتیبانی از این فیلد است. با getReviews() تماس بگیرید تا حداکثر پنج نظر را برای یک مکان برگردانید.

• Place Photo، AuthorAttributions به کلاس PhotoMetadata اضافه می کند. AuthorAttributions حاوی List از اشیاء AuthorAttribution است.

پاسخ URI جدید به عکس‌های مکان اضافه شد

اکنون می توانید از Place Photos برای برگرداندن یک URI به یک بیت مپ تصویر استفاده کنید. قبلاً فقط می‌توانستید خود بیت مپ تصویر را برگردانید.

قیمت گذاری ساده شده

قیمت گذاری با Places SDK برای Android (جدید) ساده شده است، به طوری که شما فقط برای داده هایی که استفاده می کنید پرداخت می کنید. قیمت گذاری ساده شده با استفاده از لیست های فیلد، که به آن ماسک های میدان نیز می گویند، اجرا می شود.

با جزئیات مکان و جستجوی متن، از لیست فیلدها برای کنترل لیست فیلدهایی که باید در پاسخ بازگردانده شوند، استفاده می کنید. سپس فقط برای داده های درخواستی صورتحساب دریافت می کنید. استفاده از فهرست فیلد یک روش طراحی خوب برای اطمینان از عدم درخواست داده‌های غیرضروری است که به جلوگیری از زمان پردازش غیر ضروری و هزینه‌های صورت‌حساب کمک می‌کند.

برای اطلاعات دقیق قیمت گذاری برای هر دو SDK، استفاده و صورتحساب را ببینید.

توجه: مدل قیمت‌گذاری جدید فقط برای جزئیات مکان، جستجوی متن و عکس‌های مکان اعمال می‌شود. قیمت تکمیل خودکار مکان و مکان فعلی برای هر دو SDK یکسان است.

انواع مکان های گسترده

SDK جدید انواع مکان های نشان داده شده در جدول زیر را اضافه می کند. این انواع به عنوان بخشی از پاسخ جزئیات مکان و جستجوی متن برگردانده می شوند. همچنین می توانید از این انواع جدید و انواع موجود در جستجو با جستجوی متن استفاده کنید. انواع جدید در جدول A آمده است.

تایپ کنید
رستوران_آمریکایی	تخفیف_فروشگاه	بستنی فروشی	ساندویچ_فروشی
مرکز_تفریح	سگ_پارک	رستوران هندی	محدوده مدرسه
رشته_ ورزشی	ایستگاه_شارژ_خودرو_برقی	اندونزی_رستوران	رستوران غذاهای دریایی
فروشگاه_قطعات_خودرو	رویداد_محل برگزاری	رستوران ایتالیایی	پیست اسکی
سالن های ضیافت	طولانی_ اقامت_هتل	رستوران ژاپنی	رستوران_اسپانیایی
باربیکیو_رستوران	مزرعه	رستوران_کوری	فروشگاه_کالاهای_ورزشی
آرایشگاه	مزرعه	رستوران_لبنانی	باشگاه ورزشی
تخت_و_صبحانه	رستوران فست فود	مارینا	مجموعه ورزشی
رستوران_برزیلی	ترمینال_فری	بازار	استیک_خانه
صبحانه_رستوران	مرکز تناسب اندام	آزمایشگاه_پزشکی	سوشی_رستوران
برانچ_رستوران	رستوران فرانسوی	رستوران_مدیترانه ای	استخر
ایستگاه اتوبوس	هدیه_فروشگاه	رستوران مکزیکی	خیاط
کمپینگ_کابین	زمین_گلف	رستوران_خاورمیانه	ارائه دهنده خدمات_ مخابراتی
فروشگاه_موبایل	یونانی_رستوران	متل	تای_رستوران
آژانس_مراقبت_کودک	فروشگاه بقالی	پارک ملی	transit_depot
رستوران چینی	مهمان خانه	پارک_و_سواری	کامیون_ایست
کافی شاپ	سالن آرایش	تئاتر_هنرهای_نمایش	رستوران_تورکی
مرکز ارتباطات	همبرگر_رستوران	پیتزا_رستوران	رستوران_وگان
مشاور	هلی فرودگاه	زمین بازی	رستوران_گیاهی
مرکز کنوانسیون	منطقه پیاده روی	پیش دبستانی	رستوران_ویتنامی
کلبه	نشانه_ تاریخی	اتاق_مهمان_خصوصی	بازدید کننده_مرکز
پیک_خدمات	خانه_بهبود_فروشگاه	رامن_رستوران	محل برگزاری عروسی
مرکز فرهنگی	خوابگاه	resort_hotel	عمده فروش
کلینیک دندانپزشکی	هتل	استراحت_توقف

همراه با این انواع جدید، Places API (جدید) انواع زیر را از جدول B از جدول A منتقل کرد. یعنی اکنون می توانید از این انواع به عنوان بخشی از جستجو استفاده کنید:

• country
• administrative_area_level_1
• administrative_area_level_2
• postal_code
• locality