یکپارچهسازیها و ماژولهای CRM
یک پنل که هر چیزی را که یک ماژول بیرونی برای اتصال لازم دارد در همان یک صفحه میدهد: افزونه WHMCS، کلید سرور برای ورود داده، و مقصد خروجی برای برگرداندن اتریبیوشن به CRM.
دو جهت، نه یکی#
در «مدیریت»، زیر گروه «دارایی»، پنل «یکپارچه سازی ها و ماژولهای CRM» در مسیر /admin?sel=integrations است. کل صفحه حول دو جریان مخالف چیده شده و اگر این دو را از هم جدا نکنید، بقیه صفحه گیجکننده میشود:
| جهت | چه چیزی حرکت میکند | با چه اعتبارنامهای |
|---|---|---|
| CRM ← ادپیکس (ورودی) | ثبتنام، ورود و سفارش، از سیستم شما به ادپیکس | کلید سرور، با پیشوند sk_ |
| ادپیکس ← CRM (خروجی) | اتریبیوشن حلشده و رویدادهای کسبوکار، از ادپیکس به سیستم شما | رمز مشترک، با پیشوند whs_ |
جهت ورودی است که به گزارشهای ادپیکس درآمد واقعی میدهد. جهت خروجی است که به CRM شما میگوید هر مشتری از کدام کمپین آمده. یک نصب کامل هر دو را دارد، ولی میشود فقط یکی را راه انداخت.
سه گامی که خود صفحه میگوید#
کارت اول، «اتصال یک CRM در سه گام»، ترتیب کار را میدهد: ماژول را دانلود و فعال کنید، مقادیر اتصال این صفحه را در تنظیمات ماژول بگذارید، و در صورت نیاز یک مقصد خروجی اضافه کنید. سه بخش بعدی صفحه دقیقا همین سه گاماند.
دانلودها#
کارت «دانلودها و مستندات» دو چیز میدهد:
- «ماژول WHMCS» — فایل
.zipافزونه همراه. اگر ماژول روی این سرور همراه نصب نشده باشد، بهجای دکمه، «روی این سرور موجود نیست» را میبینید؛ آن وقت باید با تیم پشتیبانی تماس بگیرید. - «قرارداد API سرور به سرور (S2S)» — سند OpenAPI. برای ووکامرس، وردپرس یا هر CRM خانگی همین سند کافی است؛ ماژول WHMCS هم دقیقا با همین قرارداد کار میکند.
مقادیر اتصال#
کارت «جزئیات اتصال» سه مقدار را با دکمه کپی میدهد، و نامشان عمدا با نام فیلدهای ماژول WHMCS یکی است:
| مقدار در کنسول | فیلد ماژول | چیست |
|---|---|---|
| «اندپوینت کالکتور» | Collector Endpoint |
آدرس پایهای که ماژول صدا میزند |
| «شناسه دارایی» | Property ID |
در هدر X-Sov-Site فرستاده میشود |
| «شناسه اندازهگیری» | Measurement ID |
فقط برای تگ داخل صفحه |
زیر همین کارت، کارت «کلیدهای سرور — S2S تجارت الکترونیک (شناسایی / سفارش ها / اتریبیوشن)» است. کلید سرور به یک جریان داده وصل است و «دامنهها»ی مورد نیازش را هنگام ساخت تیک میزنید. اگر «نیازمند HMAC» را تیک بزنید، همان مقدار sk_ هم کلید امضاست — ماژول WHMCS آن را در فیلد HMAC Secret میخواهد.
از کلید سرور فقط یازده نویسه ابتدایی نگه داشته میشود و خود رمز بهصورت درهمشده ذخیره میشود. اگر گمش کنید بازیابی نمیشود؛ باید کلید تازه بسازید و قبلی را «ابطال» کنید. ساخت و ابطال هر دو در گزارش ممیزی ثبت میشوند.
کلید نوشتن جریان داده — همانی که در قطعه کد تگ میآید — کلید سرور نیست و API سرور به سرور آن را نمیپذیرد. شرح کامل دامنهها، هدرها و کدهای خطا در ردیابی سمت سرور.
افزونه WHMCS#
افزونه دوطرفه است: هم رویداد به ادپیکس میفرستد، هم اتریبیوشن را از ادپیکس میگیرد و کنار پرونده مشتری نگه میدارد.
.zip را در <whmcs>/modules/addons/ از حالت فشرده خارج کنید.Setup → Addon Modules بروید و «AdPix Analytics» را فعال کنید. جدولهای محلی افزونه همانجا ساخته میشوند و فعالسازی دوباره بیخطر است.Collector Endpoint، Property ID و Server Key را از همین صفحه کنسول کپی کنید. اگر کلید سرور نیازمند HMAC است، همان مقدار را در HMAC Secret هم بگذارید.Enable Capture را روشن کنید — کلید اصلی همه قلابهاست و بهصورت پیشفرض خاموش است.Default Calling Code را پر کنید (برای ایران 98) تا شماره 09… به همان شکل بینالمللیای نرمال شود که تگ داخل صفحه میسازد. بدون این، سفر وب و پرونده صورتحساب یک نفر به هم وصل نمیشوند.با روشن بودن Enable Capture، افزونه این لحظهها را میفرستد:
| اتفاق در WHMCS | چه چیزی به ادپیکس میرود |
|---|---|
| ثبت مشتری تازه | شناسایی — ثبتنام به سفر ناشناس همان نفر وصل میشود |
| ورود مشتری | شناسایی دوباره، برای وصل کردن دستگاههای تازه |
| پرداخت سفارش | خرید، با نوع سفارش تازه یا تکراری |
| پرداخت فاکتور تمدید | خرید، با نوع تمدید — همین است که ارزش طول عمر را میسازد |
| بازپرداخت یا لغو فاکتور | بهروزرسانی روی همان سفارش؛ عکس اتریبیوشن دستنخورده میماند |
قلابها کوکیهای فرستپارتی __sov_aid، __sov_ft و __sov_lt را میخوانند تا سفارش را به بازدید ناشناسی که پیش از ثبتنام رخ داده وصل کنند. برای اینکه این کوکیها روی دامنه صورتحساب وجود داشته باشند، یا باید تگ را خودتان آنجا نصب کرده باشید یا Inject Tracker را روشن کنید. هر دو با هم نه — دوبار تگ گذاشتن یعنی دوبار شمردن.
Inject Tracker قطعه تگ را از روی Collector Endpoint میسازد. در استقراری که دامنه دریافت رویداد از دامنه تحویل فایل تگ جداست، آن آدرس فایل t.js را سرو نمیکند و اسکریپت 404 میگیرد. آدرس CDN را در Tracker (CDN) URL بگذارید. خالی گذاشتنش فقط در استقرار تکدامنهای درست است.
هیچ قلابی نمیتواند خطا را به مسیر درخواست WHMCS پرت کند؛ اگر ادپیکس در دسترس نباشد، ثبتنام و پرداخت مشتری بدون خم به ابرو ادامه پیدا میکند و فقط سنجش آن لحظه از دست میرود.
گزارشها داخل خود WHMCS#
افزونه یک صفحه گزارش با زبانههای Overview، Channels، Source / Campaign، First vs Last، New vs Returning، Cohorts، Clients، Unattributed و ROAS اضافه میکند. حقیقت درآمد در این گزارشها صورتحساب خود WHMCS است که با شناسه مشتری به اتریبیوشن محلی وصل میشود — نه یک کپی از اعداد ادپیکس. کارت جمعبندی ادپیکس هم زیر پرونده هر مشتری در بخش مدیریت مینشیند و کانال، منبع و کمپین جذب او را نشان میدهد.
چرا یک سفارش دو بار شمرده نمیشود#
یک سفارش میتواند از دو مسیر به CRM برسد: یک بار از قلاب افزونه، و یک بار از تحویل خروجی ورکر. سه محافظ جلوی دوبار شمردن را میگیرند:
- دروازه سمت ادپیکس. رویدادی که یک قاعده رویداد از روی نشانی صفحه ساخته باشد، تنها وقتی به مقصدهای CRM فرستاده میشود که شناسه تراکنش یا سفارش داشته باشد، یا مقدار مثبتی حمل کند. بدون این، هر بازدید صفحه «پرداخت موفق» در CRM شما یک سفارش میشد. گزارشهای تحلیلی از این دروازه اثر نمیگیرند؛ ردیفشان به هر حال نوشته شده است.
- کلید یکتاسازی سمت گیرنده. گیرنده افزونه شناسه سفارش و شناسه فاکتور را از خصیصههای رویداد بیرون میکشد و اگر شناسه سفارش موجود باشد، همان را کلید یکتاسازی میکند. نتیجهاش این است که تحویل خروجی همان سفارش، روی ردیفی که قلاب محلی قبلا ساخته بود مینشیند، نه کنارش.
- شمارش در پنل. کارت مشتری تعداد سفارشهای یکتا را میشمارد، نه تعداد ردیف خرید را.
این سه محافظ از لحظه استقرار به بعد کار میکنند و ردیفهای قدیمی را پاک نمیکنند. برای پاکسازی گذشته، بهروزرسانی افزونه یک بار ردیفهای خرید بیهویت و بیمقدار را حذف میکند؛ ترتیب کامل کار را از تیم پشتیبانی بگیرید و پیش از هر پاکسازی نسخه پشتیبان بردارید.
هر CRM دیگری: وبهوک عمومی#
اگر WHMCS ندارید، مقصد «وب هوک عمومی (هر CRM / CMS)» همان قرارداد است بدون افزونه. کارت «تحویل خروجی — AdPix → CRM» را پر کنید:
گیرنده شما یک POST با بدنه JSON میگیرد و رمز مشترک در هدر X-Sovereign-Secret میآید. آنچه فرستاده میشود فقط شناسایی کاربر و رویدادهای کسبوکار است — بازدید صفحه و رویدادهای تعامل هرگز به مقصد نمیروند. شکل کامل بدنه، امضای HMAC و قواعد تلاش دوباره در وبهوکها و امضای HMAC.
جدول «مقصدهای پیکربندی شده» پایین صفحه هر مقصد را با «هدف» و کلید «وضعیت» نشان میدهد. برای قطع موقت، کلید وضعیت را خاموش کنید — حذف مقصد، تحویلهای در انتظارش را هم پاک میکند.
«تعویض رمز» یک رمز مشترک تازه میسازد و یک بار نشان میدهد. رمز قدیمی همان لحظه بیاعتبار میشود، پس تا وقتی مقدار تازه را در گیرنده نگذاشتهاید، تحویلها با خطای احراز هویت رد میشوند و در صف تلاش دوباره میمانند.
دسترسی لازم#
دیدن این پنل با دسترسی خواندن گزارش ممکن است و کلیدهای سرور در فهرست فقط با پیشوندشان دیده میشوند. ساخت یا حذف مقصد، ساخت یا ابطال کلید و تعویض رمز، همگی اختیار ویرایش تنظیمات دارایی میخواهند و در گزارش ممیزی ثبت میشوند.
پرسشهای پرتکرار#
چه فرقی بین کلید سرور و رمز مشترک هست؟
جهتشان. کلید سرور با پیشوند sk_ برای ورود داده به ادپیکس است — ماژول با آن رویداد میفرستد. رمز مشترک با پیشوند whs_ برای خروج داده از ادپیکس است — ورکر با آن خودش را به گیرنده شما معرفی میکند. هر دو فقط یک بار نمایش داده میشوند و جای هم به کار نمیروند.
چرا سفارشها در پنل WHMCS بیشتر از سفارشهای واقعی بود؟
چون هر بازدید صفحه «پرداخت موفق» یک ردیف خرید میساخت. حالا دو محافظ دارد: رویدادی که قاعده رویداد ساخته باشد تنها با شناسه تراکنش یا مقدار مثبت به CRM میرسد، و گیرنده افزونه شناسه سفارش را کلید یکتاسازی میکند. پنل هم شمار سفارشهای یکتا را نشان میدهد، نه تعداد ردیف را.
میشود بدون افزونه WHMCS از هر CRM دیگری استفاده کرد؟
بله. مقصد «وب هوک عمومی (هر CRM / CMS)» همان بدنهای را میفرستد که گیرنده WHMCS میگیرد، و برای ورود داده هم قرارداد سرور به سرور همان است که ماژول WHMCS به کار میبرد. وردپرس، ووکامرس یا یک CRM خانگی از همین دو مسیر وصل میشوند.
رمز مشترک را گم کردهام. میشود دوباره دید؟
نه. فقط یک نشانه کوتاهشدهاش نگه داشته میشود. در سطر همان مقصد «تعویض رمز» را بزنید تا رمز تازهای ساخته و یک بار نمایش داده شود، بعد همان را در ماژول جایگزین کنید. تا وقتی ماژول بهروز نشده، تحویلها با خطای احراز هویت رد میشوند.
ممنون — بازخورد شما به بهتر شدن مستندات کمک میکند.