تقویم گوگل

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

پس از آن، هر کسی که از میترا استفاده می‌کند حساب گوگل خودش را از داخل برنامه وصل می‌کند، هر کدام با اجازه دسترسی خودشان. راه‌اندازی سه مرحله دارد:

1. ثبت میترا در گوگل.
2. دادن شناسه کلاینت و رمز محرمانه به میترا.
3. اتصال یک حساب.

دو مرحله اول را برای هر سرور میترا یک بار انجام می‌دهید.

ثبت میترا در گوگل

1. در Google Cloud console یک پروژه بسازید و زیر APIs & Services، CalDAV API را فعال کنید.

2. OAuth consent screen را پیکربندی کنید. یا خودتان و همه کسانی را که حسابی وصل می‌کنند به‌عنوان test user اضافه کنید، یا برنامه را منتشر کنید.

3. یک OAuth client از نوع Web application بسازید. به‌عنوان authorized redirect URI، نشانی سرور میترایتان را به‌همراه /api/integrations/google/callback وارد کنید:

   https://mitra.example.com/api/integrations/google/callback

4. client ID و client secret را که گوگل نشان می‌دهد کپی کنید.

CAUTION

تا وقتی صفحه consent در حالت آزمایشی است، گوگل هر اجازه دسترسی را پس از ۷ روز پایان می‌دهد و همه باید هر هفته حسابشان را دوباره وصل کنند. برای ماندگار ماندن اجازه‌ها، برنامه را منتشر کنید.

دادن شناسه کلاینت و رمز محرمانه به میترا

آن‌ها را به‌صورت متغیرهای محیطی همراه با MITRA_URL، نشانی سرورتان، تنظیم کنید:

services:
  mitra:
    image: ghcr.io/a11delavar/mitra:latest
    environment:
      MITRA_URL: 'https://mitra.example.com'
      MITRA_GOOGLE_CLIENT_ID: '….apps.googleusercontent.com'
      MITRA_GOOGLE_CLIENT_SECRET: '…'
    # …

سپس میترا را دوباره راه‌اندازی کنید:

docker compose up -d

هر دو متغیر را تنظیم کنید یا هیچ‌کدام را. میترا با شناسه کلاینت بدون رمز محرمانه اجرا نمی‌شود، تا راه‌اندازی نیمه‌کاره هرگز نادیده نماند.

MITRA_URL باید با نشانی redirect URI شما یکی باشد. بدون آن، میترا از نشانی‌ای که با آن بازش کرده‌اید استفاده می‌کند، که برای امتحان روی localhost کافی است. گوگل برای هر چیزی جز localhost فقط نشانی‌های ارجاع https:// را می‌پذیرد، پس یک سرور واقعی به HTTPS و MITRA_URL نیاز دارد. همه متغیرها در پیکربندی فهرست شده‌اند.

اتصال یک حساب

1. در پایین نوار کناری افزودن یکپارچه‌سازی و سپس تقویم گوگل را انتخاب کنید.
2. ادامه با گوگل را بزنید. گوگل از شما می‌خواهد حسابی را انتخاب کنید و به میترا اجازه دهید تقویم‌هایتان را ببیند و تغییر دهد.
3. در بازگشت به میترا، تقویم‌های حساب همه روشن فهرست شده‌اند. تیک آن‌هایی را که نمی‌خواهید بردارید و ذخیره را بزنید.

وصل کردن دوباره همان حساب گوگل، به جای افزودن دوباره آن، اجازه دسترسی‌اش را تمدید می‌کند.

گوگل تعداد فراخوانی برنامه‌ها را محدود می‌کند، پس میترا حساب‌های گوگل را حدود یک بار در دقیقه همگام می‌کند (همگام‌سازی چگونه کار می‌کند را ببینید).

تقویم‌هایی که با شما به اشتراک گذاشته شده‌اند

تقویم‌هایی که صاحبشان هستید به محض اتصال ظاهر می‌شوند. تقویم‌هایی که دیگران با شما به اشتراک گذاشته‌اند، مثل تقویم یک تیم یا همکار، فقط وقتی به برنامه‌های دیگر می‌رسند که در تنظیمات گوگلتان اجازه دهید:

1. در حالی که وارد گوگل شده‌اید، calendar.google.com/calendar/syncselect را باز کنید.
2. زیر Shared Calendars، هر تقویمی را که در میترا می‌خواهید تیک بزنید و Save را بزنید.
3. در میترا، منوی ⋯ حساب را در نوار کناری باز کنید، ویرایش را انتخاب کنید و تازه‌سازی را بزنید.
4. تقویم‌هایی را که ظاهر می‌شوند روشن کنید و ذخیره را بزنید.

تقویمی که با شما به‌عنوان See all event details به اشتراک گذاشته شده باشد در میترا فقط‌خواندنی است: همه چیز آن را می‌بینید، اما نمی‌توانید رویدادی اضافه، تغییر یا حذف کنید. اگر صاحبش بعداً Make changes to events را به شما بدهد، ویرایش با همگام‌سازی بعدی روشن می‌شود. تقویم‌های فقط‌خواندنی را ببینید.

چه چیزهایی همگام می‌شود

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

در دسترس بودن که در یک تقویم گوگل مشغول علامت بزنید به‌صورت رویدادهای مشغول به همان تقویم اضافه می‌شود، تا دیگران زمان را اشغال ببینند. همان‌طور که برای CalDAV توضیح داده شد کار می‌کند.

توکن گوگل شما

توکنی که گوگل صادر می‌کند هرگز سرور را ترک نمی‌کند. مرورگر شما فقط از صفحه گوگل می‌گذرد تا دسترسی بدهد. میترا توکن را همراه حساب نگه می‌دارد و هر بار که همگام می‌کند از آن برای گرفتن دسترسی کوتاه‌مدت استفاده می‌کند.

قطع اتصال یک حساب

برای برداشتن حساب و توکنش از میترا، حذف را در منوی ⋯ حساب انتخاب کنید. برای گرفتن دسترسی میترا از سمت گوگل هم، میترا را از اتصال‌های شخص ثالث حساب گوگل خود حذف کنید. فقط همین کار را کردن هم همگام‌سازی را متوقف می‌کند: حساب در میترا می‌ماند، اما هر همگام‌سازی شکست می‌خورد تا دوباره وصلش کنید.

عیب‌یابی

• اگر با انتخاب تقویم گوگل به جای دکمه ادامه با گوگل یادداشتی می‌بینید که روی این سرور پیکربندی نشده است، MITRA_GOOGLE_CLIENT_ID و MITRA_GOOGLE_CLIENT_SECRET تنظیم نشده‌اند، یا میترا از زمان تنظیم آن‌ها دوباره راه‌اندازی نشده است.
• اگر گوگل با redirect_uri_mismatch پاسخ می‌دهد، redirect URI در Google Cloud console با MITRA_URL به‌همراه /api/integrations/google/callback یکی نیست. باید دقیقاً یکی باشد، از جمله https:// و بدون اسلش پایانی.
• اگر حساب‌ها پس از ۷ روز همگام نمی‌شوند، صفحه consent شما هنوز در حالت آزمایشی است. برنامه را منتشر کنید و سپس حساب‌ها را دوباره وصل کنید.