📅

Calendar Feeds & Integration Manual

Comprehensive Step-by-Step Instructions for Connecting Any iCalendar (.ics) or Webcal Source

⚡ Supported Calendar Types

Family Hub supports any calendar provider that exports an industry-standard RFC 5545 iCalendar (ICS) or Webcal feed. This includes Google Calendar, Apple iCloud, Microsoft Outlook / Office 365, TeamSnap, SportsEngine, GameChanger, Canvas LMS, and public school district schedules.

1. Google Calendar Integration

Google Calendar is one of the most common calendar services. To link a Google Calendar without making it viewable to the entire public internet, you must retrieve the Secret address in iCal format.

⚠️ Use the Secret Address, NOT the Public Address

Google generates two separate iCal addresses: Public address and Secret address. Unless you intentionally made your calendar publicly searchable, the "Public address" will return an empty feed or HTTP 404 error. Always copy the "Secret address in iCal format".

Step-by-Step Instructions:

1

Open Google Calendar on Desktop

Open calendar.google.com in a desktop web browser (these settings are not fully accessible via the mobile app).

2

Locate the Calendar in "My calendars"

On the left-hand sidebar, find the calendar you wish to sync under My calendars. Hover your mouse over the calendar name and click the three vertical dots (⠇ Options).

3

Select "Settings and sharing"

Click Settings and sharing from the dropdown menu to open the calendar's configuration page.

4

Navigate to "Integrate calendar"

In the left-hand navigation column, click Integrate calendar (or scroll down until you see the section titled Integrate calendar).

5

Copy the "Secret address in iCal format"

Locate the box labeled Secret address in iCal format. Click the copy icon or highlight the URL. The URL format looks like this:

https://calendar.google.com/calendar/ical/your_email%40gmail.com/xxxxxx...xxxxxx/basic.ics

6

Paste into Family Hub

Open Family Hub, click Settings (⚙️) ➔ Add Calendar, enter a label (e.g. "Dad Work" or "Tanner"), paste the secret URL, choose a color, and click Save.

2. Apple iCloud Calendar Integration

Apple devices use CalDAV and Webcal protocols for iCloud Calendars. Family Hub includes native automatic URL protocol translation, so you can paste either webcal:// or https:// links directly into the dashboard.

Option A: From an iPhone or iPad

1

Open the iOS Calendar App

Tap the default Calendar app on your home screen.

2

Tap "Calendars" at the Bottom

At the center bottom of your screen, tap the Calendars button to view all active iCloud and local calendars.

3

Tap the Info Icon (ℹ️)

Find the calendar you want to sync (e.g., "Family" or "Home") and tap the red circle (ℹ️) icon next to its name.

4

Enable "Public Calendar"

Scroll down to the Public Calendar toggle and switch it to ON (green). When prompted, tap Share Link....

5

Copy the Link

Select Copy from the iOS share sheet. The link will begin with webcal://pXX-caldav.icloud.com/published/2/....

6

Paste into Family Hub

Paste the copied link directly into the Family Hub Add Calendar drawer. Family Hub automatically normalizes the webcal:// scheme to high-speed secure https://.

Option B: From macOS (Mac Calendar App)

1

Open Calendar on Mac

Open the Apple Calendar app. If the sidebar is hidden, click View ➔ Show Calendar List.

2

Click the Broadcast Icon

Hover over the iCloud calendar you wish to share and click the broadcast/silhouette share icon next to it.

3

Check "Public Calendar" & Copy URL

Check the box for Public Calendar. A URL starting with webcal:// will appear. Right-click or copy the link and paste it into Family Hub.

3. Microsoft Outlook & Office 365

Microsoft allows you to publish an ICS feed for work, personal (Outlook.com), and school Microsoft 365 accounts.

Step-by-Step Instructions:

1

Log in to Outlook on the Web

Navigate to outlook.live.com or your corporate outlook.office.com portal.

2

Open Settings

Click the Settings gear icon (⚙️) in the top-right toolbar, then select View all Outlook settings.

3

Go to Shared Calendars

Select Calendar on the left, then click Shared calendars.

4

Publish a Calendar

Under the Publish a calendar section:

Select the calendar you want to export.
Set permissions to Can view all details (so event titles and times display on the hub).
Click Publish.

5

Copy the ICS Link

Two links will appear: HTML and ICS. Click the ICS link and choose Copy link. Paste this URL into Family Hub.

4. Youth Sports & School Calendars

