توسعه‌دهندگان
توسعه بر پایهٔ لایهٔ یکپارچه‌سازی هما متا
مرجع فنی جریان OAuth، مدیریت وب‌هوک، چرخهٔ عمر توکن، مدل مجوزها و معنای خطاها در پلتفرم متای هما.
پلتفرم متای هما میان APIهای کسب‌وکاری متا و هما CRM قرار می‌گیرد. این بخش توضیح می‌دهد که مجوزدهی چگونه آغاز می‌شود، توکن‌ها چگونه نگهداری می‌شوند، رویدادهای وب‌هوک چگونه تأیید می‌شوند و خطاها چگونه نمایش داده می‌شوند. مخاطب این متن مهندسانی هستند که این پلتفرم را یکپارچه یا بازبینی می‌کنند.
موضوعات مرجع
هر موضوع طرح مورد نظر، بخش‌هایی که به تأیید متا وابسته‌اند و حالت‌های خطایی که باید مدیریت کنید را پوشش می‌دهد.
جریان OAuth
ساخت درخواست مجوزدهی، مدیریت redirect URI، پارامتر state، محافظت CSRF و تبادل کد مجوزدهی در سمت سرور.
مطالعهٔ مرجع OAuthدامنهٔ مجوزها
انتخاب مجوزها بر پایهٔ کمینهٔ دسترسی، تفاوت دسترسی استاندارد و پیشرفته، انتظارات App Review و عوامل نیاز به مجوزدهی مجدد.
مطالعهٔ مرجع مجوزهاوبهوکها
الزامات نقطهٔ پایانی HTTPS، چالش تأیید، بررسی امضای payload، حذف تکرار، idempotency و رفتار تلاش مجدد.
مطالعهٔ مرجع وبهوکهاتوکنهای دسترسی
مفاهیم توکن کوتاهمدت و بلندمدت، رمزنگاری در حالت ذخیره، چرخش، انقضا، ابطال و جداسازی مستأجران.
مطالعهٔ مرجع توکنهاحذف داده
حذف به درخواست کاربر، چرخهٔ عمر درخواست حذف، شمارهٔ پیگیری، انتظارات ردگیری و موارد استثنای نگهداری.
مطالعهٔ مرجع حذف دادهمدیریت خطا
لغو مجوزدهی، state نامعتبر، نبود مجوز لازم، انقضای توکن، ابطال دسترسی، محدودیت نرخ و قطعی سرویس بالادست.
مطالعهٔ مرجع خطاها
متغیرهای محیطی
مقادیر با دامنهٔ سرور تنها در کد سمت سرور خوانده می‌شوند و هرگز به مرورگر ارسال نمی‌شوند. مقادیر با پیشوند NEXT_PUBLIC_ در بستهٔ سمت کلاینت قرار می‌گیرند و هرگز نباید اعتبارنامه نگه دارند.
| NEXT_PUBLIC_SITE_URL | عمومی | مبدأ canonical برای فراداده، ورودی‌های sitemap و پیوندهای مطلق. |
|---|---|---|
| NEXT_PUBLIC_HOMA_URL | عمومی | مقصد کنش «ورود به هما CRM» در ناوبری. |
| META_AUTHORIZATION_BASE_URL | فقط سرور | نشانی پایهٔ گفت‌وگوی مجوزدهی متا (مثلاً https://www.facebook.com). نشانی کامل مجوزدهی در سمت سرور از این مقدار به‌همراه نسخهٔ API ساخته می‌شود. اگر تنظیم نشده باشد، صفحهٔ اتصال به‌جای آغاز جریان، اطلاعیهٔ پیکربندی نشان می‌دهد. |
| META_API_VERSION | فقط سرور | نسخهٔ Graph API برای ساخت نشانی‌های گفت‌وگوی مجوزدهی و تبادل توکن (مثلاً v21.0). |
| META_APP_ID | فقط سرور | شناسهٔ عمومی اپ که در سمت سرور به‌عنوان client_id در درخواست مجوزدهی ارسال می‌شود. |
| META_CONFIG_ID | فقط سرور | شناسهٔ پیکربندی Facebook Login for Business. دامنه‌های نمایش‌داده‌شده در صفحهٔ رضایت متا را تعیین می‌کند. |
| META_REDIRECT_URI | فقط سرور | نشانی بازگشت ثبت‌شده در اپ متا، بدون اسلش پایانی. باید به /api/auth/meta/callback اشاره کند و حرف‌به‌حرف با مقدار ثبت‌شده یکسان باشد. |
| META_APP_SECRET | فقط سرور | تنها برای تبادل توکن در سمت سرور و بررسی امضای وب‌هوک استفاده می‌شود. هرگز به کلاینت ارسال یا در گزارش‌ها ثبت نمی‌شود. |
| HOMA_INTERNAL_API_URL | فقط سرور | نقطهٔ پایانی بک‌اند که نتیجهٔ مجوزدهی برای ذخیره‌سازی ایمن به آن تحویل می‌شود. اگر تنظیم نشده باشد، callback به‌جای جعل اتصال، مقدار storage_not_configured بازمی‌گرداند. |
| HOMA_INTERNAL_API_KEY | فقط سرور | اعتبارنامهٔ Bearer برای تحویل داخلی به بک‌اند هما. |
| META_WEBHOOK_VERIFY_TOKEN | فقط سرور | رشتهٔ مشترک که در چالش تأیید وب‌هوک مقایسه می‌شود. |
| RESEND_API_KEY | فقط سرور | ارسال اطلاع‌رسانی درخواست‌های تماس و حذف را فعال می‌کند. اگر تنظیم نشده باشد، فرم‌ها به‌جای اعلام موفقیت، مسیر جایگزین ایمیلی نشان می‌دهند. |
| DATA_DELETION_EMAIL | فقط سرور | صندوق دریافت درخواست‌های حذف داده. |
| CONTACT_EMAIL | فقط سرور | صندوق دریافت پیام‌های عمومی تماس. |
اصول پیاده‌سازی
این محدودیت‌ها در سراسر لایهٔ یکپارچه‌سازی اعمال می‌شوند و بازتاب آن‌ها در هر کلاینت مصرف‌کننده ارزشمند است.
اعتبارنامه‌ها در سمت سرور می‌مانند
رمز اپ و توکن‌های دسترسی تنها در کد سمت سرور خوانده می‌شوند. هیچ اعتبارنامه‌ای در کامپوننت کلاینت، نشانی، پیام خطا یا خط گزارش قرار نمی‌گیرد.
مجوزدهی همیشه از سرور آغاز می‌شود
مرورگر رضایت کاربر را به یک مسیر سروری ارسال می‌کند؛ سرور مقدار state را می‌سازد، آن را به‌صورت کوکی HttpOnly تنظیم می‌کند و بازگردانی را انجام می‌دهد. کلاینت هرگز نشانی مجوزدهی را نمی‌سازد.
به payload بدون امضا اعتماد نمی‌شود
هر تحویل پیش از تجزیه یا اثرگذاری، با امضای خود بررسی می‌شود. خطاهای تأیید حذف و ثبت می‌شوند، نه آنکه کورکورانه تلاش مجدد شوند.
هر درخواست به مستأجر محدود ا��ت
دارایی‌ها و توکن‌های ذخیره‌شده شناسهٔ مستأجر دارند و پرس‌وجوها بر آن فیلتر می‌شوند تا مجوزدهی یک مشتری هرگز به دادهٔ مشتری دیگر نرسد.
خطاها صادقانه نمایش داده می‌شوند
وقتی یک وابستگی پیکربندی یا در دسترس نباشد، رابط کاربری آن را اعلام می‌کند و مسیر جایگزین قابل استفاده ارائه می‌دهد؛ برای کاری که انجام نشده، موفقیت گزارش نمی‌کند.
خواندن وضعیت قابلیت‌ها
مستندات هر قابلیت را برچسب‌گذاری می‌کند تا تفاوت آنچه امروز فعال است با آنچه به تصمیم متا وابسته است روشن باشد.
از مرور معماری آغاز کنید
بخش شروع کار، پیکربندی اپ، نشانی‌های لازم و جداسازی محیط‌ها را پیش از نخستین تلاش مجوزدهی پوشش می‌دهد.