reCAPTCHA - الإصدار 2

توضّح هذه الصفحة كيفية عرض وتخصيص التطبيق المصغّر للإصدار 2 من reCAPTCHA على صفحتك على الويب.

لعرض الأداة، يمكنك تنفيذ أحد الإجراءَين التاليَين:

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

راجع التحقُّق من رد المستخدم لمعرفة ما إذا كان المستخدم قد حل اختبار CAPTCHA بنجاح.

عرض تطبيق reCAPTCHA المصغّر تلقائيًا

إنّ أسهل طريقة لعرض تطبيق reCAPTCHA المصغّر على صفحتك هي تضمين مورد JavaScript المناسب وعلامة g-recaptcha. العلامة g-recaptcha هو عنصر DIV باسم الفئة g-recaptcha ومفتاح موقعك في السمة data-sitekey:

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
    <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  </head>
  <body>
    <form action="?" method="POST">
      <div class="g-recaptcha" data-sitekey="your_site_key"></div>
      <br/>
      <input type="submit" value="Submit">
    </form>
  </body>
</html>

يجب تحميل النص البرمجي باستخدام بروتوكول HTTPS ويمكن تضمينه من أي نقطة إلى الصفحة بدون قيود.

عرض تطبيق reCAPTCHA المصغّر بوضوح

يمكن تأجيل العرض من خلال تحديد دالة معاودة الاتصال onload. وإضافة معلَمات إلى مورد JavaScript

  1. حدِّد دالة معاودة الاتصال onload. سيتم استدعاء هذه الدالة عندما تحميل جميع التبعيات.

    <script type="text/javascript">
  var onloadCallback = function() {
    alert("grecaptcha is ready!");
  };
</script>

  2. إدراج مورد JavaScript، مع ضبط المَعلمة onload على الاسم من دالة رد الاتصال onload والمعلمة render إلى explicit.

    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
    async defer>
</script>

    عند تنفيذ معاودة الاتصال، يمكنك استدعاء الطريقة grecaptcha.render من JavaScript API.

الإعداد

معلمات مورد JavaScript (api.js)

المعلمة القيمة الوصف
Onload اختياريّ. اسم دالة معاودة الاتصال الذي سيتم تنفيذه بمجرد تحميل جميع التبعيات.
عرض explicit
onload		 اختياريّ. تحديد ما إذا كان سيتم عرض الأداة بشكل صريح يتم ضبط الإعدادات التلقائية على onload، ما يؤدي إلى عرض الأداة في أول علامة g-recaptcha يتم العثور عليها.
hl الاطّلاع على رموز اللغات اختياريّ. تفرض هذه السياسة عرض الأداة بلغة معيّنة. ترصد هذه الميزة لغة المستخدم تلقائيًا في حال عدم تحديدها.

سمات علامة g-recaptcha ومعلمات grecaptcha.render

سمة علامة g-recaptcha المَعلمة grecaptcha.render القيمة تلقائي الوصف
data-sitekey مفتاح الموقع مفتاح موقعك.
data-theme مظهر ضوء داكن ضوء اختياريّ. مظهر لون التطبيق المصغّر
حجم البيانات الحجم مضغوطة عادية عادي اختياريّ. حجم التطبيق المصغّر.
data-tabindex فهرس Tab 0 اختياريّ. Tabindex للتطبيق المصغّر والتحدي إذا كانت العناصر الأخرى في صفحتك تستخدم علامة Tabindex، يجب ضبطها لتسهيل التنقّل بين المستخدمين.
data-callback رد الاتصال اختياريّ. اسم دالة معاودة الاتصال، ويتم تنفيذه عندما يرسل المستخدم ردًا ناجحًا. يتم تمرير الرمز المميّز g-recaptcha-response إلى معاودة الاتصال.
data-expired-callback expired-callback اختياريّ. تشير هذه السمة إلى اسم دالة معاودة الاتصال، ويتم تنفيذه عند انتهاء صلاحية استجابة reCAPTCHA وحاجة المستخدم إلى إعادة إثبات الملكية.
data-error-callback خطأ في الاتصال اختياريّ. تشير هذه السمة إلى اسم دالة معاودة الاتصال، ويتم تنفيذه عندما تواجه خدمة reCAPTCHA خطأ (عادةً ما تكون إمكانية الاتصال بالشبكة) ولا يمكنها المتابعة إلى أن تتم استعادة الاتصال. إذا حدَّدت دالة هنا، ستكون مسؤولاً عن إبلاغ المستخدم بضرورة إعادة المحاولة.

JavaScript API

الطريقة الوصف
grecaptcha.render(
وعاء
المعلمات
) 		يعرض الحاوية كتطبيق مصغّر reCAPTCHA ويعرض معرّف التطبيق المصغّر الذي تم إنشاؤه حديثًا.
حاوية
عنصر HTML لعرض تطبيق reCAPTCHA المصغّر. حدِّد معرّف الحاوية (سلسلة) أو عنصر DOM نفسه.
المَعلمات
كائن يحتوي على معلَمات كأزواج المفتاح/القيمة، مثل {"sitekey": "your_site_key", "theme": "light"}. اطّلِع على مَعلمات grecaptcha.render.
grecaptcha.reset(
opt_widget_id
) 		إعادة ضبط تطبيق reCAPTCHA المصغّر.
opt_widget_id
رقم تعريف الأداة الاختياري، يتم ضبطه تلقائيًا على أول تطبيق مصغّر يتم إنشاؤه في حال عدم تحديده.
grecaptcha.getResponse(
opt_widget_id
) 		الحصول على استجابة تطبيق reCAPTCHA المصغّر.
opt_widget_id
رقم تعريف الأداة الاختياري، يتم ضبطه تلقائيًا على أول تطبيق مصغّر يتم إنشاؤه في حال عدم تحديده.

أمثلة

عرض صريح بعد استدعاء عند التحميل

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
    <script type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.render('html_element', {
          'sitekey' : 'your_site_key'
        });
      };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <div id="html_element"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

العرض الصريح لأدوات متعددة

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render for multiple widgets</title>
    <script type="text/javascript">
      var verifyCallback = function(response) {
        alert(response);
      };
      var widgetId1;
      var widgetId2;
      var onloadCallback = function() {
        // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
        // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
        widgetId1 = grecaptcha.render('example1', {
          'sitekey' : 'your_site_key',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.render(document.getElementById('example2'), {
          'sitekey' : 'your_site_key'
        });
        grecaptcha.render('example3', {
          'sitekey' : 'your_site_key',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.reset(widgetId2);">
      <div id="example2"></div>
      <br>
      <input type="submit" value="reset">
    </form>
    <br>
    <!-- POSTs back to the page's URL upon submit with a g-recaptcha-response POST parameter. -->
    <form action="?" method="POST">
      <div id="example3"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>