تراکنش‌های غنی‌شده

نمای کلی

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

وقتی صورت‌حساب‌های تراکنش را به‌صورت مخفف صادر می‌کنید، مثلاً «ACMEHCORP»، ممکن است درک آن برای مشتریانتان دشوار باشد. این امر می‌تواند منجر به هزینه‌های مورد مناقشه و هزینه‌های پشتیبانی اضافی برای شما شود. درعوض، بهتر است نام کامل فروشنده را ارائه دهید، مثلاً Acme Housewares.

«تراکنش‌های غنی‌شده» ارائه اطلاعات تراکنش بصری را برای شما آسان‌تر می‌کند، ازجمله نام کامل فروشنده، دسته کسب‌وکار، تصویر ویترین فروشگاه، و جزئیات تماس و مکان. این کار شفافیت را افزایش می‌دهد، «شاخص خالص مروّجان» (NPS) را بهبود می‌بخشد، و باعث می‌شود زمان بیشتری در برنامه‌تان سپری شود.

فعال کردن میاناهای برنامه‌سازی کاربردی

برای پیاده‌سازی «تراکنش‌های غنی‌شده»، باید APIهای زیر را در کنسول Google Cloud فعال کنید. پیوندهای زیر کنسول Google Cloud را باز می‌کند تا بتوانید هر میانای برنامه‌سازی کاربردی را برای پروژه انتخابی‌تان فعال کنید:

• Places API (New)
• Geocoding API
• Maps JavaScript API، Maps Static API، کیت توسعه نرم‌افزار Google Maps برای Android، یا کیت توسعه نرم‌افزار Google Maps برای iOS

برای اطلاعات بیشتر درباره راه‌اندازی، به شروع به کار با Google Maps Platform مراجعه کنید.

بخش‌های راهنمای پیاده‌سازی

پیاده‌سازی‌ها و سفارشی‌سازی‌های زیر در این راهنما پوشش داده شده است:

روندنمای زیر نشان می‌دهد که برنامه شما چگونه تراکنش‌های فروشنده را مطابقت می‌دهد تا بااستفاده از جزئیات مکان از پایگاه داده موجود فروشندگان یا ازطریق درخواست «جستجوی نوشتار» نتیجه‌ای را برگرداند:

دریافت شناسه‌های مکان «پلاتفرم Google Maps»

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

برای دریافت شناسه مکان برای کسب‌وکار، با نقطه پایانی جستجوی نوشتار (جدید) در Places API (جدید) تماس بگیرید و فقط فیلد places.id را در ماسک فیلد درخواست کنید، که باعث راه‌اندازی SKU ضروریات جستجوی نوشتار (فقط شناسه‌ها) می‌شود. اگر فروشنده چندین مکان دارد، نام شهر یا خیابان را همراه با نام فروشنده در پُرسمان خود اضافه کنید. نتایج برگردانده‌شده را اعتبارسنجی کنید تا مطمئن شوید با فروشنده مطابقت دارند.

مثال زیر شناسه مکان را برای دفتر Google در تایپه بااستفاده از نام فروشنده و شهر درخواست می‌کند:

curl -X POST -d '{
  "textQuery" : "Google Taipei"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

شناسه‌های مکان فروشگاه

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

برای حفظ دقت شناسه‌های مکان ذخیره‌شده، شناسه‌های مکان را هر ۱۲ ماه یک‌بار با ایجاد درخواست جزئیات مکان (جدید) که فقط فیلد id را در ماسک فیلد مشخص می‌کند، بازآوری کنید.

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

می‌توانید جزئیات مکان موردنیاز مشتریان را پس‌از بازدید از مکان فروشنده هم‌رسانی کنید. پس‌از فراخوانی نقطه پایانی «جزئیات مکان (جدید)» در Places API (جدید)، می‌توانید پاسخ را در چارچوب محدودیت‌های «شرایط خدمات Google Maps Platform» در پنجره اطلاعات، نوار کناری وب، یا نمای جزئیات تلفن همراه فیلتر و ارائه کنید.

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

