پیکربندی

پیکربندی کانتینر آرکپچا

تنها راه برای پیکربندی آرکپچا تنظیم ویژگی های سفارشی در کانتینر آرکپچا <div> است. قبلا این کار را با data-site-key انجام داده‌اید، اما تعدادی ویژگی اختیاری دیگر وجود دارد که سفارشی سازی بیشتر را امکان پذیر می کند.

ویژگی	مقدار	توضیحات
data-site-key	<your site key>	ضروری. sitekey عمومی شما
data-size	normal | inivisible	اختیاری. اندازه ویجت را تنظیم کنید. پیش‌فرض normal است.
data-theme	light | dark	اختیاری. تم ویجت را تنظیم کنید. پیش فرض light است.
data-color	اسم رنگ یا کد hex	اختیاری. رنگ هر عنصر در ویجت را تنظیم کنید.
data-lang	en | fa	اختیاری. تنظیم زبان ویجت به طور پیش فرض fa است
data-callback	<function name>	اختیاری. زمانی که کاربر یک پاسخ موفقیت آمیز ارسال می کند، فراخوانی می شود و arcaptcha-token به callback ارسال می شود.
data-rendered-callback	<function name>	اختیاری. این تابع پس از رندر کپچا فراخوانی می شود.
data-error-callback	<function name>	اختیاری. این تابع پس از خطا فراخوانی می شود.
data-reset-callback	<function name>	اختیاری. این تابع پس از بازگذاری مجدد کپچا فراخوانی می شود.
data-expired-callback	<function name>	اختیاری. این تابع پس از انقضا فراخوانی می شود.
data-chlexpired-callback	<function name>	اختیاری. این تابع پس از انقضای چالش فراخوانی می شود.

علاوه بر data-site-key مورد نیاز، می توانید هر تعداد یا چند ویژگی پیکربندی را که می خواهید اضافه کنید.

<div
  class="arcaptcha"
  data-site-key="your_site_key"
  data-callback="onSubmit"
></div>

همه ویژگی‌های بالا می‌توانند به‌عنوان آرگومان‌های پارامتر هنگام رندر کردن صریح با ()arcaptcha.renderاستفاده شوند (توضیح داده شده در بخش بعدی). در این حالت، نام پارامتر همانطور که در بالا نشان داده شده است، اما بدون پیشوند data است. به عنوان مثال، آرگومان پارامتر data-site-key به صورت site_key خواهد بود.

<script type="text/javascript">
  arcaptcha.render("captcha-1", {
    site_key: "your_site_key",
  });
</script>

JavaScript API

ARCaptcha API شیء آرکپچا را نشان می دهد که متدهایی دارد که ممکن است در سفارشی کردن آرکپچا مفید باشد.

arcaptcha.render(container, params)

ویجت آرکپچا را در داخل عنصر DOM کانتینر ارائه می کند. یک widgetID منحصر به فرد را برای ویجت برمی گرداند.

• container شناسه رشته کانتینر یا عنصر DOM کانتینر.

• params یک شی حاوی پارامترهای پیکربندی به عنوان جفت کلید = مقدار. برای مثال :

{
   size: "invisible",
   site_key: "your_site_key"
}

arcaptcha.reset(widgetID)

ویجت آرکپچا را با widgetID ریست می کند.

• widgetID شناسه منحصر به فرد اختیاری برای یک ویجت. پیش‌فرض‌ برای اولین ویجت ایجاد می‌شود.

arcaptcha.getArcToken(widgetID)

شناسه چالش را برای ویجت آرکپچا با widgetID دریافت می کند.

• widgetID شناسه منحصر به فرد اختیاری برای یک ویجت. پیش‌فرض‌ برای اولین ویجت ایجاد شده می‌باشد.

arcaptcha.execute(widgetID)

گردش کار آرکپچا را به صورت برنامه‌ریزی شده راه اندازی می کند. به طور کلی در حالت نامرئی استفاده می شود که در آن ظرف هدف به جای یک دکمه، یک div است. یک promise را برمی‌گرداند که پس از حل چالش توسط کاربر برطرف می‌شود و پس از هر گونه خطا یا حل نادرست رد می‌شود.

• widgetID شناسه منحصر به فرد اختیاری برای یک ویجت. پیش‌فرض‌ برای اولین ویجت ایجاد شده می‌باشد.

arcaptcha
  .execute()
  .then(({ arcaptcha_token }) => {
    console.log(arcaptcha_token);
  })
  .catch((err) => {
    console.error(err);
  });

به صراحت آرکپچا را رندر کنید

در اجرای پیش‌فرض، ابزارک‌های آرکپچا به‌طور خودکار رندر می‌شوند و در صفحه وب شما درج می‌شوند. با این حال، می‌توانید رندر را با تعیین یک تابع callback که در آن ویجت را خودتان رندر می‌کنید، به تعویق بیندازید.

برای تعیین یک تابع callback، باید نام تابع را به عنوان یک ویژگی به container آرکپچا یا به عنوان پارامتر به تابع render بفرستید.

سپس می‌توانید arcaptcha.render را با container selector (id یا کلاس) یا HTMLElement و کلید سایت خود فراخوانی کنید تا ویجت را به‌صراحت رندر کنید.

<script type="text/javascript">
  var yourFunction = function () {
    console.log("ARCaptcha is ready.");
    var widgetID = arcaptcha.render("captcha-1", {
      site_key: "your_site_key",
    });
  };
</script>

تست ادغام : کلید های تست

اگر از آرکپچا استفاده می‌کنید و قصد دارید برای نرم‌افزار خود تست بنویسید، ساده‌ترین راه برای کنار گذاشتن کپچا در محیط تست استفاده از کلیدهای مخصوص آرکپچا است که برای استفاده در چنین شرایطی تهیه شده‌اند. با استفاده از site-key مخصوص محیط تست، کپچا به صورت خودکار حل شده و یک مقدار خاص می‌پذیرد. دقت داشته باشید که این مقدار خاص در صورت استفاده از secret-key مخصوص تست تایید(verify) خواهد شد.

توجه

کلیدهای ذکر شده صرفا برای استفاده در محیط تست هستند و استفاده از آنها در محیط عملیاتی توصیه نمی‌شود. چرا که این کلیدها هیچ ویژگی تشخیص رباتی برای شما فراهم نمی‌آورند!

Test Key Set

Test parameter	Value
site-key	0000000000
secret-key	00000000000000000000
arcaptcha-token	000000000000000000000000000000