راهنمای فنی یکپارچه‌سازی تست‌های روان‌شناسی (وایت‌لِیبِل)

مقدمه و کاربردها

این سرویس به شما امکان می‌دهد تست‌های روان‌شناسی را به‌صورت وایت‌لیبل و قابل شخصی‌سازی در وب‌سایت یا اپلیکیشن‌تان نمایش دهید. کاربر بدون خروج از محیط شما تست را تکمیل می‌کند و نتیجه در همان چهارچوب، با ظاهر و برند خودتان، نمایش داده می‌شود.

مناسب برای: پلتفرم‌های آموزش و سلامت روان، کلینیک‌ها، SaaS ارزیابی، مارکت‌پلیس‌ها، وبلاگ‌ها و لندینگ‌ها.

ویژگی‌ها و مزایا

• وایت‌لیبل کامل: عدم نمایش نام/لوگو‌ی سرویس‌دهنده در خروجی.
• انعطاف در یکپارچه‌سازی: نمایش Inline، Dialog، دکمه شناور (FAB) یا دکمه کشویی (Drop)؛ همچنین امکان لینک مستقیم.
• برندسازی ساده: سفارشی‌سازی ظاهر با CSS اختصاصی از طریق form-theme.
• پیاده‌سازی سریع: تنها با یک <script> و بدون نیاز به دانش فنی پیچیده.
• مقیاس‌پذیر: امکان نمایش چندین تست متفاوت در یک صفحه.

پیش‌نیازها

• وب‌سایتی با دسترسی به HTML/CSS
• دسترسی به ویرایش سورس کد (یا پنل مدیریت محتوا)
• فعال بودن HTTPS برای بارگذاری منابع خارجی
• (اختیاری) آشنایی مقدماتی با iframe یا JavaScript

راهنمای شروع سریع

کد زیر را در هر جای صفحه HTML خود قرار دهید تا تست در آن نمایش داده شود:

html
<script 
  type="text/javascript" 
  src="https://formafzar.com/pages/formbuilder/ravesh-formbuilder.js" 
  form-url="https://eot.pal.ir/form/9xmbs" 
  form-style="inline" 
  form-theme="">
</script>

راهنما:

• form-url را با آدرس تست خودتان جایگزین کنید.
• اگر می‌خواهید ظاهر را سفارشی کنید، نشانی فایل CSS خود را در form-theme قرار دهید (در غیر این صورت خالی بماند).

انواع روش‌های نمایش فرم

1) لینک مستقیم (Direct Link)

نمایش یک لینک که با کلیک کاربر، فرم در صفحهٔ جداگانه باز می‌شود.

html
<a href="https://formafzar.com/form/9xmbs" target="_blank" rel="noopener">مشاهده فرم</a>

کِی استفاده کنیم؟ وقتی صفحه شما فضای کافی ندارد یا تمایل دارید تجربهٔ تست از محتوای اصلی جدا باشد.

2) فرم محاوره‌ای (Dialog Embed)

یک لینک روی صفحه که با کلیک، پنجرهٔ مودال باز می‌شود.

html
<script
  type="text/javascript"
  src="https://formafzar.com/pages/formbuilder/ravesh-formbuilder.js"
  form-url="https://eot.pal.ir/form/9xmbs"
  form-style="dialog"
  form-link-text="مشاهده فرم"
  form-theme="">
</script>

نکته: برای صفحات شلوغ که ترجیح می‌دهید فرم روی همان صفحه و بدون جابه‌جایی کاربر نمایش داده شود.

3) دکمه شناور (Floating Action Button - FAB)

دکمهٔ شناوری که همیشه در گوشهٔ صفحه در دسترس است و با کلیک، فرم در دیالوگ باز می‌شود.

html
<script
  type="text/javascript"
  src="https://formafzar.com/pages/formbuilder/ravesh-formbuilder.js"
  form-url="https://eot.pal.ir/form/9xmbs"
  form-style="fab"
  form-link-text="مشاهده فرم"
  form-button-color="#3f51b5"
  form-button-icon="https://eot.pal.ir/pages/formbuilder/images/send-icon.png"
  form-theme="">
</script>

پیشنهاد: برای صفحات طولانی (Long-form) و وبلاگ‌ها که دسترسی سریع به تست اهمیت دارد.

4) دکمه کشویی (Slide-in Panel)

یک تب/نوار کناری که با کلیک باز شده و فرم را درون خود نمایش می‌دهد.

