خط‌مشی‌ها و تخصیص‌ها برای Places SDK برای iOS

این سند الزاماتی را فهرست می‌کند که مختص تمام برنامه‌های توسعه‌یافته با Places SDK برای iOS هستند، از جمله سرویس تکمیل خودکار Place که بخشی از آن API است. اطلاعات عمومی بیشتر برای توسعه‌دهندگان Google Maps را می‌توانید در شرایط خدمات پلتفرم Google Maps بیابید.

سیاست‌ها

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

استثنائات محدودیت‌های ذخیره‌سازی

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

کشورها و قلمروهای منطقه اقتصادی اروپا

این محصول برای مشتریانی که آدرس صورتحساب آنها در منطقه اقتصادی اروپا (EEA) است، شرایط خدمات متفاوتی دارد و همچنین ممکن است عملکردهای متفاوتی داشته باشد. قبل از ساخت با پلتفرم Google Maps، شرایط و اطلاعات خاص EEA زیر را بررسی کنید:

• شرایط خدمات پلتفرم نقشه‌های گوگل در منطقه اقتصادی اروپا
• شرایط خاص سرویس پلتفرم نقشه‌های گوگل (Google Maps Platform) در منطقه اقتصادی اروپا (EEA)
• سوالات متداول منطقه اقتصادی اروپا (FAQ)
• الزامات ایمنی جاده‌ای پلتفرم نقشه گوگل

اگر آدرس صورتحساب شما در منطقه اقتصادی اروپا (EEA) نیست، شرایط خدمات زیر برای شما اعمال می‌شود:

• شرایط خدمات پلتفرم نقشه‌های گوگل
• شرایط خاص سرویس پلتفرم نقشه‌های گوگل

الزامات انتساب نقشه‌های گوگل

این بخش الزامات و دستورالعمل‌های مربوط به انتساب را برای نمایش نقشه‌های گوگل و محتوا از طریق برنامه‌های شما ارائه می‌دهد.

توجه: الزامات به‌روزرسانی‌شده‌ی انتساب زیر، اکنون به جای فقط «گوگل»، از «نقشه‌های گوگل» استفاده می‌کنند. ما اذعان داریم که پیاده‌سازی‌های موجود شما ممکن است مطابق با راهنمایی‌های قبلی از انتساب «گوگل» استفاده کنند و فعلاً می‌توانید به استفاده از «گوگل» به عنوان انتساب ادامه دهید. برای پیاده‌سازی‌های جدید، از «نقشه‌های گوگل» همانطور که در این بخش توضیح داده شده است استفاده کنید. در آینده، جدول زمانی و دستورالعمل‌هایی را برای کمک به شما در انتقال انتساب‌های موجود «گوگل» به انتساب‌های «نقشه‌های گوگل» ارائه خواهیم داد.

مثال انتساب

در ادامه یک مثال از انتساب برای کیت رابط کاربری Places آورده شده است.

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

نمایش اطلاعات مربوط به نقشه گوگل

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

شامل انتساب نقشه‌های گوگل

برای انتساب نقشه‌های گوگل که از قبل توسط پلتفرم نقشه‌های گوگل در رابط کاربری ارائه شده است، مانند کیت رابط کاربری Places:

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

لوگو و متن گوگل مپ

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

چپ: نمونه‌ای از انتساب لوگوی گوگل مپ، راست: نمونه‌ای از انتساب متن گوگل مپ

انتساب لوگو

برای استفاده از لوگوی گوگل مپ در برنامه یا وب‌سایت خود، این الزامات را رعایت کنید.

نمونه‌هایی از تغییرات قابل قبول برای انتساب لوگوی گوگل مپ

دانلود لوگوهای گوگل مپ

از فایل‌های رسمی لوگوی گوگل مپ استفاده کنید. لوگوهای زیر را دانلود کنید و دستورالعمل‌های این بخش را دنبال کنید.

فایل‌های مربوط به اسناد گوگل مپ را دانلود کنید

هنگام استفاده از لوگوی گوگل مپ، این دستورالعمل‌ها را دنبال کنید.

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

مشخصات اندازه لوگو

برای لوگوی گوگل مپ، این مشخصات اندازه را دنبال کنید:

• حداقل ارتفاع لوگو: 16dp
• حداکثر ارتفاع لوگو: ۱۹dp
• حداقل فضای خالی لوگو: 10dp در سمت چپ، راست و بالا، 5dp در پایین

