اختبار reCAPTCHA غير مرئي

تشرح هذه الصفحة كيفية تفعيل خدمة reCAPTCHA غير المرئية وتخصيصها على صفحتك على الويب.

لاستدعاء reCAPTCHA غير المرئي، يمكنك اتّباع إحدى الخطوتَين التاليتَين:

راجِع الإعدادات لمعرفة كيفية تخصيص رمز reCAPTCHA غير المرئي. على سبيل المثال، يمكنك تحديد اللغة أو الموقع الجغرافي للشارة.

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

ربط التحدي تلقائيًا بزر

أسهل طريقة لاستخدام أداة reCAPTCHA غير المرئية على صفحتك هي تضمين مورد JavaScript الضروري وإضافة بعض السمات إلى زر html. يجب أن تتضمن السمات التالية اسم الفئة 'g-recaptcha'، ومفتاح الموقع الإلكتروني في السمة data-sitekey، واسم استدعاء JavaScript للتعامل مع إكمال اختبار CAPTCHA في السمة data-callback.

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
     <script src="https://www.google.com/recaptcha/api.js" async defer></script>
     <script>
       function onSubmit(token) {
         document.getElementById("demo-form").submit();
       }
     </script>
  </head>
  <body>
    <form id="demo-form" action="?" method="POST">
      <button class="g-recaptcha" data-sitekey="your_site_key" data-callback="onSubmit">Submit</button>
      <br/>
    </form>
  </body>
</html>

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

اربط التحدي آليًا بأحد الأزرار أو استدعِ التحدي.

يمكن تأجيل الربط من خلال تحديد دالة رد الاتصال عند التحميل وإضافة معلمات إلى مورد JavaScript. يعمل هذا الإجراء تمامًا مثل تحدي reCAPTCHA العادي.

استدعاء التحدي آليًا.

يمكن تنفيذ استدعاء التحقق من reCAPTCHA آليًا من خلال عرض التحدي في div مع إحدى السمات data-size="invisible" والتنفيذ البرمجي.

  1. إنشاء علامة div باستخدام data-size="invisible".

    <div class="g-recaptcha"
          data-sitekey="_your_site_key_"
          data-callback="onSubmit"
          data-size="invisible">
    </div>
    
  2. استدعِ grecaptcha.execute من طريقة JavaScript.

    grecaptcha.execute();
    

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

الإعدادات

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

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

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

سمة علامة g-recaptcha مَعلمة grecaptcha.render القيمة تلقائي الوصف
مفتاح موقع البيانات مفتاح الموقع مفتاح الموقع الإلكتروني:
شارة البيانات شارة مضمّن أسفل اليمين أسفل اليسار أسفل اليسار اختياريّ. غيِّر موضع شارة reCAPTCHA. يتيح لك "inline" تحديد موضعه مع CSS.
data-size size غير مرئي اختياريّ. يُستخدم لإنشاء عنصر مصغّر غير مرئي مرتبط بعلامة div ويتم تنفيذه آليًا.
data-tabindex فهرس التبويب 0 اختياريّ. تمثّل هذه السمة فهرس التبويب للتحدي. إذا كانت هناك عناصر أخرى في صفحتك تستخدم tabindex، يجب ضبطها لتسهيل تنقّل المستخدم.
معاودة الاتصال بالبيانات رد الاتصال اختياريّ. تشير هذه السمة إلى اسم وظيفة معاودة الاتصال، والتي يتم تنفيذها عندما يرسل المستخدم ردًا ناجحًا. تم تمرير الرمز المميز g-recaptcha-response إلى معاودة الاتصال.
انتهاء صلاحية بيانات-معاودة الاتصال معاودة الاتصال منتهية الصلاحية اختياريّ. تشير هذه السمة إلى اسم وظيفة معاودة الاتصال التي يتم تنفيذها عند انتهاء صلاحية استجابة reCAPTCHA ويحتاج المستخدم إلى إعادة التحقّق.
معاودة الاتصال بخطأ بيانات خطأ-معاودة الاتصال اختياريّ. اسم وظيفة معاودة الاتصال التي يتم تنفيذها عندما تواجه reCAPTCHA خطأً (عادةً ما يكون الاتصال بالشبكة) ولا يمكن المتابعة حتى تتم استعادة الاتصال. وفي حال تحديد دالة هنا، تكون مسؤولاً عن إبلاغ المستخدم بضرورة إعادة المحاولة.
معزولة false اختياريّ. كي لا يتداخل مالكو المكوّنات الإضافية مع عمليات تثبيت reCAPTCHA الحالية على إحدى الصفحات إذا كانت القيمة true، سيكون مثيل reCAPTCHA هذا جزءًا من مساحة معرّف منفصلة.

JavaScript API

الطريقة الوصف
grecaptcha.render(
الحاوية،
أو المعاملات،
موروث
)
يؤدي هذا الخيار إلى عرض الحاوية كأداة reCAPTCHA، مع عرض معرّف التطبيق المصغّر الذي تم إنشاؤه حديثًا.
container
عنصر HTML لعرض تطبيق reCAPTCHA المصغّر. حدِّد إما رقم تعريف الحاوية (سلسلة) أو عنصر DOM نفسه.
المعلَمات
عنصر يحتوي على معلَمات كأزواج المفتاح=القيمة، مثل {"sitekey": "your_site_key", "theme": "light"}. الاطّلاع على معلَمات grecaptcha.render.
اكتساب
استخدِم سمات data-* الحالية في العنصر إذا لم يتم تحديد المَعلمة المقابلة. وسيكون للمعلمات الأولوية على السمات.
grecaptcha.execute(
opt_widget_id
)
استدعاء شيك reCAPTCHA آليًا. تُستخدَم هذه الوظيفة إذا كانت خدمة reCAPTCHA غير المرئية على قسم div بدلاً من زر.
opt_widget_id
معرّف أداة اختياري، ويتم ضبطه تلقائيًا على أول أداة يتم إنشاؤها إذا لم يتم تحديدها.
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>
        var onSubmit = function(token) {
          console.log('success!');
        };

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

استدعاء تحدي reCAPTCHA غير المرئي بعد التحقّق من جهة العميل

<html>
  <head>
  <script>
    function onSubmit(token) {
      alert('thanks ' + document.getElementById('field').value);
    }

    function validate(event) {
      event.preventDefault();
      if (!document.getElementById('field').value) {
        alert("You must add text to the required field");
      } else {
        grecaptcha.execute();
      }
    }

    function onload() {
      var element = document.getElementById('submit');
      element.onclick = validate;
    }
  </script>
  <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  </head>
  <body>
    <form>
      Name: (required) <input id="field" name="field">
      <div id="recaptcha" class="g-recaptcha"
          data-sitekey="_your_site_key_"
          data-callback="onSubmit"
          data-size="invisible"></div>
      <button id="submit">submit</button>
    </form>
    <script>onload();</script>
  </body>
</html>