شرح تفصيلي للعمليات

نظرة عامة

استخدِم هذا الدليل للتعرّف على كيفية مطابقة موقع جغرافي مع تاجر معيّن وعرض معلومات مفصّلة عن التاجر.

عند إصدار كشوفات معاملات مختصرة مثل "ACMEHCORP"، قد يصعب على عملائك فهمها. وقد يؤدي ذلك إلى اعتراضات على الرسوم وتكاليف دعم إضافية بالنسبة إليك. بدلاً من ذلك، من الأفضل تقديم اسم التاجر الكامل، مثل "أدوات منزلية من Acme".

تسهّل عليك ميزة "المعاملات المحسّنة" تقديم معلومات بديهية عن المعاملات، بما في ذلك الاسم الكامل للتاجر وفئة النشاط التجاري وصورة واجهة المحل وتفاصيل الاتصال والموقع الجغرافي. يؤدي ذلك إلى زيادة الشفافية وتحسين صافي عدد المروِّجين (NPS) وقضاء المزيد من الوقت في تطبيقك.

نموذج لشاشات على الأجهزة الجوّالة تقارن بين كشوفات المعاملات الأولية وتفاصيل التاجر المحسّنة
نماذج شاشات للمعاملات المحسّنة (انقر للتكبير)

تفعيل واجهات برمجة التطبيقات

لتنفيذ ميزة "المعاملات المحسّنة"، يجب تفعيل واجهات برمجة التطبيقات التالية في وحدة تحكّم Google Cloud. تفتح الروابط التالية وحدة تحكّم Google Cloud لتتمكّن من تفعيل كل واجهة برمجة تطبيقات لمشروعك المحدّد:

لمزيد من المعلومات حول الإعداد، يُرجى الاطّلاع على مقالة بدء استخدام "منصة خرائط Google".

أقسام دليل الاستخدام

يتناول هذا الدليل عمليات التنفيذ والتخصيص التالية:

مطابقة التجّار باستخدام "منصة خرائط Google" ربط تاجر في سجلّ المعاملات بمكان في "منصة خرائط Google"
عرض تفاصيل التاجر اعرض معاملات غنية بالبيانات مع معلومات مفيدة عن التاجر لكي يتمكّن العملاء من التعرّف على المعاملة بسرعة.
إضافة خريطة للموقع الجغرافي للتاجر أضِف خريطة لموقع التاجر الجغرافي باستخدام علامة متقدّمة.

مطابقة التجّار باستخدام "منصة خرائط Google"

يستخدم هذا المثال: Places API (جديدة) تتوفّر أيضًا: JavaScript

يوضّح المخطّط الانسيابي التالي كيفية مطابقة تطبيقك لمعاملات التجّار لعرض نتيجة باستخدام تفاصيل المكان من قاعدة بيانات حالية للتجّار أو من خلال طلب "بحث نصي":

مخطط انسيابي لمطابقة سجلّات معاملات التاجر مع أرقام تعريف الأماكن وتفاصيل الأماكن
مصفوفة مسار مطابقة التجّار (انقر للتكبير)

الحصول على أرقام تعريف الأماكن في "منصة خرائط Google"

قد يكون لديك قاعدة بيانات للتجار تحتوي على معلومات أساسية مثل اسم النشاط التجاري وعنوانه. للحصول على المعلومات التي تتوفّر لدى "منصة خرائط Google" عن هذا المكان، بما في ذلك تفاصيل الاتصال والتقييمات التي يساهم بها العملاء، ابحث عن رقم تعريف المكان الذي يتوافق مع كل تاجر في قاعدة بياناتك.

للحصول على رقم تعريف مكان لمؤسسة، يمكنك إجراء طلب إلى نقطة نهاية البحث النصي (الجديد) في Places API (الجديد) وطلب حقل places.id فقط في قناع الحقل، ما يؤدي إلى تفعيل رمز التخزين التعريفي Text Search Essentials (IDs Only). إذا كان لدى التاجر مواقع جغرافية متعددة، يُرجى تضمين اسم المدينة أو الشارع مع اسم التاجر في طلب البحث. تحقَّق من النتائج التي تم عرضها للتأكّد من أنّها تتطابق مع التاجر.

يطلب المثال التالي رقم تعريف المكان لمكتب 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" عن التاجر لطلبات مستقبلية، يمكنك تخزين رقم تعريف المكان إلى أجل غير مسمى في قاعدة بياناتك كسمة لسجلّ التاجر. عليك تنفيذ طلب "البحث النصي (الجديد)" مرة واحدة فقط لكل تاجر، أو يمكنك البحث عن رقم تعريف المكان عندما يطلب العميل تفاصيل المعاملة.

للحفاظ على دقة أرقام تعريف الأماكن المخزَّنة، حدِّث أرقام تعريف الأماكن كل 12 شهرًا من خلال تقديم طلب تفاصيل المكان (جديد) يحدِّد الحقل id فقط في قناع الحقل.

