دليل تنفيذ الدفع

نظرة عامة

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

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

إنشاء المشروع الآن

تتيح لك أداة الإنشاء السريع في Google Cloud Console إمكانية إنشاء الإكمال التلقائي لنموذج العناوين باستخدام واجهة مستخدم تفاعلية تنشئ رمز JavaScript لك.

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

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

يقدّم هذا الموضوع إرشادات تنفيذية لمساعدة عملائك في تسريع عملية الدفع من خلال إدخال العنوان بشكل توقّعي.

يوضح الرسم البياني التالي واجهات برمجة التطبيقات الأساسية المستخدمة في تنفيذ Checkout (انقر للتكبير).

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

لاستخدام خدمة "الدفع"، يجب تفعيل واجهات برمجة التطبيقات التالية في Google Cloud Console:

• واجهة برمجة تطبيقات JavaScript للخرائط
• واجهة برمجة تطبيقات الأماكن
• واجهة برمجة التطبيقات الثابتة في "خرائط Google"

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

أقسام الممارسات

في ما يلي النصائح والتخصيصات التي سنتناولها في هذا الموضوع.

• يُعدّ رمز علامة الاختيار من الممارسات الأساسية.
• إنّ رمز النجمة هو إجراء اختياري ولكنّنا ننصح به من أجل تحسين الحلّ.

	إضافة ميزة الإكمال التلقائي إلى حقول الإدخال	الملء التلقائي لنموذج عنوان يمكنك إضافة وظيفة "الكتابة أثناء التنقّل" لتحسين تجربة المستخدم على جميع الأنظمة الأساسية وتحسين دقة العناوين من خلال الحد الأدنى من ضغطات المفاتيح.
	تقديم تأكيد مرئي من خلال Maps Static API	اعثر على إحداثيات خط العرض/خط الطول لعنوان معيّن (الترميز الجغرافي)، أو حوِّل إحداثيات خطوط الطول والعرض لموقع جغرافي إلى عنوان (الترميز الجغرافي العكسي).
	نصائح لتحسين عملية الدفع بشكل أكبر	يمكنك استخدام الميزات المتقدّمة لميزة "الإكمال التلقائي" في ميزة "الإكمال التلقائي" لتحسين تجربة الدفع.

ملاحظة: لتتبُّع استخدام نماذج الرموز البرمجية للحلول وتحسين جودة الحلول، يُضمِّن Google مَعلمة طلب البحث solution_channel في طلبات البيانات من واجهة برمجة التطبيقات في نموذج الرمز المتوفّر في هذه الصفحة. لإيقاف هذه الميزة، احذف مَعلمة طلب البحث solution_channel من نموذج الرمز. اطّلِع على مَعلمة حلول "منصة خرائط Google" للحصول على مزيد من المعلومات.

إضافة الإكمال التلقائي إلى حقول الإدخال

يستخدم هذا المثال: مكتبة الأماكن وواجهة برمجة تطبيقات JavaScript للخرائط

يتوفّر أيضًا: Android | iOS

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

من خلال دمج ميزة "الإكمال التلقائي" لـ "المكان" في سلة التسوّق على الإنترنت، يمكنك:

• الحدّ من أخطاء إدخال العناوين
• تقليل عدد الخطوات في عملية الدفع
• بسِّط تجربة إدخال العنوان على الأجهزة الجوّالة أو الأجهزة القابلة للارتداء.
• قلِّل ضغطات المفاتيح بشكل كبير وإجمالي الوقت الذي يحتاجه العميل لتقديم طلب.

عندما يختار المستخدم مربّع إدخال الإكمال التلقائي ويبدأ في الكتابة، تظهر قائمة بعبارات بحث عبارات البحث المقترحة:

عندما يختار المستخدم عنوانًا من قائمة عبارات البحث المقترحة، يمكنك استخدام الردّ لإثبات صحة العنوان والحصول على الموقع الجغرافي. يمكن عندئذٍ لتطبيقك ملء الحقول الصحيحة من نموذج إدخال العنوان:

الفيديوهات: تحسين نماذج العناوين باستخدام ميزة الإكمال التلقائي للأماكن:

نماذج العناوين

الويب

Android

iOS

الخطوات الأولى لاستخدام ميزة الإكمال التلقائي في المكان

لا يتطلب الأمر سوى سطرين من رمز JavaScript لدمج مكان Autcomplete في موقعك الإلكتروني.

تتمثل أسهل طريقة في تضمين واجهة برمجة تطبيقات JavaScript للخرائط (حتى إذا كنت لا تعرض خريطة) في موقعك الإلكتروني وتحديد مكتبة الأماكن كما هو موضّح في المثال التالي، والتي تنفّذ أيضًا وظيفة الإعداد.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initAutocomplete&solution_channel=GMP_guides_checkout_v1_a">
</script>

بعد ذلك، أضف مربع نص إلى صفحتك لإدخال المستخدم:

<input id="autocomplete" placeholder="Enter your address"></input>

أخيرًا، قم بتهيئة خدمة الإكمال التلقائي وربطها بمربع النص المسمى:

function initAutocomplete() {
  // Create the autocomplete object, restricting the search predictions to
  // addresses in the US and Canada.
  autocomplete = new google.maps.places.Autocomplete(address1Field, {
    componentRestrictions: { country: ["us", "ca"] },
    fields: ["address_components", "geometry"],
    types: ["address"],
  });
  address1Field.focus();
  // When the user selects an address from the drop-down, populate the
  // address fields in the form.
  autocomplete.addListener("place_changed", fillInAddress);
}

في المثال السابق، يتم تشغيل أداة معالجة الحدث place_changed عندما يختار المستخدم عبارة بحث مقترحة ويتم تنفيذ دالة fillInAddress. تستخدم الدالة، كما هو موضّح في المثال التالي، الإجابة المحدّدة وتستخرج عناصر العنوان لعرضها بشكل مرئي داخل نموذج.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}
index.ts

ملاحظة: يمكنك قراءة الدليل عن استخدام TypeScript و"خرائط Google".

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;
index.js

بعد حصولك على هذه البيانات، يمكنك استخدامها كعنوان مطابق للمستخدم. ومن خلال بضعة أسطر من الرموز، يمكنك التأكّد من أنّ العميل يُدخل العنوان الصحيح خلال فترة زمنية قصيرة.

يمكنك الاطّلاع على عرض توضيحي يعمل ورمز مصدر كامل لملء نموذج إدخال عنوان في نموذج الرمز هذا.

الاعتبارات الواجب مراعاتها عند تنفيذ الإكمال التلقائي للأماكن

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

• في نموذج عنوان، اضبط المعلَمة types على address لحصر النتائج بعناوين الشوارع الكاملة. يمكنك الاطّلاع على مزيد من المعلومات عن الأنواع المتوافقة في طلبات الإكمال التلقائي الخاصة بميزة "عرض الإعلانات".
• ضَع القيود والانحيازات المناسبة إذا لم تكن بحاجة إلى البحث في جميع أنحاء العالم. وهناك عدد من المَعلمات التي يمكن استخدامها لانحياز أو حصر أي مطابقة في مناطق محدّدة فقط.
  • استخدِم bounds لضبط الحدود المستطيلة لتقييد منطقة، واستخدِم strictBounds لضمان عرض العناوين في تلك المناطق فقط.
  • يمكنك استخدام السمة componentRestrictions لحصر الردود بمجموعة محدّدة من البلدان.
