نظرة عامة
تتوفّر "منصة خرائط Google" للويب (JS وTS) وAndroid وiOS، وتوفّر أيضًا واجهات برمجة تطبيقات لخدمات الويب تتيح لك الحصول على معلومات حول الأماكن والاتجاهات والمسافات. النماذج الواردة في هذا الدليل مكتوبة لمنصة واحدة، ولكن يتم توفير روابط مستندات للتنفيذ على منصات أخرى.
غالبًا ما يصعب على المستخدمين فهم بيانات المعاملات، وذلك باستخدام اختصارات مثل "ACMEHCORP" بدلاً من أسماء التجّار مثل "Acme Houseware"، مما قد يؤدي إلى زيادة مكالمات دعم العملاء وإجراء نزاعات مكلفة. تعمل ميزة "المعاملات المفصّلة" على تبسيط هذه المعاملات وتسهيلها من خلال توفير الاسم الكامل للتاجر وفئة النشاط التجاري وصورة لواجهة المتجر وعنوانه وموقعه الجغرافي على الخريطة ومعلومات الاتصال الكاملة والمزيد. ويساعد ذلك على زيادة رضا المستخدمين وشفافية التطبيق، كما يمكنهم تقليل مكالمات دعم العملاء وزيادة صافي عدد المروِّجين (NPS) وتوفير المزيد من الوقت داخل التطبيق.
ننصح باستخدام "المعاملات المفصّلة"، بما في ذلك دليل التنفيذ ونصائح التخصيص التي نقدّمها في هذا الموضوع، باعتبارها مزيجًا مثاليًا من واجهات برمجة التطبيقات في "منصة خرائط Google" لإنشاء تجارب رائعة للمستخدمين في سجلّ المعاملات. سيشرح لك دليل التنفيذ هذا كيفية مطابقة موقع جغرافي مع تاجر معيّن وعرض معلوماته التفصيلية.
تمكين واجهات برمجة التطبيقات
لتنفيذ "المعاملات المفصّلة"، يجب تفعيل واجهات برمجة التطبيقات التالية في Google Cloud Console. ترسلك الروابط التشعبية التالية إلى Google Cloud Console لتفعيل كل واجهة برمجة تطبيقات لمشروعك المحدد:
- Places API:
- Geocoding API:
- Maps Static API أو حزمة تطوير البرامج بالاستناد إلى "خرائط Google" لنظام التشغيل Android أو حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل iOS.
أقسام دليل التنفيذ
في ما يلي بعض عمليات التنفيذ والتخصيص التي سنتناولها في هذا الموضوع.
- يُعدّ رمز علامة الاختيار خطوة تنفيذ أساسية.
- إنّ رمز النجمة هو إجراء اختياري لكنّنا ننصح به لتحسين الحلّ.
| مطابقة التجّار مع "منصة خرائط Google" | ربط تاجر في سجلّ المعاملات بمكان في "منصة خرائط Google". | |
| عرض تفاصيل التاجر | يعرض المعاملات التي تتضمن بيانات وافية وتعرض معلومات مفيدة عن التاجر ليتمكّن المستخدمون من التعرّف على المعاملة بسرعة. | |
| إضافة خريطة للموقع الجغرافي للتاجر | أضِف خريطة للموقع الجغرافي للتاجر. |
مطابقة التجّار مع "منصة خرائط Google"
| يستخدم هذا المثال: Places API |
يوضح المخطّط البياني التالي كيفية مطابقة تطبيقك لمعاملات التاجر لعرض نتيجة باستخدام تفاصيل المكان من قاعدة بيانات حالية للتجّار أو من خلال طلب "بحث عن الأماكن":
الحصول على أرقام تعريف الأماكن في "منصة خرائط Google"
قد تكون لديك قاعدة بيانات للتجّار تحتوي على معلومات أساسية مثل اسم النشاط التجاري وعنوانه. للحصول على المعلومات التي تمتلكها "منصة خرائط Google" حول هذا المكان، بما في ذلك معلومات الاتصال والمعلومات التي يساهم بها المستخدم، ستحتاج إلى رقم تعريف المكان في "منصة خرائط Google" الذي يتوافق مع كل من التجار في قاعدة بياناتك.
للحصول على معرّف المكان الخاص بأحد الأنشطة التجارية، يمكنك تقديم طلب إلى نقطة النهاية
/findplacefromtext في واجهة Places API وطلب إرسال فاتورة إلى الحقل place_id فقط من خلال طلب البحث عن مكان - معرّف فقط بدون رسوم. إذا كان للتاجر عدة مواقع جغرافية، استخدِم اسم التاجر مع اسم المدينة أو الشارع. ستختلف جودة البيانات التي يعرضها المكالمة، لذا عليك التحقق مما إذا كانت النتائج المعروضة تتطابق فعليًا مع التاجر المطلوب.
في ما يلي مثال على طلب معرّف المكان لمكتب Google في تايبيه باستخدام اسم التاجر والمدينة:
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" عن التاجر بهدف تلقّي طلبات مستقبلية، يمكنك تخزين معرّف المكان هذا إلى أجل غير مسمى في قاعدة بياناتك كسمة لسجلّ التاجر. ما عليك سوى تقديم طلب "العثور على مكان" مرة واحدة فقط لكل تاجر. يمكنك أيضًا البحث عن معرّف المكان في كل مرة يطلب فيها أحد المستخدمين تفاصيل المعاملة.
لضمان حصولك على المعلومات الأكثر دقة دائمًا، عليك إعادة تحميل أرقام تعريف الأماكن كل 12 شهرًا باستخدام طلب تفاصيل المكان بالمَعلمة place_id.
في حال عدم تطابق تفاصيل المكان التي تعرضها مع التاجر الذي أجرى المعاملة، ننصحك بالسماح للمستخدمين بتقديم ملاحظات حول جودة مطابقة التاجر.
عرض تفاصيل التاجر
| يستخدم هذا المثال: Places API | متوفّر أيضًا: حزمة تطوير برامج الأماكن لنظام التشغيل Android | حزمة تطوير برامج الأماكن لأجهزة iOS | مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط |
يمكنك مشاركة تفاصيل المكان التي يحتاج المستخدمون إلى معرفتها بعد زيارة أحد مواقعك. بفضل تفاصيل المكان الغنية بصريًا، مثل معلومات الاتصال وساعات العمل وتقييمات المستخدمين وصور المستخدمين، يمكن لتطبيقك تذكير المستخدمين بإتمام المعاملة. بعد إجراء استدعاء لواجهة برمجة تطبيقات الأماكن للحصول على تفاصيل المكان، يمكنك تصفية الرد وعرضه في نافذة معلومات أو شريط جانبي على الويب أو بأي طريقة أخرى تريدها.
لطلب تفاصيل المكان، ستحتاج إلى رقم تعريف كل موقع من مواقعك الجغرافية. راجع الحصول على أرقام تعريف الأماكن لاسترداد رقم تعريف المكان لموقعك.
يعرض طلب "تفاصيل المكان" التالي العنوان والإحداثيات والموقع الإلكتروني
ورقم الهاتف والتقييم والساعات في ناتج json لمعرّف مكان Google تايبيه 101:
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 | واجهة برمجة التطبيقات الثابتة للخرائط | متوفّر أيضًا: Android | iOS |
تحديد الموقع الجغرافي للتاجر
تقبل واجهة برمجة التطبيقات الثابتة للخرائط عنوانًا أو إحداثيات لوضع علامة. إذا كان سجل التاجر الخاص بك يتضمن عنوانًا، يمكنك التخطي للأمام إلى القسم التالي، ولكننا ننصح باستخدام الإحداثيات فوق العناوين لدقة الخريطة.
إذا كانت قاعدة بيانات التاجر تحتوي على عناوين الشوارع ولكن لا تحتوي على إحداثيات جغرافية ولم تكن قد تطلب تفاصيل عن الأماكن بالفعل، يمكنك استخدام واجهة برمجة تطبيقات Geocoding API لتحويل عناوين الشوارع إلى إحداثيات خطوط الطول/العرض على جانب الخادم، وإحداثيات المتاجر في قاعدة البيانات، وتحديث الإحداثيات مرة واحدة على الأقل كل 30 يومًا.
في ما يلي مثال على استخدام واجهة برمجة التطبيقات Geocoding API للحصول على خط العرض وخط الطول لرقم تعريف مكان مكتب Google في تايبيه:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY&solution_channel=GMP_guides_enrichedtransactions_v1_a
إضافة محدّد موقع جغرافي للتاجر إلى خريطة
نظرًا لأن المستخدمين سيرون الخريطة لتأكيد المعاملات بدلاً من التصفح أو التنقل، فأنت تريد إنشاء خريطة ذات تفاعل محدود.
بالنسبة إلى خدمات الويب على أجهزة الكمبيوتر المكتبي والويب على الأجهزة الجوّالة، أنشِئ عنوان URL ثابت لواجهة برمجة التطبيقات في "خرائط Google" مع علامة واحدة على خط العرض/الطول أو العنوان الخاص بالتاجر. يمكنك استخدام واجهة برمجة التطبيقات Maps Static API من خلال استدعاء خدمة ويب، والذي سينشئ نسخة صورة من الخريطة وفقًا للمعلمات التي تحدّدها. بالنسبة إلى الأجهزة الجوّالة، انتقل إلى الخطوة التالية إضافة خريطة إلى قسم تطبيق الأجهزة الجوّالة.
توضح المكالمة التالية خارطة طريق بحجم 640 × 480 بكسل، موضوعة في منتصف علامة في مكتب Google في تايبيه على مستوى التكبير التلقائي. وتحدد أيضًا علامة موقع التسليم باللون الأحمر ونمط الخريطة المستند إلى السحابة:
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? |
| حجم الصورة | الحجم=640 × 480 |
| علامات الموقع الجغرافي للتاجر (باستخدام ترميز عنوان URL) | markers=color:red%7C25.033976%2C121.5645389 |
| نمط الخريطة المستنِدة إلى السحابة الإلكترونية | map_id=b224095f76859890 |
| مفتاح واجهة برمجة التطبيقات | key=YOUR_API_KEY |
| التوقيع الرقمي (التعرّف على كيفية توقيع طلبك رقميًا) | التوقيع=BASE64_SIGNATURE |
| مَعلمة قناة الحل (اطّلِع على مستندات المَعلمات) | solution_channel=GMP_guides_enrichedtransactions_v1_a |
ستصبح هذه الصورة كما هو موضح أدناه:
يمكنك أيضًا استخدام عنوان كموقع محدِّد الموقع:
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
للحصول على خيارات إضافية للمعلَمات، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات الثابتة للخرائط.
إضافة خريطة على تطبيق الأجهزة الجوّالة
إذا كنت تستخدم حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android أو حزمة تطوير البرامج لخرائط Google لنظام التشغيل iOS، يمكنك وضع علامة باستخدام الإحداثيات من المعلومات الواردة في تفاصيل المكان.
نظرًا لأن المستخدمين سيرون الخريطة لتأكيد المعاملات بدلاً من التصفح أو التنقل، اختر خريطة ذات تفاعل محدود:
- بالنسبة إلى تطبيقات Android، يمكنك الاطّلاع على البرنامج التعليمي لإضافة خريطة باستخدام محدِّد الموقع، وتفعيل الوضع البسيط لتوفير تفاعل محدود.
- بالنسبة إلى تطبيقات iOS، يمكنك الاطّلاع على دليل تعليمي لإضافة خريطة باستخدام محدِّد الموقع، وإيقاف عناصر التحكّم والإيماءات باستخدام العلامة
GMSUiSettings.