شروع به کار

نمای کلی معماری

هما متا پلتفرم یک لایهٔ یکپارچه‌سازی بدون حالت است. فرایند احراز دسترسی با متا را مدیریت می‌کند و رویدادهای استانداردشده را به هما CRM تحویل می‌دهد. هیچ اعتبارنامهٔ متا هرگز به مرورگر نمی‌رسد.

لایهٔ وب عمومی: همین وب‌سایت. صفحات معرفی، حقوقی و مستندات توسعه‌دهندگان را ارائه می‌کند و نقطهٔ ورود ‎/connect را برای شروع درخواست احراز دسترسی در اختیار می‌گذارد.
سرویس احراز دسترسی: یک مسیر صرفاً سمت سرور که نشانی احراز دسترسی متا را می‌سازد، کوکی state امضاشده را تنظیم می‌کند و سپس کد احراز دسترسی را با توکن مبادله می‌کند. تنها روی سرور اجرا می‌شود.
گیرندهٔ وب‌هوک: یک نقطهٔ پایانی HTTPS که امضای هر بار داده را بررسی می‌کند، رویدادهای تکراری را حذف می‌کند و آن‌ها را برای پردازش در صف قرار می‌دهد.
مخزن توکن: ذخیره‌سازی رمزنگاری‌شدهٔ توکن‌های بلندمدت، جداشده به ازای هر مستأجر. توکن‌ها هرگز در گزارش‌ها ثبت نمی‌شوند و به هیچ کلاینتی بازگردانده نمی‌شوند.
هما CRM: محصول مصرف‌کننده. گفت‌وگوها، دیدگاه‌ها و رکوردهای مخاطب استانداردشده را از طریق APIهای داخلی دریافت می‌کند.

جریان درخواست

کاربر وارد‌شده به هما CRM صفحهٔ ‎/connect را در این سایت باز می‌کند.
کاربر سیاست حفظ حریم خصوصی و شرایط استفاده از خدمات را می‌پذیرد. دکمهٔ ارسال تا پذیرش هر دو مورد غیرفعال می‌ماند.
مرورگر درخواست POST را به یک مسیر سمت سرور ارسال می‌کند. آن مسیر یک مقدار state تصادفی می‌سازد، آن را در کوکی HttpOnly ذخیره می‌کند و کاربر را به متا هدایت می‌کند.
کاربر مستقیماً در متا احراز هویت می‌کند و دارایی‌های واجد شرایط مورد نظر را انتخاب می‌کند. هما هرگز این اعتبارنامه‌ها را نمی‌بیند.
متا کاربر را همراه با یک کد احراز دسترسی به نشانی بازگشت پیکربندی‌شده هدایت می‌کند.
سرور مقدار state بازگشتی را با کوکی مقایسه و اعتبارسنجی می‌کند، سپس کد را در یک تماس سرور‌به‌سرور با توکن دسترسی مبادله می‌کند.
توکن رمزنگاری و به نام مستأجر ذخیره می‌شود. کاربر در صفحهٔ ‎/authorized فرود می‌آید.

پیکربندی لازم اپلیکیشن متا

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

تنظیم	مقدار
دامنهٔ اپلیکیشن	meta.homacrm.com
نشانی سایت	https://meta.homacrm.com
نشانی بازگشت مجاز OAuth	https://meta.homacrm.com/authorized
نشانی فراخوان لغو دسترسی	https://meta.homacrm.com/api/meta/deauthorize
نشانی درخواست حذف داده	https://meta.homacrm.com/api/meta/data-deletion
نشانی سیاست حفظ حریم خصوصی	https://meta.homacrm.com/privacy
نشانی شرایط استفاده از خدمات	https://meta.homacrm.com/terms
راهنمای حذف داده‌های کاربر	https://meta.homacrm.com/data-deletion

متغیرهای محیطی

تنها مقادیری که با ‎NEXT_PUBLIC_‎ آغاز می‌شوند در کد مرورگر قابل دسترسی هستند. سایر موارد فقط سمت سرور هستند. برای محیط توسعه، فایل ‎.env.example را به ‎.env.local کپی کنید.

.env.local

# عمومی — انتشار آن در مرورگر بی‌خطر است
NEXT_PUBLIC_SITE_URL=https://meta.homacrm.com
NEXT_PUBLIC_HOMA_URL=https://www.homacrm.com

# فقط سمت سرور — نقطهٔ پایانی احراز دسترسی و هویت اپلیکیشن
META_AUTHORIZATION_URL=
META_APP_ID=
META_REDIRECT_URI=https://meta.homacrm.com/authorized

# فقط سمت سرور — هرگز منتشر نکنید و پیشوند NEXT_PUBLIC_ نگذارید
META_APP_SECRET=

# ایمیل تراکنشی برای فرم‌های تماس و حذف داده
RESEND_API_KEY=
CONTACT_EMAIL=support@homacrm.com
DATA_DELETION_EMAIL=privacy@homacrm.com
SUPPORT_EMAIL=support@homacrm.com
SECURITY_EMAIL=security@homacrm.com

سایت در غیاب متغیرهای اختیاری به‌صورت کنترل‌شده کار می‌کند. اگر ‎META_AUTHORIZATION_URL تنظیم نشده باشد، صفحهٔ ‎/connect به‌جای بروز خطا توضیح می‌دهد که احراز دسترسی هنوز پیکربندی نشده است. اگر ‎RESEND_API_KEY تنظیم نشده باشد، فرم‌ها نشانی ایمیل جایگزین و یک شمارهٔ پیگیری نشان می‌دهند و ارسالی را که رخ نداده است گزارش نمی‌کنند.

جداسازی محیط توسعه و تولید

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