برای کسب اطلاعات در مورد dp، به بخش تراکم پیکسل در وب‌سایت Material Design مراجعه کنید.

نمونه‌ای از لوگوی گوگل مپ که حداقل فضای خالی و محدوده اندازه قابل قبول را نشان می‌دهد

دسترسی‌پذیری لوگو

این الزامات دسترسی را برای لوگوی گوگل مپس دنبال کنید:

• بین لوگو و پس‌زمینه، تضاد قابل قبولی ایجاد کنید.
• یک برچسب دسترسی‌پذیری با متن Google Maps اضافه کنید.

نمونه‌هایی از تغییرات غیرقابل قبول و مشکلات دسترسی برای انتساب لوگوی گوگل مپس

انتساب متن

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

نمونه‌هایی از تغییرات قابل قبول در انتساب متن نقشه‌های گوگل

• متن نقشه‌های گوگل را به هیچ وجه تغییر ندهید:
  
  • حروف بزرگ و کوچک گوگل مپ را تغییر ندهید
  • نقشه‌های گوگل را در چندین خط قرار ندهید
  • نقشه‌های گوگل را به زبان دیگری بومی‌سازی نکنید.
  • با استفاده از ویژگی HTML translate="no" از ترجمه نقشه‌های گوگل توسط مرورگرها جلوگیری کنید.

نمونه‌هایی از تغییرات غیرقابل قبول در انتساب متن نقشه‌های گوگل

