پرش به مطلب اصلی
نسخه: 1.0.0

پیکربندی

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

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

ویژگیمقدار renderمقدارتوضیحات
data-site-keysite_key<your site key>ضروری. sitekey عمومی شما
data-sizesizenormal | inivisibleاختیاری. اندازه ویجت را تنظیم کنید. پیش‌فرض normal است.
data-themethemelight | darkاختیاری. تم ویجت را تنظیم کنید. پیش فرض light است.
data-colorcolorاسم رنگ یا کد hexاختیاری. رنگ هر عنصر در ویجت را تنظیم کنید.
data-langlangen | faاختیاری. تنظیم زبان ویجت به طور پیش فرض fa است
data-error-printerror_print0 | 1اختیاری. فعال کردن یا غیر فعال کردن پیام‌های ارور در زیر چک باکس. به طور پیش فرض0 است
data-callbackcallback<function name>اختیاری. زمانی که کاربر یک پاسخ موفقیت آمیز ارسال می کند، فراخوانی می شود و arcaptcha-token به callback ارسال می شود.
data-rendered-callbackrenderd_callback<function name>اختیاری. این تابع پس از رندر کپچا فراخوانی می شود.
data-error-callbackerror_callback<function name>اختیاری. این تابع پس از خطا فراخوانی می شود.
data-reset-callbackreset_callback<function name>اختیاری. این تابع پس از بازگذاری مجدد کپچا فراخوانی می شود.
data-expired-callbackexpired_callback<function name>اختیاری. این تابع پس از انقضا فراخوانی می شود.
data-chlexpired-callbackchlexpired_callback<function name>اختیاری. این تابع پس از انقضای چالش فراخوانی می شود.
data-blocked-callbackvlocked_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>

مدیریت خطا (سمت مشتری)

با تنظیم data-error-callback روی ویجت ARCaptcha می‌توانید به انواع مختلف خطاهایی که ممکن است در سمت کلاینت رخ دهد، دسترسی پیدا کنید.

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

<script>
function onError({ code, message }) {
console.log(code, "-", message); // '201-answer-server-error:500-خطای سرور'
}
</script>

ما خطاها را مانند پروتکل HTTP با کدها دسته‌بندی کرده‌ایم:

  • 1xx: خطاهای مرحله ایجاد
  • 2xx: خطاهای مرحله پاسخ

در این جدول می‌توانید تمام خطاهای پشتیبانی شده توسط ویجت ما را مشاهده کنید:

کدنامتوضیحاتمثال پیام
101CREATE_SERVER_ERRORزمانی که در سمت سرور ما در مرحله ایجاد خطایی رخ می‌دهدcreate-server-error:404-Website not found
102CREATE_NETWORK_ERRORزمانی که کلاینت نمی‌تواند در مرحله ایجاد به سرورهای ما متصل شودcreate-network-error:Network is unreachable
201ANSWER_SERVER_ERRORزمانی که در سمت سرور ما در مرحله پاسخ خطایی رخ می‌دهدanswer-server-error:500-Server error
202ANSWER_NETWORK_ERRORزمانی که کلاینت نمی‌تواند در مرحله پاسخ به سرورهای ما متصل شودanswer-network-error:Network is unreachable
203ANSWER_WRONG_ERRORزمانی که کلاینت پاسخ اشتباه ارسال می‌کندanswer-wrong-error
401UNKNOWN_ERRORهر خطای ناشناختهunknown-error

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

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

توجه

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

Test Key Set

Test parameterValue
site-key0000000000
secret-key00000000000000000000
arcaptcha-token000000000000000000000000000000