Never miss a kickoff, practice change, or school late start! Most modern athletic platforms and learning management systems provide real-time subscription links:

⚽ TeamSnap

Log into TeamSnap on the web or mobile app ➔ Navigate to Schedule ➔ Click Subscribe / Export ➔ Copy the iCal link.

⚾ SportsEngine

Navigate to your child's team page ➔ Click the Schedule tab ➔ Click Options ➔ iCal ➔ Copy the subscription URL.

🥎 GameChanger

Open Team Settings in the GameChanger app ➔ Tap Sync Schedule ➔ Choose Subscribe to Calendar and copy the URL.

🎓 Canvas LMS & School Districts

In Canvas, click Calendar in the global navigation bar ➔ Click Calendar Feed at the bottom right ➔ Copy the personal iCal feed link.

5. Color Palettes & Contrast Engine

A critical feature of Family Hub is visual clarity. When 3 or 4 calendars overlap on a single day, distinguishing mom's schedule, dad's work, and the kids' soccer practices requires distinct color coding.

🎨 Harmonious Contrast Generation

When you select a primary color for a calendar feed in Settings, Family Hub does not just color the event text. The backend calculates an RGBA color triad:

Solid Accent Color: Used for the left indicator bar and primary text badge.
Tinted Background (12% opacity): Soft pastel background fill that works cleanly in both Light and Dark mode.
Translucent Border (35% opacity): Subtle boundary definition ensuring high contrast against the calendar day card.

Recommended Color Assignments:

Category / Member	Recommended Hex	Sample Preview	Tone Description
Dad / Work	`#3B82F6`	Blue	High-contrast cobalt blue for primary work and personal appointments.
Family Shared	`#F97316`	Warm Orange	Warm coral/orange for family dinners, birthdays, and household events.
Sports & Events	`#10B981`	Emerald Green	Vibrant emerald green for soccer, gymnastics, piano, and practices.
School & District	`#8B5CF6`	Purple	Distinct violet for school holidays, parent-teacher conferences, and testing days.

6. 15-Minute Sync Engine & Midnight Rollover

Wall kiosks run 24 hours a day, 7 days a week. Family Hub contains specialized background automation to ensure the display stays accurate without manual page reloads:

Automatic 15-Minute Background Daemon:

Every 15 minutes, the Python WSGI background worker iterates through all active calendars across all households:

Fetches updated .ics files with HTTP cache-busting headers (?_cb=timestamp) to bypass proxy caching.
Saves a local cached copy in /data/cache_<id>.ics. If an external calendar provider is temporarily down or rate-limiting requests, Family Hub serves the cached version seamlessly with zero downtime.
Evaluates recurring event expansion (RRULEs) for the next 60 days using the recurring_ical_events engine.

Instant On-Demand Sync:

Whenever you edit or add a calendar in the Settings drawer, the backend immediately triggers an eager synchronous fetch for that feed so your new events appear within seconds. You can also tap the 🔄 Sync Feeds button on the dashboard at any time.

Automatic Midnight Rollover:

🌙 Autonomous Midnight Day Advance

A wall kiosk should never wake up at 7:00 AM displaying yesterday's agenda! Family Hub includes a precision client-side midnight scheduler. At 00:00:01 local time, the dashboard automatically updates the current date calculation, shifts the "Today" highlight chip, advances the selected day view, and requests fresh calendar feeds without requiring a browser refresh.

7. Troubleshooting Feeds

Symptom	Probable Cause	Recommended Fix
Google Calendar shows 0 events	The "Public address" was copied instead of the "Secret address in iCal format".	In Google Calendar Settings ➔ Integrate calendar, scroll down to the Secret address in iCal format box and copy that URL.
Apple iCloud link fails to connect	"Public Calendar" was not toggled ON, or the link was truncated.	Verify that the Public Calendar toggle is green in Apple Calendar. Ensure the link contains the full `published/2/...` token.
All events appear shifted by hours	Timezone mismatch between calendar provider and server.	Family Hub operates on `America/Denver` (Mountain Time) and parses UTC timestamps (`DTSTART:...Z`) automatically. Verify your Google or Apple calendar timezone matches your home timezone.
Changes made on phone don't show immediately	Apple and Google servers can take 5-15 minutes to publish changes to their public/secret ICS feeds.	This delay is upstream at Apple/Google. Once their servers update the feed, tap Sync Feeds on Family Hub to ingest it immediately.