> For the complete documentation index, see [llms.txt](https://monthly-calender-widgets.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://monthly-calender-widgets.gitbook.io/docs/calendars-and-events/google-calendar.md). # Google Calendar (OAuth) Google Calendar sync is an optional feature designed for users who want **exact Google event colors** and a **deep offline archive** of their events. ## Why use it * **Exact Google colors** -- Events appear in the same colors as they do on calendar.google.com. No approximation. * **All Google calendars** -- View every calendar in your Google account together. * **Large event window** -- A single sync downloads **3 years of data** (2 years past + 1 year future), giving you a comprehensive archive. * **Offline access** -- After syncing, events are stored locally on your device. Widgets render your calendar without an internet connection. * **Widget color support** -- Google event colors are rendered correctly in Home Screen widgets, including custom widgets when **Preserve Event Colors** is enabled (**Edit any widget -> Display Options**). Only Google has a direct, separate API integration in the app. Other providers (Outlook, Exchange, Yahoo, and others) are accessed through iOS Calendar when those accounts are added to iOS. ## How to connect 1. Open the app and go to **Settings** (Profile tab). 2. Under **Data Sources**, tap **Google Calendar**. 3. Tap **Connect Google Account**. 4. A Google sign-in page opens in your browser. Sign in with your Google account. 5. Review the permissions and tap **Allow**. The app requests read access to your calendars. 6. You'll be returned to the app. Tap **Sync Now** to fetch your events. ### What happens during sync * The app calls the Google Calendar API to fetch events from all your calendars. * Event data (titles, times, colors, calendar names, optional locations) is downloaded and stored locally on your device. * OAuth tokens are stored securely in the iOS Keychain. * The sync process may take a few seconds to a minute depending on the number of events. ## Sync limits * **Free accounts:** up to **2 Google syncs per week**. * **Pro:** **unlimited** Google syncing for normal use, so your widgets always stay fresh. Subject to light fair-use safeguards against abuse (a \~1 minute cooldown between syncs and a generous daily safety cap), which are not expected to affect normal use. ### Why a free limit exists * A single sync fetches about 3 years of events and stores them on your device, so the data is comprehensive and works offline — you rarely need to refresh more than a couple of times a week. * Most users only need to sync when they've changed their Google Calendar (added, edited, or deleted events). * Pro removes the limit entirely for people who want their widgets refreshed as often as they like. ### When to sync * After adding new events in Google Calendar. * After editing or deleting events. * After receiving new calendar invitations. * Once at the beginning of the week as a routine refresh. ### What counts as a sync Each time you tap **Sync Now**, it counts as one sync attempt. Failed syncs (due to network errors) may also count depending on how far the request progressed. ## Conflict behavior If you edit a Google Calendar event locally inside the app, and then perform a Google sync, the app needs to decide which version of the event to keep. You can configure this behavior in **Settings** > **Optional Settings** > **Google Sync Conflict**: | Setting | Behavior | | ----------------------- | -------------------------------------------------------------------------------------------- | | **Ask every time** | The app prompts you to choose during sync | | **Keep my edits** | Local changes are preserved. Google data does not overwrite events you've edited locally | | **Restore from Google** | Google data takes priority. Any local edits are discarded and replaced with Google's version | This setting only affects events that you've edited locally. Events you haven't touched are always updated with the latest Google data. ## Disconnecting Google To disconnect your Google account: 1. Go to **Settings** > **Data Sources** > **Google Calendar**. 2. Tap **Disconnect**. Disconnecting removes: * Stored OAuth tokens from the iOS Keychain. * Cached Google Calendar events from local storage. * The connected account information. Your Google Calendar data on Google's servers is not affected. ## Privacy and security * The app uses Google OAuth (browser-based sign-in). **We never see or store your Google password.** * OAuth tokens are stored in the iOS Keychain, which is encrypted by iOS. * Calendar data fetched from Google is stored only on your device. We do not upload it to any server. * You can revoke the app's access to your Google account at any time from your [Google Account security settings](https://myaccount.google.com/permissions). ## Common issues ### Sync fails or hangs * Check your internet connection. * Ensure you haven't exceeded the free weekly sync limit (2 syncs/week; Pro is unlimited). * Try disconnecting and reconnecting your Google account.### Wrong Google account connected- Disconnect the current account (Settings > Data Sources > Google Calendar > Disconnect). <<<<<<< Updated upstream * Reconnect and sign in with the correct account.<<<<<<< HEAD ### Colors don't match Google- Make sure you're using Google Calendar as a data source (not just iOS Calendar with a Google account added to iOS). * In custom widgets, go to **Edit any widget -> Display Options -> Preserve Event Colors** and toggle it on. ======= ### Colors don't match Google- Make sure you're using Google Calendar as a data source (not just iOS Calendar with a Google account added to iOS). * In custom widgets, ensure "Preserve event colors" is enabled. > > > > > > > e71208b79c5b95a1b709d0ac33eebc38a42789e0 ======= * Reconnect and sign in with the correct account.### Colors don't match Google- Make sure you're using Google Calendar as a data source (not just iOS Calendar with a Google account added to iOS). * In custom widgets, ensure "Preserve event colors" is enabled. > > > > > > > Stashed changes --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://monthly-calender-widgets.gitbook.io/docs/calendars-and-events/google-calendar.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.