رفتن به محتوا
مستنداتجست‌وجو در مستنداتفارسیبازگشت به سایتورود به کنسول

یکپارچه‌سازی‌ها و ماژول‌های CRM

یک پنل برای هر چیزی که یک ماژول بیرونی برای اتصال لازم دارد: افزونه WHMCS، شناسه های اتصال، کلید سرور برای ورود داده، و مقصد خروجی برای برگرداندن اتریبیوشن به CRM.

دو جهت، نه یکی#

در «مدیریت»، زیر گروه «وب‌سایت»، پنل «یکپارچه‌سازی‌ها» در مسیر /admin?sel=integrations است. کل صفحه حول دو جریان مخالف چیده شده و اگر این دو را از هم جدا نکنید، بقیه صفحه گیج‌کننده می‌شود:

جهت چه چیزی حرکت می‌کند با چه اعتبارنامه‌ای
CRM ← ادپیکس (ورودی) ثبت‌نام، ورود و سفارش، از سیستم شما به ادپیکس کلید سرور، با پیشوند sk_
ادپیکس ← CRM (خروجی) اتریبیوشن حل‌شده و رویدادهای کسب‌وکار، از ادپیکس به سیستم شما رمز مشترک، با پیشوند whs_

جهت ورودی است که به گزارش‌های ادپیکس درآمد واقعی می‌دهد. جهت خروجی است که به CRM شما می‌گوید هر مشتری از کدام کمپین آمده. یک نصب کامل هر دو را دارد، ولی می‌شود فقط یکی را راه انداخت.

یکپارچه‌سازی‌ها و ماژول‌های CRM: WHMCS، WooCommerce و وب‌هوک عمومی.
یکپارچه‌سازی‌ها و ماژول‌های CRM: WHMCS، WooCommerce و وب‌هوک عمومی.

سه گامی که خود صفحه می‌گوید#

کارت اول، «اتصال یک CRM در سه گام»، ترتیب کار را می‌دهد: ماژول را دانلود و فعال کنید، مقادیر اتصال این صفحه را در تنظیمات ماژول بگذارید، و در صورت نیاز یک مقصد خروجی اضافه کنید. سه بخش بعدی صفحه دقیقا همین سه گام‌اند.

دانلودها#

کارت «دانلودها و مستندات» دو چیز می‌دهد:

  • «ماژول WHMCS» — فایل .zip افزونه همراه. اگر ماژول روی این سرور همراه نصب نشده باشد، به‌جای دکمه، «روی این سرور موجود نیست» را می‌بینید؛ آن وقت باید با تیم پشتیبانی تماس بگیرید.
  • «قرارداد API سرور به سرور (S2S)» — سند OpenAPI. برای ووکامرس، وردپرس یا هر CRM خانگی همین سند کافی است؛ ماژول WHMCS هم دقیقا با همین قرارداد کار می‌کند.

مقادیر اتصال#

کارت «جزئیات اتصال» سه مقدار را با دکمه کپی می‌دهد، و نامشان عمدا با نام فیلدهای ماژول WHMCS یکی است:

مقدار در کنسول فیلد ماژول چیست
«اندپوینت کالکتور» Collector Endpoint آدرس پایه‌ای که ماژول صدا می‌زند
«شناسه وب‌سایت» Property ID در هدر X-Sov-Site فرستاده می‌شود
«شناسه تگ» Measurement ID فقط برای تگ داخل صفحه
جزئیات اتصال و کلیدهای سرور — کلید سرور فقط همین‌جا ساخته می‌شود و رمز آن تنها یک بار نمایش داده می‌شود.
جزئیات اتصال و کلیدهای سرور — کلید سرور فقط همین‌جا ساخته می‌شود و رمز آن تنها یک بار نمایش داده می‌شود.

کارت «جزئیات اتصال» همان سه شناسه‌ای را نشان می‌دهد که در دستورالعمل نصب تگ هم می‌بینید — «شناسه وب‌سایت»، «آدرس دریافت داده» و «شناسه تگ»، هر کدام با دکمه «کپی» خودش — و اگر وب‌سایت بیش از یک جریان داده دارد، انتخاب جریان داده هم همان‌جاست. زیر آن، کارت «کلیدهای سرور» است، برای API سرور به سرور تجارت الکترونیک (شناسایی، سفارش‌ها، اتریبیوشن). کلید سرور فقط همین‌جا ساخته و باطل می‌شود (پنل جریان داده فقط به اینجا لینک می‌دهد) و به یک جریان داده وصل است (اگر وب‌سایت بیش از یک جریان داده داشته باشد، کارت می‌پرسد کدام) و «سطوح دسترسی» مورد نیازش را هنگام ساخت تیک می‌زنید؛ در ابتدا هر چهار مورد تیک خورده‌اند. اگر «الزام امضای HMAC» را روشن کنید، همان مقدار sk_ هم کلید امضاست — ماژول WHMCS آن را در فیلد HMAC Secret می‌خواهد. رمز تازه فقط یک بار، در کادری برجسته با دکمه «کپی» خودش، نمایش داده می‌شود.

رمز فقط یک بار دیده می‌شود

از کلید سرور فقط یازده نویسه ابتدایی نگه داشته می‌شود و خود رمز به‌صورت درهم‌شده ذخیره می‌شود. اگر گمش کنید بازیابی نمی‌شود؛ باید کلید تازه بسازید و قبلی را «ابطال» کنید؛ ابطال پیش از انجام تایید می‌خواهد، چون از آن لحظه درخواست‌هایی که با آن کلید برسند پذیرفته نمی‌شوند. ساخت و ابطال هر دو در گزارش ممیزی ثبت می‌شوند.

