اتصال به لیدآرا

لیدآرا با دریافت رویدادها (این‌که کاربران چه می‌کنند) و هویت‌ها (این‌که چه کسانی هستند) کار می‌کند. وقتی رویدادها وارد شوند، تیم بازاریابی روی همان‌ها تحلیل، بخش‌بندی، مسیر و کمپین می‌سازد — کار شما فقط ارسال رویدادهای خوب است.

راهنمای ثابت و نسخه‌دار برای عامل AI

این آدرس ثابت را به دستیار کدنویسی بدهید؛ همیشه آخرین نسخهٔ راهنما را ارائه می‌کند. فایل JSON نسخه، هش محتوا، روش‌های اتصال و لینک نسخه‌های ثابت را دارد. نسخهٔ راهنما با نسخهٔ اسکریپت فرق دارد؛ پیش از نصب، آماده‌بودن endpointهای Runtime را بررسی کنید.

برای کشف خودکار ایونت‌ها از یکپارچه‌سازی‌ها → Site Runtime اسکریپت بگیرید. برای ردیابی دستی از SDK کلاسیکِ پایین استفاده کنید. بدون اسکریپت، API مناسب است؛ روش ترکیبی هم مشاهدهٔ مرورگر را با رویدادهای معتبر سمت سرور همراه می‌کند. Runtime و SDK کلاسیک را هم‌زمان نصب نکنید.

در Runtime نسخهٔ 0.3.0 این تگ عمومی را نصب کنید؛ site_x را با شناسهٔ کامل سایت از SiteConnection یکتای فضای کاری جایگزین کنید:

<script defer src="https://api.leadara.ir/site-runtime.js" data-site-id="site_x"></script>

نشست Runtime توکن مستقل دارد؛ شناسهٔ فضای کاری، کلید نوشتن یا ویژگی API-base روی این تگ نگذارید. مبدأ API از src گرفته می‌شود. مبدأ دقیق سایت را تنظیم کنید؛ تطبیق مبدأ به معنی تأیید مالکیت دامنه نیست. راهنمای 3.0.0 مورخ 2026-10-18 قرارداد و محدودیت قابلیت‌ها را توضیح می‌دهد؛ نصب Runtime به‌تنهایی تضمین همهٔ قابلیت‌های SDK کلاسیک نیست.

کدام مسیر را انتخاب کنم؟

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

• سایت وردپرسی ← افزونهٔ لیدآرا را نصب کنید و شناسهٔ فضای کاری و کلید نوشتن را وارد کنید. بدون کدنویسی.
• وب‌سایت یا وب‌اپ ← برای کشف خودکار Site Runtime بالا و برای ردیابی دستی و قابلیت‌های SDK، SDK کلاسیک پایین را انتخاب کنید.
• موبایل، بک‌اند یا سمت سرور ← مستقیم API را صدا بزنید.

می‌توانید ترکیب کنید — مثلاً اسنیپت روی سایت و API از سمت سرور.

دریافت اطلاعات حساب

بخش‌های SDK کلاسیک، وردپرس و API پایین از اطلاعات منبع در یکپارچه‌سازی‌ها → منابع استفاده می‌کنند؛ Runtime فقط شناسهٔ سایت خودش را می‌خواهد:

• شناسهٔ فضای کاری — یک UUID مثل 1c4f1e2a-….
• کلید نوشتن — در اسنیپت SDK کلاسیک و هدر x-write-key استفاده می‌شود. کلید مرورگر عمومی است؛ منبعی مستقل با حداقل مجوز Write بسازید. کلیدهای منبع ممکن است مجوزهای دیگری هم داشته باشند.

اسنیپت SDK کلاسیک وب‌سایت

این را در <head> اضافه کنید و دو جای‌گزین را عوض کنید:

<script
  async
  src="https://api.leadara.ir/sdk/WORKSPACE_ID/sdk.js"
  data-write-key="WRITE_KEY"
></script>

به‌صورت خودکار ثبت بازدید صفحه‌ها را شروع می‌کند. بعد هرجا که خواستید این‌ها را صدا بزنید:

window.leadara.identify("user-123", { email: "sam@example.com", plan: "pro" });
window.leadara.track("checkout_started", { cartValue: 149000, currency: "IRR" });
window.leadara.page("Pricing");
window.leadara.group("acct-42", { companyName: "Acme Co." });
window.leadara.reset(); // هنگام خروج از حساب

