راهنمای اتصال اسکریپت گزارش‌گیری رویدادهای تبلیغاتی به وب‌سایت فروشگاه

2بار مشاهده شده

راهنمای اتصال اسکریپت گزارش‌گیری رویدادهای تبلیغاتی به وب‌سایت فروشگاه

راهنمای افزودن اسکریپت گزارش‌گیری رویدادهای تبلیغاتی به وب‌سایت و ارسال پارامترهای موردنیاز در درخواست Payment Token

زمان مطالعه: ۵ دقیقه مناسب برای: تیم فنی فروشگاه‌های آنلاین

کدام فروشگاه‌ها باید این تغییرات را انجام دهند؟

فروشگاه‌های ووکامرسی

اگر وب‌سایت شما ووکامرسی است، کافی است افزونه را از پنل پذیرندگان به‌روزرسانی کنید و مطمئن شوید نسخه نصب‌شده ۱.۵.۰ یا بالاتر است. تمام تغییرات موردنیاز در افزونه اعمال شده‌اند و نیازی به اقدام دیگری ندارید.

فروشگاه‌های دارای اتصال اختصاصی

فروشگاه‌هایی که اتصال اختصاصی دارند باید دو تغییر زیر را انجام دهند:

  1. اسکریپت گزارش‌گیری رویدادها را به فوتر وب‌سایت اضافه کنند.
  2. اطلاعات انتساب را هنگام دریافت Payment Token در فیلد adsParameters ارسال کنند.

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

کد زیر را در فوتر مشترک وب‌سایت و درست پیش از تگ بسته </body> قرار دهید:

HTML
<script src="https://web-cdn.snapppay.ir/fms-merchant-promotion/scripts/spt.js"></script>

<script>
  spt.init({
    merchant: "<YOUR_MERCHANT_ENGLISH_NAME>"
  });
</script>
مقدار <YOUR_MERCHANT_ENGLISH_NAME> را با نام انگلیسی اختصاص‌یافته به فروشگاه خود جایگزین کنید.
اسکریپت باید در تمام صفحات، از جمله صفحه اصلی، صفحات فرود، صفحه محصول، سبد خرید و تسویه‌حساب بارگذاری شود.

اسکریپت پس از اجرا چه کارهایی انجام می‌دهد؟

پس از اجرای spt.init()، اسکریپت به‌صورت خودکار:

  • مقادیر spt_aid و spt_sid را از آدرس صفحه دریافت می‌کند.
  • اطلاعات انتساب را برای استفاده در صفحات بعدی نگه می‌دارد.
  • پارامترهای ثبت‌شده را از نوار آدرس حذف می‌کند.
  • رویداد ورود کاربر به وب‌سایت را ثبت می‌کند.
  • اطلاعات انتساب را از طریق تابع spt.getAttribution() در اختیار فروشگاه قرار می‌دهد.
مرچنت نیازی به پیاده‌سازی جداگانه برای ذخیره‌سازی یا خواندن مستقیم اطلاعات از localStorage ندارد.

مرحله دوم: ارسال پارامترهای تبلیغاتی در درخواست Payment Token

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

در نسخه قبلی، این اطلاعات همراه درخواست توکن ارسال نمی‌شد. تغییر جدید، اضافه‌شدن adsParameters به بدنه درخواست است.

۱ دریافت اطلاعات انتساب از اسکریپت

برای دریافت اطلاعات ذخیره‌شده، از تابع آماده spt.getAttribution() استفاده کنید:

JavaScript
const attribution = spt.getAttribution();

در صورت وجود اطلاعات معتبر، خروجی این تابع ساختاری مشابه نمونه زیر دارد:

Output
{
  attributionId: "<ATTRIBUTION_ID>",
  sessionId: "<SESSION_ID>",
  capturedAt: 1763370000000
}

برای ساخت adsParameters فقط از دو مقدار زیر استفاده کنید:

خروجی اسکریپتفیلد ارسالی
attributionId←spt_aid
sessionId←spt_sid
فیلد capturedAt نباید در درخواست Payment Token ارسال شود.

۲ ارسال اطلاعات به بک‌اند در درخواست‌های AJAX

اگر فرایند پرداخت با fetch یا درخواست AJAX انجام می‌شود، اطلاعات انتساب را به‌شکل زیر به بک‌اند ارسال کنید:

JavaScript
const attribution = spt.getAttribution();
const adsParameters = {};

if (attribution?.attributionId) {
  adsParameters.spt_aid = attribution.attributionId;
}
if (attribution?.sessionId) {
  adsParameters.spt_sid = attribution.sessionId;
}

await fetch("YOUR_BACKEND_ENDPOINT", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "same-origin",
  body: JSON.stringify({
    orderId: "<ORDER_ID>",
    adsParameters: Object.keys(adsParameters).length ? adsParameters : null
  })
});

۳ ارسال اطلاعات با فرم HTML

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

JavaScript
const paymentForm = document.querySelector("#payment-form");
spt.decorateForm(paymentForm);

این تابع در صورت وجود اطلاعات انتساب، فیلدهای مخفی spt_aid و spt_sid را به فرم اضافه می‌کند. بک‌اند می‌تواند این دو مقدار را از داده‌های فرم دریافت کند.

۴ افزودن اطلاعات به درخواست Payment Token

بک‌اند باید مقادیر دریافت‌شده از فرانت‌اند را در فیلد adsParameters قرار دهد:

JSON
{
  "amount": 25000000,
  "paymentMethodTypeDto": "INSTALLMENT",
  "returnURL": "https://merchant.example/payment/callback",
  "transactionId": "<TRANSACTION_ID>",
  "cartList": [],
  "discountAmount": 0,
  "adsParameters": {
    "spt_aid": "<ATTRIBUTION_ID>",
    "spt_sid": "<SESSION_ID>"
  }
}
آبجکت adsParameters فقط می‌تواند شامل spt_aid و spt_sid باشد. هیچ فیلد دیگری نباید در این آبجکت ارسال شود.

نکات مهم پیاده‌سازی

  • برای دریافت اطلاعات از spt.getAttribution() استفاده کنید و localStorage را مستقیماً نخوانید.
  • اسکریپت بررسی اعتبار و انقضای اطلاعات ذخیره‌شده را انجام می‌دهد.
  • در صورت مسدودبودن localStorage، اسکریپت می‌تواند از cookie به‌عنوان مسیر جایگزین استفاده کند.
  • فقط spt_aid و spt_sid را از فرانت‌اند بپذیرید و نام فیلدها را تغییر ندهید.
  • نوع و مقدار ورودی‌ها را در بک‌اند بررسی کنید.
  • اطلاعات یک کاربر یا نشست را به سفارش کاربر دیگری متصل نکنید.
  • اگر spt.getAttribution() مقدار معتبری برنگرداند، فیلد adsParameters را ارسال نکنید.
نبودن اطلاعات انتساب نباید باعث توقف فرایند پرداخت شود.

خلاصه تغییرات موردنیاز

فروشگاه‌های دارای اتصال اختصاصی فقط باید دو تغییر انجام دهند:

  1. اسکریپت گزارش‌گیری رویدادها را در فوتر مشترک تمام صفحات وب‌سایت اضافه و spt.init() را اجرا کنند.
  2. هنگام شروع پرداخت، اطلاعات را با spt.getAttribution() یا spt.decorateForm() دریافت کرده و از طریق بک‌اند داخل آبجکت adsParameters درخواست Payment Token ارسال کنند.
اشتراک گذاری