إذا كانت تفاصيل المكان التي تعرضها لا تتطابق مع التاجر الذي أكمل العميل المعاملة معه، تنصح Google بالسماح للعملاء بإرسال ملاحظات حول جودة مطابقة التاجر.

عرض تفاصيل التاجر

يستخدم هذا المثال: Places API (جديدة) تتوفّر أيضًا: حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل Android | حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل iOS | مكتبة الأماكن، Maps JavaScript API

يمكنك مشاركة تفاصيل المكان التي يحتاجها العملاء بعد زيارة موقع جغرافي لتاجر. بعد استدعاء نقطة نهاية تفاصيل المكان (الجديدة) في Places API (الجديدة)، يمكنك فلترة الاستجابة وعرضها في نافذة معلومات أو شريط جانبي على الويب أو عرض تفصيلي على الأجهزة الجوّالة ضمن حدود بنود خدمة "منصة خرائط Google".

عرض تفصيلي لمعاملة على جهاز جوّال يعرض اسم التاجر وعنوانه وخريطة وتفاصيل الاتصال
نموذج لشاشة تفاصيل التاجر (انقر للتكبير)

لإصدار طلب إلى نقطة نهاية "تفاصيل المكان"، تحتاج إلى رقم تعريف المكان لكل موقع جغرافي. يمكنك الاطّلاع على الحصول على أرقام تعريف الأماكن في "منصة خرائط Google" لاسترداد رقم تعريف المكان الخاص بالموقع الجغرافي للتاجر.

يعرض طلب "تفاصيل المكان (الجديد)" التالي الاسم المعروض والعنوان المنسَّق والإحداثيات والموقع الإلكتروني ورقم الهاتف والرمز وساعات العمل والتقييم بتنسيق 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",
  ],
});

إضافة خريطة لموقع التاجر الجغرافي

يستخدم هذا المثال: Maps JavaScript API | Geocoding API | Maps Static API تتوفّر أيضًا على: Android | iOS

تحديد الموقع الجغرافي للتاجر

يمكنك وضع علامة على خريطة باستخدام الإحداثيات الجغرافية من تفاصيل المكان. إذا كانت قاعدة بيانات التجّار لديك تحتوي على عناوين شوارع بدون إحداثيات جغرافية ولم تكن تطلب تفاصيل المكان، يمكنك استخدام Geocoding API لتحويل عناوين الشوارع إلى إحداثيات خطوط العرض والطول على جهة الخادم، وتخزين هذه الإحداثيات في قاعدة بياناتك، وإعادة تحميلها مرة واحدة على الأقل كل 30 يومًا.

يستخدم المثال التالي 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",
  });
}

يمكنك أيضًا تخصيص العلامات المتقدّمة من خلال تغيير لون خلفية الدبوس أو حدوده أو رموزه، أو من خلال تقديم صورة رسومية مخصّصة لفئة التاجر.

إضافة صورة خريطة ثابتة

إذا كنت تفضّل صورة خريطة غير تفاعلية للويب على أجهزة الكمبيوتر المكتبي أو الويب على الأجهزة الجوّالة، يمكنك إنشاء عنوان URL لواجهة برمجة التطبيقات Maps Static API يتضمّن علامة واحدة عند إحداثيات خطوط العرض والطول أو عنوان التاجر. تعرض Maps Static API نسخة من الخريطة على شكل صورة باستخدام المَعلمات التي تحدّدها.

يعرض الطلب التالي خريطة طريق بحجم 640×480 بكسل، تتوسّطها علامة حمراء في مكتب 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
```

يوضّح الجدول التالي كل قسم من أقسام الطلب:

عنوان URL لواجهة برمجة التطبيقات https://maps.googleapis.com/maps/api/staticmap?
حجم الصورة size=640x480
علامات موقع التاجر (باستخدام ترميز عنوان URL) markers=color:red%7C25.033976%2C121.5645389
نمط الخريطة المستند إلى السحابة الإلكترونية map_id=b224095f76859890
مفتاح واجهة برمجة التطبيقات key=YOUR_API_KEY
التوقيع الرقمي (تعرَّف على كيفية توقيع طلبك رقميًا) signature=BASE64_SIGNATURE

ينتج عن الطلب صورة الخريطة الثابتة التالية:

خريطة تتوسّطها علامة موقع حمراء لمكتب Google في تايبيه

يمكنك أيضًا تمرير عنوان كموقع العلامة:

```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.

إضافة خريطة إلى تطبيقك المتوافق مع الأجهزة الجوّالة

إذا كنت تستخدم حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android أو حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS، يمكنك وضع علامة متقدّمة باستخدام الإحداثيات من تفاصيل المكان.

بما أنّ العملاء يطّلعون على الخريطة لتأكيد المعاملات بدلاً من التصفّح أو التنقّل، يمكنك ضبط خريطة ذات تفاعل محدود: