تا اینجا دربارهی UCP، MCP و GEO خواندید. این راهنما فنیترین بخش مسیر است: قدمبهقدم چطور این استانداردها را روی یک سایت فروشگاهی واقعی پیادهسازی کنید — از ساخت فایل اول تا تست نهایی.
پیشنیازها
- دسترسی به ریشهی دامنه برای آپلود فایل در مسیر
/.well-known/ - یک بکاند که بتواند اندپوینتهای JSON برگرداند (هر زبانی: PHP، Node.js، Python و ...)
- دسترسی HTTPS معتبر (اکثر ایجنتها اتصال HTTP ساده را نمیپذیرند)
ساختار پیشنهادی پوشهها
گام اول: ساخت فایل ucp.json
سریعترین راه، استفاده از ژنراتور رایگان UCP است: اطلاعات کسبوکار، نوع فعالیت و قابلیتهای موردنیاز را وارد کنید تا فایل کامل و آماده تولید شود. اگر ترجیح میدهید دستی بنویسید، حتماً فیلدهای protocol، merchant_name و capabilities را طبق مقالهی راهنمای UCP کامل کنید.
گام دوم: انتشار در مسیر درست
فایل باید دقیقاً در آدرس https://yoursite.com/.well-known/ucp در دسترس باشد و هدر Content-Type آن روی application/json تنظیم شده باشد. بسیاری از سرورها بهطور پیشفرض دسترسی به پوشهی .well-known را مسدود میکنند — حتماً این مورد را در تنظیمات وبسرور خود بررسی کنید.
گام سوم: پیادهسازی اندپوینتها
برای هر قابلیتی که در فایل UCP معرفی کردهاید (مثل search_offers یا initiate_checkout)، باید یک اندپوینت واقعی در بکاند بسازید که دقیقاً همان ساختار پاسخ تعریفشده را برگرداند. نکتهی مهم: پاسخها باید همیشه JSON معتبر و ساختیافته باشند، نه HTML یا متن آزاد.
گام چهارم: راهاندازی یک سرور MCP ساده
اگر میخواهید ایجنتها بتوانند به دادههای داخلیتان (مثل موجودی لحظهای انبار) دسترسی کنترلشده داشته باشند، طبق راهنمای MCP یک سرور مجزا با ابزارهای مشخص بسازید. توصیه میشود این سرور را از API عمومی سایت جدا نگه دارید تا مرز امنیتی واضحی داشته باشید.
گام پنجم: تست و اعتبارسنجی
- با دستور
curl -i https://yoursite.com/.well-known/ucpبررسی کنید پاسخ ۲۰۰ و JSON معتبر برمیگردد - خروجی JSON را در یک اعتبارسنج آنلاین بررسی کنید
- هر اندپوینت capability را جداگانه با Postman تست کنید
- زمان پاسخدهی اندپوینتها را بسنجید — ایجنتها معمولاً محدودیت زمانی کوتاهی دارند
- مطمئن شوید در صورت خطا، پاسخ JSON با پیام مشخص برمیگردد، نه صفحهی خطای HTML
نکات امنیتی که نباید فراموش کنید
- هرگز اطلاعات حساس پرداخت را مستقیماً در پاسخ UCP قرار ندهید؛ از درگاههای استاندارد پرداخت استفاده کنید
- برای اندپوینتهای حساس (مثل پرداخت)، احراز هویت و امضای درخواست را الزامی کنید
- روی همهی اندپوینتهای عمومی، محدودیت نرخ درخواست (Rate Limiting) اعمال کنید
- درخواستهای غیرعادی یا حجم بالا را لاگ و پایش کنید
یک اندپوینت تستنشده، بدتر از نداشتن آن اندپوینت است — چون اعتماد یک ایجنت را یکبار از دست میدهید و بهسختی بازمیگردد.
چکلیست نهایی پیادهسازی
- فایل ucp.json در مسیر /.well-known/ucp و با Content-Type درست منتشر شده
- همهی capabilities تعریفشده، اندپوینت واقعی و فعال دارند
- پاسخها همیشه JSON معتبر هستند، حتی در حالت خطا
- HTTPS فعال و گواهی معتبر است
- در صورت نیاز، سرور MCP با دسترسی محدود و کنترلشده راهاندازی شده
- تست نهایی با curl/Postman انجام و مستند شده است
سوالات متداول
چقدر زمان میبرد تا این مراحل را کامل کنم؟
ساخت و انتشار فایل UCP معمولاً کمتر از ده دقیقه طول میکشد. پیادهسازی کامل اندپوینتها بسته به پیچیدگی فروشگاه، از چند ساعت تا چند روز کاری متغیر است.
آیا باید همهی capabilities را همزمان پیاده کنم؟
نه. پیشنهاد میشود با search_offers و get_product_details شروع کنید و بهمرور قابلیتهای پیشرفتهتر مثل پرداخت را اضافه کنید.