وقتی کاربر از حسابش خارج می‌شود reset() را صدا بزنید تا نفر بعدی روی همان دستگاه، بازدیدکننده‌ی تازه حساب شود و به پروفایل نفر قبلی نچسبد.

اگر برنامه‌ی شما این دستورها را قبل از بارگذاری اسکریپت صدا می‌زند (در اپ‌های تک‌صفحه‌ای رایج است)، این خط را بالای اسکریپت نصب بگذارید تا دستورهای زودهنگام نگه داشته شوند و بعد از بارگذاری ارسال شوند:

<script>window.leadara=window.leadara||{_q:[]};["identify","track","page","group","reset"].forEach(function(m){window.leadara[m]=window.leadara[m]||function(){window.leadara._q.push([m,[].slice.call(arguments)])}});</script>

تنظیمات سایت از داشبورد

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

ویژگی‌های قدیمی مثل data-session-replay، data-replay-sample-rate، data-realtime و data-auto-subscribe-push دیگر نادیده گرفته می‌شوند؛ می‌توانید روی تگ بمانند یا حذفشان کنید.

تنها ویژگی اختیاری باقی‌مانده data-debug="true" است که هنگام عیب‌یابی، پیام‌های تشخیصی نصب را در کنسول مرورگر نشان می‌دهد.

نکته‌های یکپارچه‌سازی

• اسکریپت را یک‌بار لود کنید — یک تگ async در <head>. روی هر مسیر دوباره تزریق نکنید.
• window.leadara.init() را صدا نزنید وقتی تگ اسکریپت روی صفحه است — SDK خودکار بالا می‌آید. init() دستی ممکن است اتصال زندهٔ تکراری باز کند.
• فقط به identify، track، group و page نیاز دارید — اتصال زنده یا هندلر ناوبری سمت خودتان لازم نیست.
• فقط تحلیل می‌خواهید؟ اگر پاپ‌آپ لحظه‌ای یا چت زنده ندارید ولی رویدادها (و در صورت نیاز بازپخش) را می‌خواهید، اتصال زنده را در ادغام‌ها ← SDK وب‌سایت خاموش کنید.

API

کلید نوشتن را در هر درخواست به https://api.leadara.ir در هدر x-write-key بفرستید.

curl -X POST 'https://api.leadara.ir/track' \
  -H 'x-write-key: WRITE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"userId":"user-123","name":"purchase_completed","properties":{"total":249000}}'

مسیرها: POST /track، /page، /screen، /identify، /group، /alias و /batch (تا ۱۰۰ رویداد یک‌جا). هر رویداد به userId و/یا anonymousId نیاز دارد. پاسخ‌ها به شکل { "success": true, "data": … } هستند — پیش از خواندن data روی success شرط بگذارید.

راهنمای قابل‌دانلود بالا شامل ساختار کامل درخواست‌ها، کدهای خطا، ارسال دسته‌ای و نام‌های پیشنهادی رویداد است — همان نسخه‌ای که باید به دستیار کدنویسی هوش مصنوعی‌تان بدهید.

نکته‌ها

• قبل از logged_in در همان بارگذاری صفحه identify را صدا بزنید و email و/یا phone را بفرستید تا مسیرهای ایمیلی/پیامکی بتوانند برسند. track ویژگی نمی‌آورد — مسیر از پروفایل می‌خواند، نه از رویداد ورود.
• در بالا آمدن اپ، اگر نشست از قبل وجود دارد، identify را با ویژگی‌های پایگاه کاربران خودتان صدا بزنید (نه فقط هنگام ورود تازه). کاربران برگشتی اغلب صفحهٔ ورود را نمی‌بینند.
• نام‌های پایدار و snake_case برای رویدادها (signed_up، purchase_completed) و جزئیات در properties. اتوماسیون‌ها نام را دقیق (حساس به حروف بزرگ/کوچک) مطابقت می‌دهند.
• روی تبدیل کلیدی یک مقدار عددی بفرستید (مثل total) تا تحلیل درآمد به‌صورت آماده کار کند.
• در وب، اسنیپت را ترجیح بدهید — بازدیدکنندهٔ ناشناس، نشست‌ها و تلاش مجدد را برایتان مدیریت می‌کند.

راهنمای قابل‌دانلود هوش مصنوعی را برای نمونه‌های کامل ورود، بازیابی نشست و پیش‌نیازهای پیامک/ایمیل ببینید.