شناسه تگ داخل قطعه کد اعتبارنامه نیست و API سرور به سرور آن را نمی‌پذیرد؛ فقط کلید سرور sk_ آنجا کار می‌کند. ساختن جریان داده هیچ کلیدی نمی‌سازد؛ هر وقت ماژولی لازم داشت، همین‌جا یکی بسازید. شرح کامل دامنه‌ها، هدرها و کدهای خطا در ردیابی سمت سرور.

افزونه WHMCS#

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

۱
فایل .zip را در <whmcs>/modules/addons/ از حالت فشرده خارج کنید.
۲
در WHMCS به 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 را روشن کنید. هر دو با هم نه — دوبار تگ گذاشتن یعنی دوبار شمردن.

در استقرار دودامنه‌ای، فیلد Tracker (CDN) URL را خالی نگذارید

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)» همان قرارداد است بدون افزونه. کارت «ارسال خروجی؛ ادپیکس ← CRM» را پر کنید:

۱
در «نام» چیزی بگذارید که در فهرست مقصدها قابل تشخیص باشد.
۲
در «نوع» یکی از سه گزینه را انتخاب کنید: «وب هوک عمومی (هر CRM / CMS)»، «WHMCS — افزونه همراه (توصیه شده)» یا «WHMCS — API مدیریتی (فیلدهای سفارشی)».
۳
آدرس گیرنده را وارد کنید.
۴
«افزودن مقصد» را بزنید. کارت «رمز مشترک — یک بار نمایش داده می‌شود» ظاهر می‌شود؛ همان لحظه مقدارش را در سیستم گیرنده بگذارید.

گیرنده شما یک POST با بدنه JSON می‌گیرد و رمز مشترک در هدر X-Sovereign-Secret می‌آید. آنچه فرستاده می‌شود فقط شناسایی کاربر و رویدادهای کسب‌وکار است — بازدید صفحه و رویدادهای تعامل هرگز به مقصد نمی‌روند. شکل کامل بدنه، امضای HMAC و قواعد تلاش دوباره در وب‌هوک‌ها و امضای HMAC.

جدول «مقصدهای پیکربندی شده» پایین صفحه هر مقصد را با «هدف» و کلید «وضعیت» نشان می‌دهد. برای قطع موقت، کلید وضعیت را خاموش کنید — حذف مقصد، تحویل‌های در انتظارش را هم پاک می‌کند.

«تعویض رمز» یک رمز مشترک تازه می‌سازد و یک بار نشان می‌دهد. رمز قدیمی همان لحظه بی‌اعتبار می‌شود، پس تا وقتی مقدار تازه را در گیرنده نگذاشته‌اید، تحویل‌ها با خطای احراز هویت رد می‌شوند و در صف تلاش دوباره می‌مانند.

دسترسی لازم#

دیدن این پنل با دسترسی خواندن گزارش ممکن است و کلیدهای سرور در فهرست فقط با پیشوندشان دیده می‌شوند. ساخت یا حذف مقصد، ساخت یا ابطال کلید و تعویض رمز، همگی اختیار ویرایش تنظیمات وب‌سایت می‌خواهند و در گزارش ممیزی ثبت می‌شوند.

پرسش‌های پرتکرار#

چه فرقی بین کلید سرور و رمز مشترک هست؟

جهتشان. کلید سرور با پیشوند sk_ برای ورود داده به ادپیکس است — ماژول با آن رویداد می‌فرستد. رمز مشترک با پیشوند whs_ برای خروج داده از ادپیکس است — ورکر با آن خودش را به گیرنده شما معرفی می‌کند. هر دو فقط یک بار نمایش داده می‌شوند و جای هم به کار نمی‌روند.

چرا سفارش‌ها در پنل WHMCS بیشتر از سفارش‌های واقعی بود؟

چون هر بازدید صفحه «پرداخت موفق» یک ردیف خرید می‌ساخت. حالا دو محافظ دارد: رویدادی که قاعده رویداد ساخته باشد تنها با شناسه تراکنش یا مقدار مثبت به CRM می‌رسد، و گیرنده افزونه شناسه سفارش را کلید یکتاسازی می‌کند. پنل هم شمار سفارش‌های یکتا را نشان می‌دهد، نه تعداد ردیف را.

می‌شود بدون افزونه WHMCS از هر CRM دیگری استفاده کرد؟

بله. مقصد «وب هوک عمومی (هر CRM / CMS)» همان بدنه‌ای را می‌فرستد که گیرنده WHMCS می‌گیرد، و برای ورود داده هم قرارداد سرور به سرور همان است که ماژول WHMCS به کار می‌برد. وردپرس، ووکامرس یا یک CRM خانگی از همین دو مسیر وصل می‌شوند.

رمز مشترک را گم کرده‌ام. می‌شود دوباره دید؟

نه. فقط یک نشانه کوتاه‌شده‌اش نگه داشته می‌شود. در سطر همان مقصد «تعویض رمز» را بزنید تا رمز تازه‌ای ساخته و یک بار نمایش داده شود، بعد همان را در ماژول جایگزین کنید. تا وقتی ماژول به‌روز نشده، تحویل‌ها با خطای احراز هویت رد می‌شوند.

با API بسازیدبفهمید درآمد از کجا می‌آید.
آیا این صفحه مفید بود؟