• متن نقشه گوگل را مطابق جدول زیر استایل دهید:

  الزامات مربوط به سبک‌دهی متن در نقشه گوگل
  ملک	سبک
  خانواده فونت	بارگذاری فونت اختیاری است.
  خانواده فونت جایگزین	هر فونت بدنه‌ی سنس‌سریف که از قبل در محصول شما استفاده شده است یا "سنس‌سریف" برای فراخوانی فونت پیش‌فرض سیستم
  سبک فونت	عادی
  وزن فونت	۴۰۰
  رنگ فونت	سفید، مشکی (#1F1F1F) یا خاکستری (#5E5E5E). کنتراست (4.5:1) قابل قبول را نسبت به پس‌زمینه حفظ کنید.
  اندازه فونت	حداقل اندازه فونت: 12sp حداکثر اندازه فونت: 16sp برای کسب اطلاعات در مورد sp، به واحدهای اندازه فونت در وب‌سایت Material Design مراجعه کنید.
  فاصله حروف	عادی

مثال CSS

کد CSS زیر نقشه‌های گوگل را با سبک و رنگ تایپوگرافی مناسب روی پس‌زمینه سفید یا روشن نمایش می‌دهد.

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

.GMP-attribution {
font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}

الزامات بصری

برای نحوه‌ی نمایش بصری ارجاعات نقشه‌های گوگل، این الزامات را رعایت کنید.

• انتساب را در نزدیکی بالا یا پایین محتوا و در همان ظرف بصری قرار دهید. برای یک خط محتوا، انتساب می‌تواند در سمت راست یا چپ قرار گیرد.

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

• با نسبت دادن محتوای غیر از پلتفرم نقشه‌های گوگل، نقشه‌های گوگل را تحریف نکنید.
• تأیید کنید که منبع همیشه قابل مشاهده و خوانا باشد. هرگز آن را حذف، پنهان، مبهم یا تغییر ندهید.

شکل‌های زیر نمونه‌هایی از این الزامات بصری را نشان می‌دهند.

نمونه‌ای از انتساب نقشه‌های گوگل که در بالا، پایین و کنار محتوا قرار گرفته است

مثالی از دو رویکرد برای تمایز محتوای نقشه‌های گوگل (رتبه‌بندی مکان) از سایر محتواها

منبع گوگل مپ را مبهم نکنید یا آن را با محتوای منابع دیگر ترکیب نکنید.

ارائه دهندگان داده شخص ثالث

برخی از داده‌ها و تصاویر موجود در محصولات نقشه‌برداری ما از ارائه‌دهندگانی غیر از گوگل می‌آیند. برای برخی از محصولات، مانند Map Tiles API، ممکن است نسبت‌دهی لازم به ارائه‌دهنده داده شخص ثالث را در اختیار شما قرار دهیم. در این صورت، متن نسبت‌دهی شما باید شامل نام "Google Maps" و ارائه‌دهنده(گان) داده مربوطه، مانند "Map data: Google, Maxar Technologies" باشد. هنگامی که گوگل نسبت‌دهی شخص ثالث را ارائه می‌دهد، فقط ذکر "Google Maps" یا لوگوی گوگل، نسبت‌دهی مناسبی محسوب نمی‌شود.

سایر الزامات انتساب

ارجاعات به ارائه‌دهندگان شخص ثالث حاوی محتوا و پیوندهایی است که شما باید آنها را به همان شکلی که ارائه شده‌اند به کاربر نمایش دهید. گوگل توصیه می‌کند که برنامه شما این اطلاعات را در زیر جزئیات مکان نمایش دهد.

انتساب‌های شخص ثالث که توسط API برگردانده می‌شوند، شامل انتساب گوگل نمی‌شوند . شما باید خودتان این انتساب را، همانطور که در نمایش لوگو و انتساب‌های گوگل توضیح داده شده است، وارد کنید.

نکته: ممکن است استفاده از یک کتابخانه شخص ثالث برای رندر کردن داده‌های NSAttributedString برایتان راحت‌تر باشد.

برای بازیابی اطلاعات شخص ثالث برای یک مکان یا مجموعه‌ای از مکان‌ها، این دستورالعمل‌ها را دنبال کنید.

بازیابی اسناد برای یک مکان واحد

وقتی مکانی را با دریافت شناسه آن بازیابی می‌کنید، می‌توانید ویژگی‌های آن مکان را از attributions در GMSPlace بازیابی کنید.

این attributions به عنوان یک شیء NSAttributedString ارائه می‌شوند.

بازیابی شناسه‌ها برای مجموعه‌ای از مکان‌ها

اگر برنامه شما اطلاعات به دست آمده از درخواست مکان فعلی دستگاه را نمایش می‌دهد، برنامه باید ویژگی‌های شخص ثالث را برای جزئیات مکان نمایش داده شده نمایش دهد. می‌توانید ویژگی‌های مربوط به همه مکان‌های بازیابی شده در درخواست را از ویژگی attributions در GMSPlaceLikelihoodList بازیابی کنید.

این attributions به عنوان یک شیء NSAttributedString ارائه می‌شوند که می‌توانید به آن دسترسی داشته باشید و آن را مانند attributions در یک مکان واحد، همانطور که در بالا توضیح داده شد، نمایش دهید.

انتساب نتایج جستجو

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

سربرگ: درباره این نتایج

بدنه: وقتی به دنبال کسب و کارها یا مکان‌های نزدیک به یک مکان می‌گردید، نقشه‌های گوگل نتایج محلی را به شما نشان می‌دهند. چندین عامل - در درجه اول ارتباط، فاصله و برجستگی - با هم ترکیب می‌شوند تا به شما در یافتن بهترین نتایج برای جستجویتان کمک کنند.

دکمه ۱: اطلاعات بیشتر
متن «بیشتر بدانید» باید به یک مقاله مرکز راهنما پیوند داشته باشد.

دکمه ۲: تایید

نمایش ویژگی‌های یک عکس

اگر برنامه شما عکس‌ها را نمایش می‌دهد، باید هرگونه attributions و authorAttributions برای هر عکسی که آنها را دارد، نمایش دهید.

• برای دسترسی به هرگونه ویژگی، از GMSPlacePhotoMetadata.attributions استفاده کنید. این ویژگی یک NSAttributedString است، یا اگر هیچ ویژگی برای نمایش وجود ندارد، nil .
• برای دسترسی به هرگونه ویژگی مربوط به نویسنده، از GMSPlacePhotoMetadata.authorAttributions استفاده کنید. این ویژگی شامل آرایه‌ای از اشیاء GMSPlaceAuthorAttribution است.

سویفت

GMSPlacesClient.sharedClient().lookUpPhotosForPlaceID(placeID) { (photos, error) -> Void in
  if let error = error {
    // TODO: handle the error.
    print("Error: \(error.description)")
  } else {
    // Get attribution for the first photo in the list.
    if let photo = photos?.results.first {
      let attributions = photo.attributions
    }
  }
}
    

هدف-سی

[[GMSPlacesClient sharedClient]
    lookUpPhotosForPlaceID:placeID
      callback:^(GMSPlacePhotoMetadataList *_Nullable photos,
                  NSError *_Nullable error) {
        if (error) {
          // TODO: handle the error.
          NSLog(@"Error: %@", [error description]);
        } else {
          // Get attribution for the first photo in the list.
          if (photos.results.count > 0) {
            GMSPlacePhotoMetadata *photo = photos.results.firstObject;
            NSAttributedString *attributions = photo.attributions;
          }
        }
      }];
    

نمایش یک نقد و بررسی

یک شیء GMSPlace می‌تواند شامل حداکثر پنج نقد و بررسی باشد که هر نقد و بررسی توسط یک شیء GMSPlaceReview نمایش داده می‌شود. شما می‌توانید به صورت اختیاری این نقد و بررسی‌ها را در برنامه خود نمایش دهید.

هنگام نمایش نظرات کاربران گوگل، باید نام نویسنده را در نزدیکی آن قرار دهید. در صورت وجود امکان ذکر نام نویسنده در فیلد انتساب نویسنده از شیء GMSPlaceReview ، توصیه می‌کنیم عکس نویسنده و لینک به پروفایل او را نیز درج کنید. تصویر زیر نمونه‌ای از یک نظر در مورد یک پارک را نشان می‌دهد:

گوگل همچنین توصیه می‌کند که نحوه مرتب‌سازی نظرات را به کاربر نهایی نمایش دهید.

نکته: پیش‌فرض این است که نظرات بر اساس میزان مرتبط بودن مرتب شوند. برای SDK جدید، مرتب‌سازی بر اساس میزان مرتبط بودن تنها گزینه است.

برای دسترسی به نظرات:

سویفت

// Define a Place ID.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties: [GMSPlaceProperty] = [.name, .website, .reviews]

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties)

