راهنمای اتصال اسکریپت گزارشگیری رویدادهای تبلیغاتی به وبسایت فروشگاه
راهنمای افزودن اسکریپت گزارشگیری رویدادهای تبلیغاتی به وبسایت و ارسال پارامترهای موردنیاز در درخواست Payment Token
کدام فروشگاهها باید این تغییرات را انجام دهند؟
فروشگاههای ووکامرسی
اگر وبسایت شما ووکامرسی است، کافی است افزونه را از پنل پذیرندگان بهروزرسانی کنید و مطمئن شوید نسخه نصبشده ۱.۵.۰ یا بالاتر است. تمام تغییرات موردنیاز در افزونه اعمال شدهاند و نیازی به اقدام دیگری ندارید.
فروشگاههای دارای اتصال اختصاصی
فروشگاههایی که اتصال اختصاصی دارند باید دو تغییر زیر را انجام دهند:
- اسکریپت گزارشگیری رویدادها را به فوتر وبسایت اضافه کنند.
- اطلاعات انتساب را هنگام دریافت Payment Token در فیلد
adsParametersارسال کنند.
مرحله اول: افزودن اسکریپت گزارشگیری رویدادها به فوتر سایت
کد زیر را در فوتر مشترک وبسایت و درست پیش از تگ بسته </body> قرار دهید:
<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()در اختیار فروشگاه قرار میدهد.
مرحله دوم: ارسال پارامترهای تبلیغاتی در درخواست Payment Token
هنگام دریافت Payment Token، فروشگاه باید اطلاعات انتساب را از اسکریپت دریافت و از فرانتاند به بکاند خود ارسال کند. بکاند فروشگاه نیز باید این اطلاعات را در آبجکت adsParameters درخواست Payment Token قرار دهد.
adsParameters به بدنه درخواست است.۱ دریافت اطلاعات انتساب از اسکریپت
برای دریافت اطلاعات ذخیرهشده، از تابع آماده spt.getAttribution() استفاده کنید:
const attribution = spt.getAttribution();
در صورت وجود اطلاعات معتبر، خروجی این تابع ساختاری مشابه نمونه زیر دارد:
{
attributionId: "<ATTRIBUTION_ID>",
sessionId: "<SESSION_ID>",
capturedAt: 1763370000000
}
برای ساخت adsParameters فقط از دو مقدار زیر استفاده کنید:
| خروجی اسکریپت | فیلد ارسالی | |
|---|---|---|
attributionId | ← | spt_aid |
sessionId | ← | spt_sid |
capturedAt نباید در درخواست Payment Token ارسال شود.۲ ارسال اطلاعات به بکاند در درخواستهای AJAX
اگر فرایند پرداخت با fetch یا درخواست AJAX انجام میشود، اطلاعات انتساب را بهشکل زیر به بکاند ارسال کنید:
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() استفاده کنید:
const paymentForm = document.querySelector("#payment-form");
spt.decorateForm(paymentForm);
این تابع در صورت وجود اطلاعات انتساب، فیلدهای مخفی spt_aid و spt_sid را به فرم اضافه میکند. بکاند میتواند این دو مقدار را از دادههای فرم دریافت کند.
۴ افزودن اطلاعات به درخواست Payment Token
بکاند باید مقادیر دریافتشده از فرانتاند را در فیلد adsParameters قرار دهد:
{
"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را ارسال نکنید.
مطالب مرتبط:
خلاصه تغییرات موردنیاز
فروشگاههای دارای اتصال اختصاصی فقط باید دو تغییر انجام دهند:
- اسکریپت گزارشگیری رویدادها را در فوتر مشترک تمام صفحات وبسایت اضافه و
spt.init()را اجرا کنند. - هنگام شروع پرداخت، اطلاعات را با
spt.getAttribution()یاspt.decorateForm()دریافت کرده و از طریق بکاند داخل آبجکتadsParametersدرخواست Payment Token ارسال کنند.
© ۱۴۰۵ · تمامی حقوق محفوظ است.