html
<script
  type="text/javascript"
  src="https://formafzar.com/pages/formbuilder/ravesh-formbuilder.js"
  form-url="https://eot.pal.ir/form/9xmbs"
  form-style="drop"
  form-link-text="مشاهده فرم"
  form-width="320px"
  form-height="400px"
  form-position="right"
  form-theme="">
</script>

نکتهٔ طراحی: برای صفحه‌های اپلیکیشن‌محور که نیاز به فضای کاری ثابت دارند.

پارامترهای قابل پیکربندی

نمایش چند تست در یک صفحه

برای هر تست، یک اسکریپت جدا با form-url مخصوص خودش اضافه کنید:

html
<!-- تست A -->
<script
  type="text/javascript"
  src="https://formafzar.com/pages/formbuilder/ravesh-formbuilder.js"
  form-url="https://eot.pal.ir/form/AAA"
  form-style="inline"
  form-theme="">
</script>

<!-- تست B -->
<script
  type="text/javascript"
  src="https://formafzar.com/pages/formbuilder/ravesh-formbuilder.js"
  form-url="https://eot.pal.ir/form/BBB"
  form-style="inline"
  form-theme="">
</script>

مستندات پیشرفته

وب‌هوک‌ها

با وقوع هر رویداد روی فرم‌ها، یک درخواست POST به آدرس(های) وب‌هوک شما ارسال می‌شود. رویدادهای پشتیبانی‌شده:

• Create – ثبت اطلاعات
• Update – ویرایش اطلاعات
• Delete – حذف اطلاعات

ساختار رویدادها

ثبت اطلاعات

json
{
  "form": {
    "id": "شناسه‌ی فرم پر شده",
    "formId": "شناسه‌ی فرم",
    "formattedId": "شناسه‌ی اختصاصی",
    "creatorId": "شناسه‌ی کاربر ثبت کننده",
    "creatorName": "نام کاربر ثبت کننده",
    "createDate": "تاریخ ثبت",
    "editorId": "شناسه‌ی ویرایش کننده",
    "editorName": "نام ویرایش کننده",
    "editDate": "تاریخ ویرایش",
    "custCode": "شناسه‌ی مشتری",
    "custName": "نام مشتری",
    "urlReferrer": "آدرس اینترنتی ثبت فرم",
    "browser": "نام مرورگر",
    "ip": "آی پی",
    "coordinate": "موقعیت جغرافیایی",
    "params": [
      {
        "fieldId": "شناسه‌ی فیلد",
        "title": "مقدار متنی",
        "value": "مقدار",
        "number": "مقدار عددی",
        "group": "گروه پارامتر"
      }
    ]
  }
}

ویرایش اطلاعات

json
{
  "form": {
    "id": "شناسه‌ی فرم پر شده",
    "formId": "شناسه‌ی فرم",
    "formattedId": "شناسه‌ی اختصاصی",
    "creatorId": "شناسه‌ی کاربر ثبت کننده",
    "creatorName": "نام کاربر ثبت کننده",
    "createDate": "تاریخ ثبت",
    "editorId": "شناسه‌ی ویرایش کننده",
    "editorName": "نام ویرایش کننده",
    "editDate": "تاریخ ویرایش",
    "custCode": "شناسه‌ی مشتری",
    "custName": "نام مشتری",
    "urlReferrer": "آدرس اینترنتی ثبت فرم",
    "browser": "نام مرورگر",
    "ip": "آی پی",
    "coordinate": "موقعیت جغرافیایی",
    "paymentStatus": "وضعیت پرداخت",
    "params": [
      {
        "fieldId": "شناسه‌ی فیلد",
        "title": "مقدار متنی",
        "value": "مقدار",
        "number": "مقدار عددی",
        "group": "گروه پارامتر"
      }
    ]
  }
}

حذف اطلاعات

json

{
  "ids": [
    "شناسه فرم حذف شده"
  ]
}

پارامترهای لینک فرم (Query String Binding)

کاربرد: پیش‌پرکردن فیلدها یا ارسال متادیتا (مثل منبع ارجاع، کمپین، شناسه کاربر) به فرم از طریق Query String در URL. این مقادیر می‌توانند قابل‌ویرایش برای کاربر باشند یا به‌صورت قفل/رمزشده ثبت شوند.

موارد استفادهٔ رایج

• انتساب منبع ترافیک/کمپین (مانند referrer, utm_source, utm_campaign)
• پیش‌پرکردن شناسه کاربر/سفارش (بدون نمایش به کاربر)
• انتخاب پیش‌فرض‌هایی در فرم (مثلاً نوع تست، زبان، پلن)
• اجرای آزمایش‌های A/B با پارامترهای کنترلی