client.fetchPlaceWithRequest(fetchPlaceRequest: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    let firstReview: GMSPlaceReview = place.reviews![0]

    // Use firstReview to access review text, authorAttribution, and other fields.

  }
})

هدف-سی

// Define a Place ID.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return, including reviews.
NSArray<GMSPlaceProperty *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite,GMSPlacePropertyReviews];

GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest, callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
  if (error) {
    // TODO: handle the error.
    NSLog(@"Error: %@", [error description]);
  } else {
    // Get first review.
    GMSPlaceReview *firstReview = [place reviews][0];

    // Use firstReview to access review text, authorAttribution, and other fields.

  }
}];

نمایش مشخصات شخص ثالث

نسبت دادن به ارائه دهندگان شخص ثالث به صورت اشیاء NSAttributedString ارائه می‌شوند که حاوی محتوا و پیوندهایی هستند که شما باید آنها را حفظ کرده و به کاربر نمایش دهید.

روش پیشنهادی برای نمایش ویژگی‌ها، استفاده از UITextView است، زیرا لینک‌های موجود در ویژگی‌ها باید کار کنند. برای اطمینان از عملکرد لینک‌ها، یک delegate روی UITextView تنظیم کنید و متد shouldInteractWithURL از UITextViewDelegate خود را طوری تنظیم کنید که YES برگرداند.

سویفت

...
  self.attributionTextView.delegate = self
...

// MARK: - UITextViewDelegate

func textView(textView: UITextView, shouldInteractWithURL URL: NSURL,
  inRange characterRange: NSRange) -> Bool {
  // Make links clickable.
  return true
}
    

هدف-سی

...
  self.attributionTextView.delegate = self;
...

#pragma mark - UITextViewDelegate

- (BOOL)textView:(UITextView *)textView
    shouldInteractWithURL:(NSURL *)url
                  inRange:(NSRange)characterRange {
  // Make links clickable.
  return YES;
}
    

نمونه‌ای از انتساب به شخص ثالث

انتساب به شخص ثالث معمولاً شامل متنی با لینک است. برای مثال:

فهرست‌ها بر اساس شرکت نمونه

در مثال بالا، محدوده متن Example Company توسط یک ویژگی NSLink پوشش داده شده است.

تکمیل خودکار آدرس‌های کاربر نهایی

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

در تصویر قبلی، لیست آدرس‌های سمت چپ همچنان مشمول محدودیت‌های محتوای نقشه‌های گوگل است. هنگامی که کاربر نهایی آدرس مورد نظر خود را انتخاب می‌کند، آن آدرس صرفاً برای تراکنش مربوطه کاربر نهایی، مشمول محدودیت‌های محتوای نقشه‌های گوگل نمی‌شود.