نظرة عامة
تتوفّر "منصة خرائط Google" على الويب (JS وTS) وAndroid وiOS، كما توفّر واجهات برمجة تطبيقات لخدمات الويب للحصول على معلومات حول الأماكن والاتجاهات والمسافات. تمت كتابة النماذج في هذا الدليل لمنصة واحدة، ولكن يتم توفير روابط المستندات لتنفيذها على منصات أخرى.
غالبًا ما يصعب على المستخدمين فهم كشوفات المعاملات، إذ تستخدم اختصارات مثل "ACMEHCORP" بدلاً من أسماء التجّار مثل "أدوات منزلية من Acme"، ما قد يؤدي إلى زيادة عدد مكالمات دعم العملاء والنزاعات المكلفة. تسهّل هذه الميزة المعاملات وتجعلها أكثر وضوحًا من خلال توفير الاسم الكامل للتاجر وفئة النشاط التجاري وصورة لواجهة المتجر وعنوانه وموقعه الجغرافي على الخريطة ومعلومات الاتصال الكاملة والمزيد. يساعد ذلك في زيادة رضا المستخدمين والشفافية، ويمكن أن يؤدي أيضًا إلى تقليل عدد مكالمات الدعم التي يتلقّاها فريق خدمة العملاء، وزيادة صافي نقاط الترويج، وتشجيع المستخدمين على قضاء المزيد من الوقت داخل التطبيق.
إنّ "المعاملات المحسّنة"، أي دليل التنفيذ ونصائح التخصيص التي نقدّمها في هذا الموضوع، هي ما ننصح به كأفضل مجموعة من واجهات برمجة التطبيقات في "منصة خرائط Google" لإنشاء تجارب رائعة للمستخدمين في ما يتعلّق بسجلّ المعاملات. سيوضّح لك دليل التنفيذ هذا كيفية مطابقة موقع جغرافي مع تاجر معيّن وعرض معلوماته التفصيلية.
تفعيل واجهات برمجة التطبيقات
لتنفيذ ميزة "المعاملات المحسّنة"، يجب تفعيل واجهات برمجة التطبيقات التالية في Google Cloud Console. تنقلك الروابط التشعبية التالية إلى وحدة تحكّم Google Cloud لتفعيل كل واجهة برمجة تطبيقات للمشروع الذي اخترته:
- Places API
- Geocoding API
- Maps Static API أو حزمة تطوير البرامج (SDK) لخدمة "خرائط Google" لنظام التشغيل Android أو حزمة تطوير البرامج (SDK) لخدمة "خرائط Google" لنظام التشغيل iOS
أقسام دليل التنفيذ
في ما يلي عمليات التنفيذ والتخصيص التي يتم تناولها هنا:
- يُعدّ رمز علامة الاختيار خطوة أساسية في عملية التنفيذ.
- رمز النجمة هو تخصيص اختياري ولكن يُنصح به لتحسين الحلّ.
| مطابقة التجّار مع "منصة خرائط Google" | ربط تاجر في سجلّ المعاملات بمكان في "منصة خرائط Google" | |
| عرض تفاصيل التاجر | عرض معاملات غنية بالبيانات تعرض معلومات مفيدة عن التاجر، ما يتيح للمستخدمين التعرّف على المعاملة بسرعة | |
| إضافة خريطة لموقع التاجر | أضِف خريطة للموقع الجغرافي للتاجر. |
مطابقة التجّار مع "منصة خرائط Google"
| يستخدم هذا المثال: Places API |
يوضّح المخطّط التالي كيف يطابق تطبيقك معاملات التاجر لعرض نتيجة باستخدام "تفاصيل المكان" من قاعدة بيانات حالية للتجّار أو من خلال طلب "بحث عن مكان":
الحصول على أرقام تعريف الأماكن في Google Maps Platform
قد يكون لديك قاعدة بيانات للتجّار تتضمّن معلومات أساسية، مثل اسم النشاط التجاري وعنوانه. للحصول على معلومات من "منصة خرائط Google" حول هذا المكان، بما في ذلك معلومات الاتصال والمعلومات التي يقدّمها المستخدمون، عليك الحصول على معرّف المكان على "منصة خرائط Google" الذي يتوافق مع كل تاجر في قاعدة البيانات.
للحصول على رقم تعريف المكان الخاص بمؤسسة، أرسِل طلبًا إلى نقطة النهاية /findplacefromtext في Places API واطلب الحقل place_id فقط لتحصيل رسوم الطلب كطلب البحث عن مكان - المعرّف فقط بدون رسوم. إذا كان التاجر يملك مواقع جغرافية متعددة، استخدِم اسم التاجر مع اسم المدينة أو الشارع. تختلف جودة البيانات التي تعرضها المكالمة، لذا عليك التأكّد مما إذا كانت النتائج المعروضة تطابق التاجر فعلاً.
في ما يلي مثال على طلب رقم تعريف المكان لمكتب Google في تايبيه باستخدام اسم التاجر والمدينة:
```html
https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=google%20taipei&inputtype=textquery&fields=place_id&key=YOUR_API_KEY&solution_channel=GMP_guides_enrichedtransactions_v1_a
```
احرص على ترميز عنوان URL لمَعلمة الإدخال في طلب واجهة برمجة التطبيقات.
أرقام تعريف الأماكن في المتجر
لتخزين معلومات من "منصة خرائط Google" حول التاجر من أجل الطلبات المستقبلية، يمكنك تخزين معرّف المكان هذا إلى أجل غير مسمى في قاعدة البيانات كسمة لسجلّ التاجر. يجب ألا تحتاج إلى إرسال طلب Find Place أكثر من مرة واحدة لكل تاجر. يمكنك أيضًا البحث عن معرّف المكان في كل مرة يطلب فيها المستخدم تفاصيل المعاملة.
لضمان حصولك دائمًا على المعلومات الأكثر دقة، عليك إعادة تحميل معرّفات الأماكن كل 12 شهرًا باستخدام طلب تفاصيل المكان مع المَعلمة place_id.
في حال كانت "تفاصيل المكان" التي تعرضها لا تتطابق مع التاجر الذي أجرى المعاملة، ننصحك بالسماح للمستخدمين بتقديم ملاحظات حول جودة المطابقة مع التاجر.
عرض تفاصيل التاجر
| يستخدم هذا المثال: Places API | تتوفّر أيضًا: حزمة تطوير البرامج (SDK) للأماكن لنظام التشغيل Android | حزمة تطوير البرامج (SDK) للأماكن لنظام التشغيل iOS | مكتبة الأماكن في Maps JavaScript API |
يمكنك مشاركة تفاصيل المكان التي يحتاج المستخدمون إلى معرفتها بعد زيارة أحد مواقعك الجغرافية. باستخدام تفاصيل الأماكن الغنية بالمعلومات، مثل معلومات الاتصال وساعات العمل وتقييمات المستخدمين وصور المستخدمين، يمكن لتطبيقك تذكير المستخدمين بالمعاملات التي أكملوها. بعد إجراء طلب إلى Places API للحصول على تفاصيل المكان، يمكنك فلترة الاستجابة وعرضها في نافذة معلومات أو شريط جانبي على الويب أو بأي طريقة تريدها ضمن حدود بنود الخدمة.
لطلب "تفاصيل المكان"، ستحتاج إلى رقم تعريف المكان لكل موقع من مواقعك الجغرافية. اطّلِع على الحصول على معرّفات الأماكن لاسترداد معرّف المكان الخاص بموقعك الجغرافي.
يعرض طلب "تفاصيل المكان" التالي العنوان والإحداثيات والموقع الإلكتروني ورقم الهاتف والتقييم وساعات العمل في الناتج json لمعرّف المكان الخاص بـ "تايبيه 101" في Google:
```html
https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJraeA2rarQjQRyAqIxkx2vN8&fields=name%2Cformatted_address%2Cwebsite%2Cformatted_phone_number%2Cgeometry/location%2Cicon%2Copening_hours%2Crating&key=YOUR_API_KEY&solution_channel=GMP_guides_enrichedtransactions_v1_a
```
إضافة خريطة لموقع التاجر
| يستخدم هذا المثال: Geocoding API | Maps Static API | يتوفّر أيضًا: Android | iOS |
تحديد الموقع الجغرافي الخاص بالتاجر
تقبل Maps Static API عنوانًا أو إحداثيات لوضع علامة. إذا كان سجل التاجر يتضمّن عنوانًا، يمكنك الانتقال إلى القسم التالي، ولكن ننصحك باستخدام الإحداثيات بدلاً من العناوين لضمان دقة الخريطة.
إذا كانت قاعدة بيانات التاجر تتضمّن عناوين شوارع ولكن ليس إحداثيات جغرافية، ولم تكن تطلب تفاصيل المكان، يمكنك استخدام Geocoding API لتحويل عناوين الشوارع إلى إحداثيات خطوط الطول والعرض من جهة الخادم، وتخزين الإحداثيات في قاعدة البيانات، وتحديث الإحداثيات مرة واحدة على الأقل كل 30 يومًا.
في ما يلي مثال على استخدام Geocoding API للحصول على خطوط الطول والعرض الخاصة برقم تعريف المكان لمكتب Google في تايبيه:
```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY&solution_channel=GMP_guides_enrichedtransactions_v1_a
```
إضافة محدّد موقع جغرافي لموقع التاجر إلى خريطة
بما أنّ المستخدمين سيطّلعون على الخريطة لتأكيد المعاملات بدلاً من تصفّحها أو التنقّل فيها، عليك إنشاء خريطة تتضمّن تفاعلاً محدودًا.
بالنسبة إلى الويب على أجهزة الكمبيوتر والأجهزة الجوّالة، أنشئ عنوان URL لواجهة Maps Static API يتضمّن علامة واحدة عند خط العرض/خط الطول أو العنوان الخاص بالتاجر. يمكنك استخدام واجهة برمجة التطبيقات Maps Static API من خلال طلب خدمة ويب، ما يؤدي إلى إنشاء نسخة مصوّرة من خريطة استنادًا إلى المَعلمات التي تحدّدها. بالنسبة إلى الأجهزة الجوّالة، انتقِل إلى إضافة خريطة على قسم تطبيقك المتوافق مع الأجهزة الجوّالة.
تعرض المكالمة التالية خريطة طريق بحجم 640x480 بكسل، مع تركيز على علامة في مكتب 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&solution_channel=GMP_guides_enrichedtransactions_v1_a
```
تنقسم هذه المكالمة إلى الأقسام التالية:
| عنوان 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 |
| مَعلمة قناة الحلول (راجِع مستندات المَعلمة) | solution_channel=GMP_guides_enrichedtransactions_v1_a |
تصبح هذه النتيجة هي الصورة كما هو موضّح أدناه:
يمكنك أيضًا استخدام عنوان كموقع جغرافي للعلامة:
```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&solution_channel=GMP_guides_enrichedtransactions_v1_a
```
للاطّلاع على خيارات إضافية للمعلمات، يُرجى الرجوع إلى مستندات Maps Static API.
إضافة خريطة على تطبيقك للأجهزة الجوّالة
إذا كنت تستخدم حزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل Android أو حزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل iOS، يمكنك وضع علامة باستخدام الإحداثيات من المعلومات الواردة في تفاصيل المكان.
بما أنّ المستخدمين سيطّلعون على الخريطة لتأكيد المعاملات بدلاً من تصفّحها أو التنقّل فيها، اختَر خريطة تتضمّن تفاعلاً محدودًا:
- بالنسبة إلى تطبيقات Android، يمكنك الاطّلاع على البرنامج التعليمي حول إضافة خريطة تتضمّن علامة، وتفعيل الوضع الخفيف لتوفير تفاعل محدود.
- بالنسبة إلى تطبيقات iOS، يُرجى الاطّلاع على البرنامج التعليمي حول إضافة خريطة بعلامة،
وإيقاف عناصر التحكّم والإيماءات
باستخدام العلامة
GMSUiSettings.