خط‌مشی‌ها و ارجاع‌های Maps JavaScript API

این سند فهرستی از الزامات برنامه‌های توسعه‌یافته با Maps JavaScript API را ارائه می‌دهد. توجه داشته باشید که استفاده از Maps JavaScript API تحت کنترل «قرارداد شما با Google» است.

خط‌مشی‌ها

این بخش خط‌مشی‌های مربوط به Maps JavaScript API را شرح می‌دهد. خط‌مشی‌ها دستورالعمل‌ها و الزامات اجرایی عملی ارائه می‌دهند تا به شما کمک کنند از «سرویس» به‌درستی و مطابق با انتظارات «پلاتفرم Google Maps» استفاده کنید.

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

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

تراشیدن محتوا

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

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

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

• شرایط خدمات پلاتفرم Google Maps در منطقه اقتصادی اروپا
• شرایط خاص سرویس پلاتفرم Google Maps در منطقه اقتصادی اروپا
• پرسشگان منطقه اقتصادی اروپا
• ملزومات ایمنی جاده‌ای «پلاتفرم Google Maps»

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

• شرایط خدمات پلاتفرم Google Maps
• شرایط خاص سرویس پلاتفرم Google Maps

الزامات ارجاع Google Maps

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

مثال اسنادی

در زیر نمونه‌ای از اسناد استنادی برای «کیت میانای کاربر جاها» آورده شده است.

نمایش اسناد Google Maps

هنگام نمایش «محتوا» از «میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps» در برنامه یا وب‌سایتتان، باید از الزامات ذکر منبع Google Maps پیروی کنید. اگر «محتوا» در «نقشه Google» نشان داده شود و اسناد قبلاً نمایان باشد، نیازی به افزودن اسناد اضافی نیست.

اسناد Google Maps اضافه شد

برای اسناد Google Maps که قبلاً توسط «پلاتفرم Google Maps» در واسط کاربر ارائه شده است، مانند «کیت واسط کاربر مکان‌ها»:

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

نشان‌واره Google Maps و اسناد استنادی نوشتاری

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

ارجاع نشان‌واره

بارگیری نشان‌واره‌های Google Maps

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

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

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

مشخصات اندازه نشان‌واره

• حداقل ارتفاع نشان‌واره: ۱۶ پیکسل
• حداکثر ارتفاع نشان‌واره: ۱۹ پیکسل
• حداقل فضای خالی نشان‌واره: ۱۰ پیکسل در سمت راست، چپ، و بالا، ۵ پیکسل در پایین

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

دسترسی‌پذیری نشان‌واره

• تضاد دسترس‌پذیری بین نشان‌واره و پس‌زمینه حفظ کنید.
• برچسب دسترس‌پذیری را با نوشتار Google Maps اضافه کنید.

انتساب نوشتار

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

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

• نوشتار Google Maps را به‌سبک شرح‌داده‌شده در جدول زیر بنویسید:

  الزامات سبک‌دهی نوشتار Google Maps
  دارایی	سبک
  خانواده قلم	Roboto. بار کردن قلم اختیاری است.
  خانواده قلم جایگزین	هر قلم سن‌سریف نوشتار اصلی که ازقبل در محصولتان استفاده شده است یا «سن‌سریف» برای فراخواندن قلم سیستم پیش‌فرض
  سبک قلم	معمولی
  سیاهی قلم	۴۰۰
  رنگ قلم	سفید، سیاه (#1F1F1F)، یا خاکستری (#5E5E5E). تضاد (۴٫۵:۱) دسترس‌پذیر را دربرابر پس‌زمینه حفظ کنید.
  اندازه قلم	حداقل اندازه قلم: ۱۲ اس‌پی حداکثر اندازه قلم: ۱۶ اس‌پی برای آشنایی با اس‌پی، واحدهای اندازه قلم را در وب‌سایت «طراحی مواد» ببینید.
  فاصله حروف	معمولی

نمونه CSS

‫CSS زیر Google Maps را با سبک و رنگ مناسب حروف‌چینی در پس‌زمینه سفید یا روشن ارائه می‌کند.

@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;
}

الزامات دیداری

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

• «محتوای پلاتفرم Google Maps» را بااستفاده از نشانه‌های میانای کاربری مثل حاشیه، رنگ پس‌زمینه، سایه، یا فضای سفید کافی، ازنظر بصری از محتوای دیگر متمایز کنید.

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

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

ارائه‌دهندگان داده طرف سوم

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

سایر الزامات ارجاع

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

واکشی اسناد اِسنادی از «مکان»

اگر برنامه شما اطلاعات مرور را که ازطریق تماس با Place.fetchFields به‌دست آمده است نمایش می‌دهد، برنامه باید اسناد انتساب طرف سوم را نیز برای جزئیات مکان به‌دست‌آمده نمایش دهد.

این API یک Place شیء برمی‌گرداند. برای بازیابی اسناد از شیء Place، از Place.attributions دارایی استفاده کنید که با هر درخواست برگردانده می‌شود (نیازی نیست آن را با فیلدها مشخص کنید). این دارایی List از String شیء یا null را برمی‌گرداند اگر هیچ اسنادی برای نمایش وجود نداشته باشد. کد مثال زیر نحوه دریافت مکان و فهرست کردن اسناد مالکیت را نشان می‌دهد.

  // Use place ID to create a new Place instance.
  const place = new Place({
      id: 'ChIJB9a4Ifl744kRlpz0BQJzGQ8', // Crazy Good Kitchen
  });

  // Call fetchFields, passing the desired data fields.
  await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location", "reviews"],
  });

  // Check for any place attributions.
  if (!place.attributions) {
      console.log('No attributions were found.');
      return;
  } else {
      // Log the place attribution
      for (var attribution of place.attributions) {
          console.log(attribution);
      }
  }

  

نمایش مرور

شیء Place می‌تواند حداکثر پنج مرور داشته باشد که هر مرور با شیء Review نشان داده می‌شود. می‌توانید این مرورها را به‌صورت اختیاری در برنامه‌تان نمایش دهید.

هنگام نمایش نظراتی که کاربران Google همیاری کرده‌اند، باید نام نویسنده را در نزدیکی قرار دهید. وقتی در فیلد اسناد نویسنده در شیء Review دردسترس باشد، توصیه می‌کنیم عکس نویسنده و پیوند به نمایه او را نیز اضافه کنید. تصویر زیر نمونه‌ای از مرور پارک را نشان می‌دهد:

مثال زیر نشان می‌دهد که چگونه مکان دریافت می‌شود، مرورها بررسی می‌شود، و داده‌های اولین مرور نشان داده می‌شود:

// Create a new Place instance.
const place = new Place({
    id: 'ChIJpyiwa4Zw44kRBQSGWKv4wgA', // Faneuil Hall Marketplace, Boston, MA
});

// Call fetchFields, passing 'reviews' and other needed fields.
await place.fetchFields({
    fields: ['displayName', 'formattedAddress', 'location', 'reviews'],
});

// Create an HTML container.
const content = document.createElement('div');
const title = document.createElement('div');
const rating = document.createElement('div');
const address = document.createElement('div');
const review = document.createElement('div');
const authorLink = document.createElement('a');

// If there are any reviews display the first one.
if (place.reviews && place.reviews.length > 0) {
    // Get info for the first review.
    const reviewRating = place.reviews[0].rating;
    const reviewText = place.reviews[0].text;
    const authorName = place.reviews[0].authorAttribution.displayName;
    const authorUri = place.reviews[0].authorAttribution.uri;

    // Safely populate the HTML.
    title.textContent = place.displayName || '';
    address.textContent = place.formattedAddress || '';
    rating.textContent = `Rating: ${reviewRating} stars`;
    review.textContent = reviewText || '';
    authorLink.textContent = authorName;
    authorLink.href = authorUri || '';
    authorLink.target = '_blank';

    content.appendChild(title);
    content.appendChild(address);
    content.appendChild(rating);
    content.appendChild(review);
    content.appendChild(authorLink);
} else {
    content.textContent = `No reviews were found for ${place.displayName}.`;
}

// Create an infoWindow to display the review.
infoWindow = new InfoWindow({
    content,
    ariaLabel: place.displayName,
});
index.js

اسناد مربوط به مرورهای مکان را ببینید.

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

اگر برنامه شما عکس نمایش می‌دهد، باید نام نویسنده هر عکسی را که نویسنده دارد ذکر کنید. جزئیات مربوط به عکس در Place شیء پاسخ در آرایه photos قرار دارد. برای افزودن آرایه photos به پاسخ، فیلد داده photos را در درخواست بگنجانید.

هر عنصر آرایه عکس‌ها نمونه‌ای از Photo است که آرایه authorAttributions از نوع «اسناد نویسنده» را دربرمی‌گیرد. فیلدهای شیء AuthorAttribution رشته‌هایی هستند که حاوی displayName، uri، و photoUri اسناد استناد هستند، یا رشته‌ای خالی درصورتی‌که اسناد استنادی برای نمایش وجود نداشته باشد.

مستندات عکس‌های مکان را ببینید.

اسناد نتایج جستجو

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

سرصفحه: درباره این نتایج

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

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

دکمه ۲: تأیید

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

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

در تصویر قبلی، فهرست نشانی در سمت راست همچنان مشمول محدودیت‌های «محتوای Google Maps» است. پس‌از اینکه کاربر نهایی نشانی موردنظرش را انتخاب کرد، آن نشانی صرفاً برای هدف انجام معامله مربوط به آن کاربر نهایی مشمول محدودیت‌های «محتوای Google Maps» نمی‌شود.

خلاصه‌های هوشواره‌ای

وقتی خلاصه با بهره‌گیری از هوش مصنوعی را در برنامه‌تان نمایش می‌دهید — ازجمله خلاصه مکان، منطقه، و مرور — باید موارد زیر را انجام دهید:

• اسناد استنادی موردنیاز، پیوندهای گزارش‌دهی، و پیوندهای مرجع را همان‌طور که در زیر تعریف شده است نمایش دهید.
• کاربران نهایی باید بتوانند متن خلاصه کامل را همان‌گونه که توسط Google Maps ارائه شده است بخوانند.

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

هنگام نمایش خلاصه هوش مصنوعی از هر نوعی، همیشه نوشتار شفاف‌سازی بومی‌سازی‌شده (ارائه‌شده در فیلد disclosureText بدنه پاسخ) را بلافاصله زیر خلاصه اضافه کنید. هرگز متن شفاف‌سازی ارائه‌شده توسط API را تغییر ندهید یا به آن اضافه نکنید.

الزامات تکمیلی خلاصه مکان و منطقه

مکان و خلاصه‌های منطقه که در برنامه شما نمایش داده می‌شود باید با نوشتار زیر و پیوندهای الزامی همراه باشد:

الزامات خلاصه مرور

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

نمایش راهنمایی برای موارد استفاده خودرو

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

• حداکثر ۳ خط
• ‫۱۲۰ نویسه یا ۲۴ کلمه یا کمتر
• حداقل اندازه جلویی ۲۴dp

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