<img src="https://brands.home-assistant.io/familylink/icon.png" alt="Google Family Link" width="30" > Google Family Link Home Assistant Integration

[![GitHub Release][releases-shield]][releases] [![License][license-shield]][license] [![HACS][hacs-shield]][hacs]

A comprehensive Home Assistant integration for monitoring and controlling Google Family Link devices. Track screen time, manage time limits, control bedtime/school schedules, and manage time bonuses directly from Home Assistant.

🚨 Important Disclaimer

This integration uses unofficial, reverse-engineered Google Family Link API endpoints. Use at your own risk. This may violate Google's Terms of Service and could result in account suspension. This project is not affiliated with, endorsed by, or connected to Google LLC.

✨ Features

📱 Device Control

• Lock/Unlock Devices - Control device access with switches in Home Assistant
• Real-time Synchronization - Lock state automatically syncs with Google Family Link
• Multi-device Support - Manage multiple supervised devices
• Bi-directional Control - Changes made in Family Link app reflect in Home Assistant

⏰ Time Management

• Bedtime Control - Enable/disable bedtime (downtime) restrictions
• Set Bedtime Schedule - Modify bedtime start/end times for any day (or today by default)
• School Time Control - Enable/disable school time restrictions
• Daily Limit Control - Enable/disable daily screen time limits (0-1440 minutes)
• Set Daily Limit - Change daily screen time limit duration per device
• Time Bonuses - Add extra time (15min, 30min, 60min) or cancel active bonuses
• Smart Detection - Automatically detects when device is in bedtime/school time window
• Schedule Visibility - View bedtime and school time schedules in sensor attributes

📊 Screen Time Monitoring

• Daily Screen Time - Track total daily usage per child
• Screen Time Remaining - See remaining time per device (accounts for bonuses and used time)
• Daily Limit Tracking - Monitor daily limit quota per device
• Active Bonus Display - See active time bonuses per device
• Top 10 Apps - Monitor most-used apps with detailed usage statistics
• App Breakdown - Per-application usage breakdown

📲 App Management

• Installed Apps Count - Total number of apps on supervised devices
• Blocked Apps - List and count of blocked/hidden apps
• Apps with Time Limits - Track apps with usage restrictions
• App Details - Package names, titles, and limit information
• 4 App States - Block, app limit off, set limit, or unlimited time per app

📍 GPS Location Tracking (Optional)

• Device Tracker - Track your child's location via device_tracker entity
• Place Detection - Automatically shows when child is at a saved place (Home, School, etc.)
• Address Display - Full address of current location
• Source Device - Shows which device provided the location
• Battery Level - Monitor battery percentage of the location source device
• On-Demand Refresh - Force a fresh GPS update from the child's device
• Privacy First - Disabled by default, opt-in via configuration
• ⚠️ Warning - Each location poll may notify the child's device

👶 Child Information

• Profile Details - Child's name, email, birthday, age band
• Device Information - Device model, name, capabilities, last activity
• Family Members - List of all family members with roles

📋 Available Entities

Per-Child Entities

Device Tracker (GPS Location - Optional)

• device_tracker.<child> - Child's GPS location
  • State: home, not_home, or zone name
  • Attributes:
    • source_device - Device name providing the location
    • place_name - Saved place name (e.g., "Home", "School")
    • address - Full address of the location
    • location_timestamp - When the location was captured
    • battery_level - Battery percentage of source device
  • Note: Requires enabling "GPS location tracking" in integration config

Battery Sensor (GPS Location - Optional)

• sensor.<child>_battery_level - Battery level of location source device
  • State: Battery percentage (0-100%)
  • Device Class: battery
  • Attributes:
    • source_device - Device name providing the battery data
    • last_update - Timestamp of last update
  • Note: Requires enabling "GPS location tracking" in integration config
  • ⚠️ Limitation: Shows battery of the device selected for location tracking in Family Link app, not all devices

Switches (Global Controls)

• switch.<child>_bedtime - Enable/disable bedtime restrictions
• switch.<child>_school_time - Enable/disable school time restrictions
• switch.<child>_daily_limit - Enable/disable daily screen time limit

Per-Device Entities