درخواست «جزئیات جا (جدید)» زیر نام نمایشی، نشانی قالب‌بندی‌شده، مختصات، وب‌سایت، شماره تلفن، نماد، ساعت کاری، و رده‌بندی را در قالب JSON برای شناسه جای Google Taipei 101 برمی‌گرداند:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: displayName,formattedAddress,location,websiteUri,nationalPhoneNumber,iconMaskBaseUri,regularOpeningHours,rating' \
'https://places.googleapis.com/v1/places/ChIJraeA2rarQjQRyAqIxkx2vN8'

اگر درحال ساختن برنامه وب با Maps JavaScript API هستید، می‌توانید از کلاس Place نیز برای واکشی همان فیلدها در کارخواه استفاده کنید:

const place = new google.maps.places.Place({
  id: "ChIJraeA2rarQjQRyAqIxkx2vN8",
});

await place.fetchFields({
  fields: [
    "displayName",
    "formattedAddress",
    "location",
    "websiteURI",
    "nationalPhoneNumber",
    "regularOpeningHours",
    "rating",
  ],
});

مکان فروشنده را تعیین کنید

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

مثال زیر از Geocoding API برای دریافت عرض جغرافیایی و طول جغرافیایی شناسه مکان دفتر Google در تایپه استفاده می‌کند:

```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY
```

افزودن نشانگر پیشرفته در نقشه وب

چون مشتریان نقشه را برای تأیید تراکنش‌ها مشاهده می‌کنند و نه برای مرور یا پیمایش، نقشه‌تان را با تعامل محدود پیکربندی کنید و یک نشانگر پیشرفته در مکان فروشنده قرار دهید. نشانگرهای پیشرفته به شناسه نقشه و کتابخانه marker (libraries=marker) نیاز دارند.

ابتدا، Maps JavaScript API را با libraries=marker بار کنید و یک محفظه div برای نقشه اضافه کنید:

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=marker&callback=initMap"></script>
<div id="map" style="height: 300px; width: 100%;"></div>

سپس، نقشه را با gestureHandling: "none" و zoomControl: false مقداردهی اولیه کنید تا تعامل‌پذیری را محدود کنید، mapId خود را ارائه دهید، و google.maps.marker.AdvancedMarkerElement را در مختصات فروشنده ایجاد کنید:

function initMap() {
  const merchantLocation = { lat: 25.033976, lng: 121.5645389 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: merchantLocation,
    zoom: 16,
    mapId: "DEMO_MAP_ID",
    gestureHandling: "none",
    zoomControl: false,
  });

  new google.maps.marker.AdvancedMarkerElement({
    map,
    position: merchantLocation,
    title: "Google Taipei",
  });
}

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

افزودن تصویر نقشه ثابت

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

درخواست زیر نقشه راهی با اندازه ۶۴۰x۴۸۰ پیکسل برمی‌گرداند که مرکز آن روی نشانگر قرمز در دفتر Google تایپه با سبک نقشه بااستفاده از فضای ابری قرار دارد:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:red%7C25.033976%2C121.5645389&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

جدول زیر هر بخش از درخواست را شرح می‌دهد:

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

همچنین می‌توانید نشانی را به‌عنوان مکان نشانگر ارسال کنید:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:green%7CTaipei%20101%20Tower%2CNo.%207信義路五段信義區台北市%20Taiwan%20110&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

برای گزینه‌های پارامتر بیشتر، اسناد Maps Static API را ببینید.

افزودن نقشه به برنامه تلفن همراه

اگر از «کیت توسعه نرم‌افزار Maps برای Android» یا «کیت توسعه نرم‌افزار Maps برای iOS» استفاده می‌کنید، می‌توانید بااستفاده از مختصات جزئیات مکان، نشانگر پیشرفته‌ای قرار دهید.

ازآنجایی‌که مشتریان نقشه را برای تأیید تراکنش‌ها مشاهده می‌کنند، نه برای مرور یا پیمایش، نقشه‌ای با تعامل محدود پیکربندی کنید:

• برای برنامه‌های Android، به نشانگرهای پیشرفته برای Android و افزودن نقشه با نشانگر مراجعه کنید، و حالت Lite را برای ارائه تعامل محدود فعال کنید.
• برای برنامه‌های iOS، نشانگرهای پیشرفته برای iOS و افزودن نقشه با نشانگر، و غیرفعال کردن کنترل‌ها و اشاره‌ها با کلاس GMSUISettings را ببینید.