پیکربندی

1. نگاشت پارامترهای URL به فیلدهای فرم: هر کلید در Query String می‌تواند به یک فیلد متناظر متصل شود و مقدار آن را تنظیم کند.
2. دو حالت مقداردهی:
   • Editable (قابل‌ویرایش): مقدار به‌عنوان پیش‌فرض فیلد قرار می‌گیرد و کاربر می‌تواند آن را تغییر دهد.
   • Locked/Encrypted (قفل/رمزشده): مقدار به‌صورت غیرقابل‌ویرایش و مقاوم در برابر دست‌کاری ثبت می‌شود (مناسب برای متادیتای حساس).
3. پشتیبانی از فیلدهای مخفی: امکان ثبت مقادیر بدون نمایش به کاربر.
4. چندپارامتری: امکان استفادهٔ هم‌زمان از چند کلید (برای نسبت‌دادن کمپین، منبع ارجاع، شناسه کاربر/سفارش و…).
5. جریان دادهٔ یکپارچه: مقادیر تنظیم‌شده در رکورد نهایی ذخیره و از طریق گزارش‌ها و وب‌هوک‌ها قابل دسترسی هستند.

ساخت لینک‌ها

قابل‌ویرایش:

https://example.com/form/3xpc8?referrer=instagram

قفل شده:

https://example.com/form/3xpc8?referrer=xamk2AOv5GXE76q4gcO/IQ==

چند پارامتر هم‌زمان:

https://example.com/form/3xpc8?referrer=instagram&utm_campaign=spring&utm_source=siteA

اگر از تعبیهٔ اسکریپتی استفاده می‌کنید، می‌توانید Query String را مستقیماً به مقدار form-url بیافزایید:

<script
  src="/sdk/embed.js"
  type="text/javascript"
  form-url="https://example.com/form/3xpc8?referrer=instagram"
  form-style="inline">
</script>

افزودن خودکار پارامتر در Front-End

html
<a data-form-link href="https://example.com/form/3xpc8">شروع تست</a>
<script>
  (function () {
    var a = document.querySelector('a[data-form-link]');
    if (!a) return;
    var url = new URL(a.href);
    var ref = (new URL(document.referrer || location.href)).hostname || 'direct';
    url.searchParams.set('referrer', ref);
    a.href = url.toString();
  })();
</script>

بهترین‌عمل‌ها

• URL-encode مقادیر پارامترها؛ از کاراکترهای رزرو‌شده در مقدار خام استفاده نکنید.
• از قراردادن PII در Query String خودداری کنید؛ برای مقادیر حساس از حالت Locked/Encrypted استفاده کنید.
• نام‌گذاری پارامترها را مستند کنید (snake_case یا camelCase) و از تداخل با پارامترهای رزرو‌شده اجتناب کنید.
• در حالت Editable، مقدار URL فقط مقدار اولیه است و کاربر می‌تواند آن را تغییر دهد. 
  

عیب‌یابی سریع

• مقدار اعمال نشده؟ نگاشت فیلد ← کلید پارامتر را بررسی کنید.
• مقدار به‌هم‌ریخته؟ URL-encoding را چک کنید.
• مقدار دیده می‌شود؟ حالت را از Editable به Locked/Encrypted تغییر دهید.
• چند پارامتر؟ با & جدا کنید و از کلیدهای یکتا استفاده کنید.

خروجی نهایی پارامترهای لینک در کنار سایر فیلدها ذخیره می‌شود و در رویدادهای وب‌هوک (Create/Update) نیز در دسترس است.

پیش نمایش پارامترهای لینک فرم

نکات پیاده‌سازی و عیب‌یابی

• مکان قرارگیری اسکریپت:
  برای حالت‌های inline و drop/dialog، اسکریپت را در همان جایی بگذارید که می‌خواهید نقطهٔ شروع تعامل باشد. برای fab، داخل <body> کافی است. 
  
• HTTP/HTTPS:
  سایت شما اگر HTTPS است، منابع فرم را نیز حتماً با HTTPS لود کنید تا خطای Mixed Content رخ ندهد.
• تست در موبایل:
  پس از استقرار، حتماً در دستگاه‌های واقعی موبایل چک کنید (نمایش، اسکرول، صفحه‌کلید مجازی، بستن دیالوگ).
• لود چندباره اسکریپت:
  از درج مکرر یکسان src در صفحه خودداری کنید مگر برای چند تست با form-url متفاوت (که هر کدام یک تگ مجزا دارند).

پرسش‌های متداول