Sensors

• sensor.<device>_screen_time_remaining - Remaining screen time in minutes
• sensor.<device>_next_restriction - Next upcoming restriction (bedtime/school time)
• sensor.<device>_daily_limit - Daily limit quota in minutes
• sensor.<device>_active_bonus - Active time bonus in minutes

Binary Sensors

• binary_sensor.<device>_bedtime_active - Currently in bedtime window
  • Attributes: bedtime_start, bedtime_end (ISO timestamps)
• binary_sensor.<device>_school_time_active - Currently in school time window
  • Attributes: schooltime_start, schooltime_end (ISO timestamps)
• binary_sensor.<device>_daily_limit_reached - Daily limit reached (true/false, ignores bonuses)

Switches

• switch.<device> - Lock/unlock device
  • ON = Device unlocked (child can use device) 📱
  • OFF = Device locked (device is locked) 🔒

Buttons

• button.<device>_15min - Add 15 minutes bonus
• button.<device>_30min - Add 30 minutes bonus
• button.<device>_60min - Add 60 minutes bonus
• button.<device>_reset_bonus - Cancel active bonus (only available when bonus is active)

Legacy Sensors (Child Level)

• sensor.<child>_daily_screen_time - Daily screen time in minutes
• sensor.<child>_screen_time_formatted - Daily screen time in HH:MM:SS format
• sensor.<child>_installed_apps - Number of installed apps
• sensor.<child>_blocked_apps - Number and list of blocked apps
• sensor.<child>_apps_with_time_limits - Apps with usage restrictions
• sensor.<child>_top_app_1 through sensor.<child>_top_app_10 - Top 10 most-used apps
• sensor.<child>_device_count - Number of supervised devices
• sensor.<child>_child_info - Supervised child's profile information

🎯 What's New

Unlimited Time Mode for Apps (#79)

The set_app_daily_limit service now supports all 4 Family Link app states:

# Set app to unlimited time (ignores device daily limits)
service: familylink.set_app_daily_limit
data:
  package_name: com.zhiliaoapp.musically
  minutes: -2

# Disable app limit (follows device limits)
service: familylink.set_app_daily_limit
data:
  package_name: com.zhiliaoapp.musically
  minutes: -1

# Set 60 min/day limit
service: familylink.set_app_daily_limit
data:
  package_name: com.zhiliaoapp.musically
  minutes: 60

On-Demand Location Refresh (#78)

New refresh_location service to force a fresh GPS update from the child's device:

service: familylink.refresh_location
data:
  entity_id: device_tracker.emma

Per-App Daily Time Limits (#59)

set_app_daily_limit service to control screen time per application.

Multi-Child Support (#57)

App control services apply to ALL children by default. Use entity_id or child_id to target a specific child.

🏗️ Architecture

This project consists of two components that work together:

1. Family Link Auth Add-on (familylink-playwright/)

Provides secure, browser-based authentication:

• Playwright Automation - Headless Chromium for Google login
• 2FA Support - Handles SMS, authenticator, and push notifications
• Cookie Extraction - Securely stores authentication cookies
• Auto-refresh - Keeps authentication fresh

2. Home Assistant Integration (custom_components/familylink/)

Provides monitoring and control:

• Config Flow - User-friendly setup wizard
• API Client - Communicates with Google Family Link API
• Coordinator - Manages data updates and caching
• Entities - Sensors, binary sensors, switches, and buttons

Why Two Components?

Home Assistant's Docker environment restricts browser automation. The add-on runs in a separate container with Chromium and Playwright, while the integration handles data fetching and device control.

📦 Installation

See the detailed Installation Guide for step-by-step instructions.

📌 Note for Home Assistant Core/Container Users

If you're running Home Assistant without Supervisor (Core or Container installation), you'll need to run the authentication add-on as a standalone Docker container. See the Docker Standalone Guide for detailed instructions.

Quick Start (Home Assistant OS / Supervised)

1. Install Family Link Auth Add-on

• Add repository to Home Assistant
• Install and start the add-on
• Authenticate via Web UI (open noVNC in your browser - see Installation Guide)

2. Install Integration

• Via HACS (recommended) or manually