> 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/sync-offline.md).

# Sync rules & offline

## How the two sources work together

Monthly Calendar Widgets recommends using **both** iOS Calendar and Google Calendar for the most complete experience:

* **iOS Calendar** handles automatic, real-time updates. When you add, edit, or delete events on your device (or via iCloud/Outlook/Exchange/Yahoo sync configured in iOS), iOS Calendar reflects the changes immediately with no manual action.
* **Google Calendar** provides exact color coding and a deep offline archive. Each sync downloads 3 years of events that are stored locally.

Only Google is supported as a separate direct API source. Other providers are accessed through iOS Calendar integration.

When both sources are active, the app merges events intelligently to avoid duplicate display. Events from both sources appear together in widgets and in-app views.

## Sync behavior by source

| Source          | Update method         | Frequency                                | Internet required?     |
| --------------- | --------------------- | ---------------------------------------- | ---------------------- |
| iOS Calendar    | Automatic (EventKit)  | Real-time as events change               | No (data is local)     |
| Google Calendar | Manual (tap Sync Now) | Free: up to 2x per week · Pro: unlimited | Yes (during sync only) |

## Offline mode

### iOS Calendar

iOS Calendar data is always available offline. Events are stored on your device by iOS, and the app reads them directly via EventKit. No internet connection is needed at any time.

### Google Calendar

After a Google sync, all fetched events are saved locally on your device. This means:

* Widgets can render your Google Calendar events without an internet connection.
* The app displays Google events even in airplane mode.
* Colors, event details, and calendar names are all preserved locally.

The only time internet is needed is during the sync itself (when the app communicates with Google's servers).

## When to sync Google Calendar

Sync is most useful in these situations:

* **After adding new events** in Google Calendar (on the web, phone, or another device).
* **After editing or deleting events** that need to be reflected in the app.
* **After receiving new calendar invitations** that you've accepted.
* **Weekly routine** -- Many users sync once at the start of the week to ensure everything is up to date.

You don't need to sync constantly. Since each sync downloads 3 years of data, your local copy is comprehensive and stays relevant for days or weeks between syncs.

## How widgets get their dataWidgets on iOS run as a separate process (a widget extension) that cannot always access Calendar data directly. To solve this:1. The app writes a lightweight "snapshot" of upcoming events to a shared **App Group** container on your device.

2. The widget extension reads this snapshot to render your calendar.
3. The snapshot includes event titles, times, all-day status, calendar names, colors, and any custom settings needed for display.This shared storage stays entirely on your device and is not sent to any server.### When the snapshot updates- When you open the app (foreground refresh).

* When you change any setting (theme, color, calendar toggle).
* When iOS Calendar data changes (EventKit notification).
* After a Google sync completes.
* When iOS grants the widget extension background refresh time.### If a widget looks stale1. **Open the app** -- This triggers an immediate snapshot update.

2. **Change any setting** -- Toggle a theme or color and back. This forces a widget refresh.
3. **Remove and re-add the widget** -- This clears the widget's cache and forces a fresh load.
4. **Restart your device** -- As a last resort, a restart clears all widget caches.


---

# 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/sync-offline.md?ask=<question>
```

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.