• اترك الحقول قابلة للتعديل في حال عدم تضمين حقول معيّنة من المطابقة والسماح للعملاء بتعديل العنوان إذا لزم الأمر. وبما أنّ معظم العناوين التي تعرضها ميزة "الإكمال التلقائي" لميزة "الإكمال التلقائي" الخاصة بالأماكن لا تحتوي على أرقام المباني الفرعية، مثل أرقام الشقة أو الأجنحة أو الوحدات السكنية، ينقل هذا المثال التركيز إلى سطر العنوان 2 لتشجيع المستخدم على ملء هذه المعلومات إذا لزم الأمر.

تقديم تأكيد مرئي من خلال Maps Static API

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

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

بدء استخدام واجهة برمجة التطبيقات الثابتة للخرائط

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

تعرض الطلب التالي خارطة طريق بحجم 600×300 بكسل متمركزة في مقر شركة Google في ماونتن فيو، كاليفورنيا عند مستوى التكبير 13. وتحدّد أيضًا علامة موقع تسليم زرقاء ونمط خريطة على الإنترنت.

      https://maps.googleapis.com/maps/api/staticmap?center=37.422177,-122.084082
      &zoom=13
      &size=600x300
      &maptype=roadmap
      &markers=color:blue%7Clabel:S%7C37.422177,-122.084082
      &map_id=8f348d1b5a61d4bb
      &key=YOUR_API_KEY
      &solution_channel=GMP_guides_checkout_v1_a
      

ينقسم هذا إلى الأقسام التالية:

عنوان URL لواجهة برمجة التطبيقات	https://maps.googleapis.com/maps/api/staticmap?
مركز الخريطة	center=37.422177,-122.084082
مستوى التكبير أو التصغير	تكبير/تصغير=13
حجم الصورة	الحجم=600×300
نوع الخريطة	maptype=roadmap
علامات الموقع الجغرافي للمتجر	markers=color:blue%7Clabel:C%7C37.422177,-122.084082
نمط خريطة السحابة الإلكترونية	map_id=8f348d1b5a61d4bb
مفتاح واجهة برمجة التطبيقات	key=YOUR_API_KEY
مَعلمة قناة الحل (اطّلِع على مستندات المَعلمات).	solution_channel=GMP_guides_checkout_v1_a

تصبح هذه الصورة كما هو موضّح أدناه:

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

نصائح لتحسين عملية الدفع

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

• اسمح للمستخدمين بإدخال عنوان بناءً على اسم نشاط تجاري أو نقطة اهتمام. لا تعمل خدمة التنبؤات "الكتابة مسبقًا" مع العناوين فحسب، بل يمكنك أيضًا اختيار السماح بإدخال أسماء الأنشطة التجارية أو المعالم. بعد إدخال المستخدم اسم نشاط تجاري، من السهل استرداد العنوان من خلال طلب تفاصيل المكان. للسماح بإدخال العناوين وأسماء المؤسسات، أزِل السمة types من تعريف الإكمال التلقائي.
• خصِّص مظهر ومضمون مربّع الإكمال التلقائي لـ "الأماكن" ليطابق نمط موقعك الإلكتروني. ويمكنك أيضًا اختيار تصميم أداة الإكمال التلقائي لتتناسب مع شكل سلة التسوّق ومضمونها. تتوفّر لك مجموعة من فئات CSS لتخصيصها. للاطّلاع على مزيد من المعلومات حول طريقة تصميم مربّع الإكمال التلقائي، يمكنك الاطّلاع على المستندات.
• في حال أردت إنشاء واجهة مستخدم مخصَّصة عند إنشاء واجهة مستخدم مخصّصة بدلاً من استخدام واجهة المستخدم التي صمّمتها Google، يجب طلب خدمة "الإكمال التلقائي" آليًا لاسترداد عبارات البحث المقترحة لإدخال معيّن. يمكنك استرداد عبارات البحث المقترحة من ميزة "الإكمال التلقائي" لميزة "المكان" آليًا في JavaScript وAndroid وiOS، بالإضافة إلى طلب بيانات من واجهة برمجة تطبيقات خدمات الويب مباشرةً من خلال Places API.