noiwid/HAFamilyLink

# Google Family Link Home Assistant 集成 [][releases] [][license] [][hacs] [](https://buymeacoffee.com/noiwid) 一个全面的 Home Assistant 集成，用于监控和控制 Google Family Link 设备。直接在 Home Assistant 中追踪屏幕使用时间、管理时间限制、控制就寝/上课时间安排以及管理时间奖励。 ## 🚨 重要免责声明 此集成使用非官方的、通过逆向工程获取的 Google Family Link API 端点。**使用风险自负**。这可能违反 Google 的服务条款，并可能导致账户被暂停。本项目与 Google LLC 无关、未获其认可，也未与其建立任何关联。 ## ✨ 功能特性 ### 📱 设备控制 - **锁定/解锁设备** - 通过 Home Assistant 中的开关控制设备访问 - **实时同步** - 锁定状态自动与 Google Family Link 同步 - **多设备支持** - 管理多个受监控设备 - **双向控制** - 在 Family Link 应用程序中所做的更改会反映在 Home Assistant 中 ### ⏰ 时间管理 - **就寝时间控制** - 启用/禁用就寝时间（停机时间）限制 - **设置就寝时间表** - 修改任何一天（或默认今天）的就寝开始/结束时间 - **上课时间控制** - 启用/禁用上课时间限制 - **每日限额控制** - 启用/禁用每日屏幕时间限制（0-1440 分钟） - **设置每日限额** - 更改每台设备的每日屏幕时间限制时长 - **时间奖励** - 添加额外时间（15分钟、30分钟、60分钟）或取消活动奖励 - **智能检测** - 自动检测设备是否处于就寝/上课时间窗口内 - **日程可见性** - 在传感器属性中查看就寝和上课时间表 ### 📊 屏幕时间监控 - **每日屏幕时间** - 追踪每个孩子的每日总使用时间 - **屏幕时间剩余** - 查看每台设备的剩余时间（已计入奖励和已用时间） - **每日限额追踪** - 监控每台设备的每日限额配额 - **活动奖励显示** - 查看每台设备的活动时间奖励 - **十大应用** - 监控最常用的应用，包含详细使用统计 - **应用使用分布** - 按应用程序的详细使用情况分解 ### 📲 应用管理 - **已安装应用数量** - 受监控设备上的应用总数 - **被阻止应用** - 被阻止/隐藏应用的数量和列表 - **有时间限制的应用** - 追踪有使用限制的应用 - **应用详情** - 包名、标题和限制信息 - **4种应用状态** - 阻止、关闭应用限制、设置限制或无限时间 ### 📍 GPS 位置追踪（可选） - **设备追踪器** - 通过 `device_tracker` 实体追踪您孩子的位置 - **地点检测** - 自动显示孩子何时处于已保存的地点（家、学校等） - **地址显示** - 当前位置的完整地址 - **来源设备** - 显示是哪个设备提供的位置信息 - **电池电量** - 监控位置来源设备的电池百分比 - **按需刷新** - 强制从孩子设备获取新的 GPS 更新 - **隐私优先** - 默认禁用，通过配置选择加入 - **⚠️ 警告** - 每次位置轮询可能会通知孩子的设备 ### 👶 儿童信息 - **个人资料详情** - 儿童的姓名、电子邮件、生日、年龄组 - **设备信息** - 设备型号、名称、功能、最后活动时间 - **家庭成员** - 所有家庭成员及其角色的列表 ## 📋 可用实体 ### 每个儿童的实体 #### 设备追踪器（GPS 位置 - 可选） - `device_tracker.` - 儿童的 GPS 位置 - **状态**: `home`、`not_home` 或区域名称 - **属性**: - `source_device` - 提供位置信息的设备名称 - `place_name` - 已保存的地点名称（例如，“家”、“学校”） - `address` - 位置的完整地址 - `location_timestamp` - 位置信息捕获的时间 - `battery_level` - 来源设备的电池百分比 - **注意**: 需要在集成配置中启用“GPS 位置追踪” #### 电池传感器（GPS 位置 - 可选） - `sensor._battery_level` - 位置来源设备的电池电量 - **状态**: 电池百分比 (0-100%) - **设备类别**: `battery` - **属性**: - `source_device` - 提供电池数据的设备名称 - `last_update` - 上次更新的时间戳 - **注意**: 需要在集成配置中启用“GPS 位置追踪” - **⚠️ 局限性**: 显示的是在 Family Link 应用程序中为位置追踪选择的设备的电池电量，而不是所有设备 #### 开关（全局控制） - `switch._bedtime` - 启用/禁用就寝时间限制 - `switch._school_time` - 启用/禁用上课时间限制 - `switch._daily_limit` - 启用/禁用每日屏幕时间限制 ### 每台设备的实体 #### 传感器 - `sensor._screen_time_remaining` - 剩余屏幕时间（分钟） - `sensor._next_restriction` - 下一个即将到来的限制（就寝/上课时间） - `sensor._daily_limit` - 每日限额配额（分钟） - `sensor._active_bonus` - 活动时间奖励（分钟） #### 二进制传感器 - `binary_sensor._bedtime_active` - 当前是否处于就寝时间窗口 - 属性: `bedtime_start`, `bedtime_end` (ISO 时间戳) - `binary_sensor._school_time_active` - 当前是否处于上课时间窗口 - 属性: `schooltime_start`, `schooltime_end` (ISO 时间戳) - `binary_sensor._daily_limit_reached` - 是否达到每日限制 (true/false，忽略奖励) #### 开关 - `switch.` - 锁定/解锁设备 - **ON** = 设备解锁（孩子可以使用设备） 📱 - **OFF** = 设备锁定（设备被锁定） 🔒 #### 按钮 - `button._15min` - 添加 15 分钟奖励 - `button._30min` - 添加 30 分钟奖励 - `button._60min` - 添加 60 分钟奖励 - `button._reset_bonus` - 取消活动奖励（仅当有活动奖励时可用） ### 旧版传感器（儿童级别） - `sensor._daily_screen_time` - 每日屏幕时间（**分钟**） - `sensor._screen_time_formatted` - 每日屏幕时间（**HH:MM:SS** 格式） - `sensor._installed_apps` - 已安装应用的数量 - `sensor._blocked_apps` - 被阻止应用的数量和列表 - `sensor._apps_with_time_limits` - 有使用限制的应用 - `sensor._top_app_1` 至 `sensor._top_app_10` - 最常用的前 10 个应用 - `sensor._device_count` - 受监控设备的数量 - `sensor._child_info` - 受监控儿童的个人资料信息 ## 🎯 新增功能 ### 应用程序无限时间模式 (#79) `set_app_daily_limit` 服务现在支持 Family Link 的所有 4 种应用状态： ``` # 将应用设为无限时间（忽略设备每日限制） service: familylink.set_app_daily_limit data: package_name: com.zhiliaoapp.musically minutes: -2 # 禁用应用限制（遵循设备限制） service: familylink.set_app_daily_limit data: package_name: com.zhiliaoapp.musically minutes: -1 # 设置每天60分钟限制 service: familylink.set_app_daily_limit data: package_name: com.zhiliaoapp.musically minutes: 60 ``` ### 按需位置刷新 (#78) 新增 `refresh_location` 服务，可强制从孩子设备获取新的 GPS 更新： ``` service: familylink.refresh_location data: entity_id: device_tracker.emma ``` ### 按应用程序设置每日时间限制 (#59) `set_app_daily_limit` 服务，用于控制每个应用程序的屏幕时间。 ## 🏗️ 架构 此项目由两个协同工作的组件组成： ### 1. Family Link 认证插件 (`familylink-playwright/`) 提供安全的、基于浏览器的身份验证： - **Playwright 自动化** - 用于 Google 登录的无头 Chromium - **两步验证支持** - 处理短信、身份验证器和推送通知 - **Cookie 提取** - 安全存储身份验证 Cookie - **自动刷新** - 保持身份验证信息的新鲜度 ### 2. Home Assistant 集成 (`custom_components/familylink/`) 提供监控和控制功能： - **配置流程** - 用户友好的设置向导 - **API 客户端** - 与 Google Family Link API 通信 - **协调器** - 管理数据更新和缓存 - **实体** - 传感器、二进制传感器、开关和按钮 ### 为什么是两个组件？ Home Assistant 的 Docker 环境限制了浏览器自动化。插件在独立的容器中运行，包含 Chromium 和 Playwright，而集成则负责数据获取和设备控制。 ## 📦 安装 请参阅详细的[安装指南](INSTALL.md)获取分步说明。 ### 快速开始 (Home Assistant OS / Supervised) 1. **安装 Family Link 认证插件** [](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fnoiwid%2FHAFamilyLink) - 将仓库添加到 Home Assistant - 安装并启动插件 - 通过 Web UI 进行身份验证（在浏览器中打开 noVNC - 参见[安装指南](INSTALL.md)） 2. **安装集成** - 通过 HACS（推荐）或手动安装 - 通过 Home Assistant UI 进行配置 - Cookie 从插件自动加载 3. **开始使用！** - 监控屏幕时间 - 控制时间限制 - 管理奖励时间 - 创建自动化 ## ⚙️ 配置 此集成完全通过 Home Assistant UI（配置流程）进行配置。**不支持 YAML 配置。** ### 通过 UI 设置 1. 前往 **设置 → 设备与服务 → 添加集成** 2. 搜索 "**Family Link**" 并选择它 3. 在设置向导中配置以下选项： - **名称**: 集成的显示名称（默认: "Google Family Link"） - **更新间隔**: 获取数据的频率，以秒为单位（默认: 300，范围: 30-3600） - **超时**: API 请求超时时间，以秒为单位（默认: 30） - **启用 GPS 位置追踪**: 选择加入设备位置追踪（默认: 禁用） ### 更新间隔 默认更新间隔为 5 分钟（300 秒）。您可以在初始设置期间或重新配置集成时更改此值： 1. 前往 **设置 → 设备与服务** 2. 找到 Family Link 集成 3. 点击 **配置** 以修改设置 ### 锁定状态同步 设备状态从 Google 的 `appliedTimeLimits` API 端点获取。在 Family Link 应用程序或网站上所做的更改将在下一个更新周期内反映在 Home Assistant 中。 ## 🔧 使用的 API 端点 此集成使用通过逆向工程获取的 Google Family Link API 端点： | 端点 | 用途 | |------|------| | `/families/mine/members` | 家庭成员信息 | | `/families/mine/location/{userId}` | 儿童 GPS 位置 | | `/people/{userId}/apps` | 已安装应用列表 | | `/people/{userId}/apps:updateRestrictions` | 阻止/取消阻止应用，设置每应用时间限制 | | `/people/{userId}/appsandusage` | 应用使用数据 | | `/people/{userId}/timeLimitOverrides:batchCreate` | 锁定/解锁设备，添加时间奖励 | | `/people/{userId}/timeLimitOverride/{id}?$httpMethod=DELETE` | 取消时间奖励 | | `/people/{userId}/appliedTimeLimits` | 当前时间限制和锁定状态 | | `/people/{userId}/timeLimit` | 时间限制规则和时间表 | | `/people/{userId}/timeLimit:update` | 启用/禁用就寝时间、上课时间、每日限制 | ## 🐛 故障排除 ### 401 身份验证错误 **症状**: 日志显示 "401 Unauthorized" 错误 **解决方案**: 1. 确认 Family Link 认证插件正在运行 2. 检查 API 是否可访问: `curl http://localhost:8099/api/cookies` (或您的插件 IP) 3. 对于文件回退: 检查 `/share/familylink/cookies.enc` 和 `.key` 是否存在 4. 重启插件以刷新身份验证 5. 在 Home Assistant 中重新加载集成 ### 锁定状态未更新 **症状**: 设备锁定状态未反映实际状态 **解决方案**: 1. 检查日志中是否有 API 错误 2. 确认设备在线且已连接 3. 等待下一个更新周期（默认: 5 分钟） 4. 从 Family Link 应用程序手动锁定/解锁以测试同步 ### 就寝/上课时间未检测到 **症状**: 二进制传感器始终显示 "off" **解决方案**: 1. 确认在 Family Link 应用程序中配置了时间表 2. 检查传感器属性中的 `bedtime_start` 和 `bedtime_end` 时间戳 3. 确保时间表已为当前星期几启用 4. 检查 Home Assistant 时区是否与您的实际时区匹配 ### 传感器显示 "未配置" 或 "不可用" **症状**: 某些传感器没有显示数据 **原因**: - 儿童级别的日程传感器在 v0.8.0 中被移除（请改用设备级别的二进制传感器） - 当前日期没有应用使用数据 **解决方案**: - 从 UI 手动删除旧实体 - 等待孩子今天使用应用程序以生成使用数据 ### Cookie 已过期 **症状**: 日志中出现 "Session expired" 错误 **解决方案**: 1. 打开插件 Web UI（端口 8099） 2. 点击 "Démarrer l'authentification" 3. 完成 Google 登录 4. 集成会自动获取新的 Cookie ## 📊 自动化示例 ### 就寝锁定 ``` automation: - alias: "Lock phone at bedtime" trigger: - platform: time at: "21:00:00" condition: - condition: time weekday: - mon - tue - wed - thu - fri action: - service: switch.turn_off target: entity_id: switch.child_phone ``` ### 工作日晚间启用就寝模式 ``` automation: - alias: "Enable bedtime on weeknights" trigger: - platform: time at: "20:00:00" condition: - condition: time weekday: - mon - tue - wed - thu action: - service: switch.turn_on target: entity_id: switch.firstname_lastname_bedtime ``` ### 屏幕时间警报 ``` automation: - alias: "Alert on excessive screen time" trigger: - platform: numeric_state entity_id: sensor.galaxy_tab_firstname_screen_time_remaining below: 30 # Less than 30 minutes remaining action: - service: notify.mobile_app data: message: "Only {{ states('sensor.galaxy_tab_firstname_screen_time_remaining') }} minutes remaining!" ``` ### 完成作业后添加奖励时间 ``` automation: - alias: "Bonus time for homework" trigger: - platform: state entity_id: input_boolean.homework_done to: "on" action: - service: button.press target: entity_id: button.galaxy_tab_firstname_30min - service: notify.mobile_app data: message: "Good job! Added 30 minutes bonus time." ``` ### 达到每日限制通知 ``` automation: - alias: "Notify when daily limit reached" trigger: - platform: state entity_id: binary_sensor.galaxy_tab_firstname_daily_limit_reached to: "on" action: - service: notify.mobile_app data: message: "{{ trigger.to_state.attributes.device_name }} has reached its daily limit" ``` ### 基于位置的自动化（GPS 追踪） ``` automation: - alias: "Notify when child leaves school" trigger: - platform: state entity_id: device_tracker.firstname from: "School" action: - service: notify.mobile_app_parent data: message: "{{ trigger.to_state.name }} has left school" - alias: "Notify when child arrives home" trigger: - platform: state entity_id: device_tracker.firstname to: "home" action: - service: notify.mobile_app_parent data: message: "{{ trigger.to_state.name }} is home!" ``` ## 📈 版本历史 ### 开发环境设置 ``` git clone https://github.com/noiwid/HAFamilyLink.git cd HAFamilyLink python -m venv venv source venv/bin/activate pip install -r requirements-dev.txt ``` ## 📄 许可证 本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## ⚠️ 法律声明 这是一个非官方的集成，与 Google LLC 无关、未获其认可，也未与其建立任何关联。所有产品名称、徽标和品牌均为其各自所有者的财产。使用风险自负。

标签：Android, API集成, DSL, Google Family Link, HACS, Home Assistant, 儿童保护, 儿童安全, 可观测性, 同步, 奖励时间, 学校时间管理, 家庭安全, 家庭监控, 家庭自动化, 家长控制, 就寝时间管理, 屏幕时间监控, 屏幕时间限制, 教育辅助, 时间管理, 时间限制, 智能家居, 特征检测, 社区插件, 设备管理, 设备锁定, 请求拦截, 逆向工具, 限制控制