憑感覺估，通常不準

Our gut estimates are usually off

官方怎麼建議——以及為什麼只看幾小時不夠

What the health bodies say — and why hours alone aren't enough

數字是拿來開口的，不是拿來定罪的

Numbers are for opening a conversation, not passing a verdict

RestBud 現在會「數」了

RestBud can count now

💡 目前進度：這個區塊今天（10/5）才做出來，預計隨下一個版本更新。實機的第一眼就抓到兩個問題——合計對不上列表、語言沒跟著 App 走——都已修掉（來龍去脈在第二部分的〈踩過的雷〉）；完整的實機驗收還在進行。它只能在實機上看到（模擬器沒有螢幕時間授權，畫面會是空白），我還沒拍實機截圖，所以上面那張是示意圖。

💡 Status: this block was only built today (Oct 5) and is planned for the next release. My very first look on a real phone caught two problems — the total didn't match the list, and the language didn't follow the app — both fixed (the story is under "Pitfalls" in Part 2); full device acceptance is still under way. It can only be seen on a real device (the simulator has no Screen Time authorization, so it stays blank), and I don't have a device screenshot yet, so the picture above is an illustration.

為什麼 RestBud 自己「看不到」這些數字

Why RestBud itself can't see the numbers

老實說：這版做不到的事

Honestly: what this version can't do

為了顯示幾個數字，要多一個 target、一個 App ID

A few numbers on screen cost one more target and one more App ID

原因是：Screen Time 的每個 extension 在 iOS 眼裡都是獨立的小 App——有自己的 Bundle ID、自己的 capability、自己的 provisioning profile。RestBud 現在有四個，彼此靠同一個 App Group（group.app.rexcode.restbud）串起來：

The reason: to iOS, every Screen Time extension is its own small app — its own Bundle ID, its own capabilities, its own provisioning profile. RestBud now has four, tied together by one App Group (group.app.rexcode.restbud):

• 主 app · app.rexcode.restbud — 要授權、挑 App、排程，並把報表嵌進畫面 Main app · app.rexcode.restbud — authorizes, picks apps, schedules, and embeds the report
• Monitor · ….monitor — 排程到點或用量過門檻時被系統喚醒，改遮罩、發通知 Monitor · ….monitor — woken by the system at schedule boundaries or usage thresholds; changes the shield, sends notifications
• Shield UI · ….shieldui — 決定被鎖 App 的遮罩長相 Shield UI · ….shieldui — decides how the shield on a blocked app looks
• Report · ….report（這次新增）— 系統把用量交給它，它畫成畫面 Report · ….report (new this time) — the system hands it the usage and it draws the view

一句話版：後台建 App ID、勾 Family Controls、指定 App Group、存檔；專案加 target、entitlements 寫進 project.yml、主 app 嵌入；最後實機驗證，並逐個 .appex 驗簽。

One-line version: in the portal — create the App ID, tick Family Controls, assign the App Group, save. In the project — add a target, declare entitlements in project.yml, embed it in the main app. Finally — check on a real device and verify every .appex in the built .ipa.

七個步驟

Seven steps

1. 先確認帳號有 Family Controls 權限

   First, check your account has Family Controls

   Family Controls 是要向 Apple 申請的受限權限。RestBud 在 7/30 通過（帳號層級），之後新建的 App ID，Family Controls 的兩個選項直接就勾得起來。不過 Apple 的文件說得更嚴格：extension 要比照主 app 設定，上架時也要為 extension 提出同樣的申請。如果你的帳號勾不起來，先處理這件事（App ID 頁面上有個 Capability Requests 分頁，我這次用不到）。

   Family Controls is a restricted capability you have to request from Apple. RestBud's came through on 7/30 at the account level, and since then both Family Controls options can simply be ticked on newly created App IDs. Apple's documentation is stricter, though: extensions are configured like the main app, and for distribution you submit the same request for the extension too. If you can't tick the boxes on your account, sort that out first (the App ID page also has a Capability Requests tab, which I didn't need this time).

   來源：Source: Apple · Configuring Family Controls

2. 手動建立新的 App ID

   Create the new App ID by hand

   Certificates, Identifiers & Profiles → Identifiers → + → App IDs → App。Description 填 rexcode restbud report；Bundle ID 選 Explicit（不是 Wildcard），填 app.rexcode.restbud.report。Description 不能有 @ & * " 這類特殊字元（欄位底下會提醒），它只是給人看的標籤，真正的識別是 Bundle ID。

   為什麼手動建？我的經驗是，Xcode 自動幫你建的 App ID（名字開頭是「XC app …」）只會開 App Groups，不會開 Family Controls，最後還是得回後台補勾。

   Certificates, Identifiers & Profiles → Identifiers → + → App IDs → App. Description: rexcode restbud report. Bundle ID: choose Explicit (not Wildcard) and enter app.rexcode.restbud.report. The Description can't contain special characters such as @ & * " (the field tells you so); it's just a label for humans — the Bundle ID is the real identifier.

   Why by hand? In my experience the App IDs Xcode creates automatically (names starting with "XC app …") only get App Groups, not Family Controls, so you end up back in the portal ticking things anyway.

   來源（建立步驟）：Source (the steps): Apple Developer Help · Register an App ID
   

   建好之後點進去就是這個畫面：Description、Bundle ID（explicit）和 Capabilities 分頁；App Groups 已勾，旁邊寫著 Enabled App Groups (1)。點圖可看原尺寸。

   Open the new App ID and you get this page: Description, Bundle ID (explicit) and the Capabilities tab; App Groups is ticked, with "Enabled App Groups (1)" beside it. Tap the image for full size.

3. Family Controls：Development 和 Distribution 都要勾

   Family Controls: tick both Development and Distribution

   在這個 App ID 的頁面找到 Family Controls (Development) 和 Family Controls (Distribution)，開發用和上架用各一個，兩個都勾。

   另外還有第三個 App and Website Usage：那是 iOS 26.4 開給歐盟的資料讀取通道（Apple 文件寫明只有歐盟的裝置能用，見上面〈為什麼 RestBud 自己「看不到」這些數字〉）。台灣用不到，我在 entitlements 裡不宣告它。

   On this App ID's page, find Family Controls (Development) and Family Controls (Distribution) — one for development builds, one for shipping — and tick both.

   There is also a third entry, App and Website Usage: that's the iOS 26.4 data-access route for the EU (Apple's documentation says it only works on devices in the EU; see "Why RestBud itself can't see the numbers" above). It's no use in Taiwan, so I don't declare it in the entitlements.

   來源：Source: Apple · Configuring Family Controls · Apple · approvedWithDataAccess

4. 勾 App Groups，並指定到同一個 group

   Tick App Groups and assign the same group

   App Group 本身要先註冊好（Identifiers → + → App Groups，識別字必須以 group. 開頭），RestBud 的早就有了。接著在這個 App ID 勾選 App Groups，再按旁邊的按鈕（Apple 的說明寫 Configure，我的畫面上設定完之後是 Edit），會跳出「App Group Assignment」：勾 group.app.rexcode.restbud → Continue → Assign → Done。四個 target 都指到同一個 group——主 app、monitor、shield 早就指好了，這次補上 report。

   The App Group itself has to be registered first (Identifiers → + → App Groups; the identifier must start with group.) — RestBud's has existed for a while. Then, on this App ID, tick App Groups and press the button beside it (Apple's help page calls it Configure; on my screen, once set, it reads Edit). The "App Group Assignment" dialog opens: tick group.app.rexcode.restbud → Continue → Assign → Done. All four targets point at the same group — the main app, monitor and shield were already done; this time it was report's turn.

   

   App Group Assignment：把共用的 group 指給這個 App ID。左邊 group app rexcode restbud 是建立 group 時填的描述（給人看的標籤），右邊 group.app.rexcode.restbud 才是程式裡用的識別。

   App Group Assignment: assign the shared group to this App ID. The name on the left, "group app rexcode restbud", is the description given when the group was created (a label for people); the identifier on the right, group.app.rexcode.restbud, is what the code uses.

   來源：Source: Apple Developer Help · Enable app capabilities · Register an App Group · Apple · Configuring app groups

5. Save → Confirm，然後 profile 會失效

   Save → Confirm — and the profiles go stale

   按 Save，跳出警告對話框就按 Confirm。Apple 的提醒是：包含這個 App ID 的 provisioning profile 會因為修改而失效，必須重新產生。用自動簽章（或 cloud signing）的話，通常會在下一次 build 時重新產生；手動管理 profile 的人要自己去重生。

   Press Save and, if a warning dialog appears, press Confirm. Apple's reminder: provisioning profiles that include a modified App ID become invalid and have to be regenerated. With automatic signing (or cloud signing) that usually happens on the next build; if you manage profiles by hand, you regenerate them yourself.

   來源：Source: Apple Developer Help · Enable app capabilities

6. 專案端：加第四個 target

   In the project: add the fourth target

   我用 xcodegen，在 project.yml 新增一個 target，並讓主 app 嵌入它：

   I use xcodegen. Add a target in project.yml and have the main app embed it:

   RestBud:                                   # main app
     sources:
       - RestBud
       - Shared
       - path: RestBudReport/ReportContext.swift   # scene id, shared by both
     dependencies:
       - target: RestBudReport                # embed the report extension
   
   RestBudReport:
     type: app-extension
     platform: iOS
     sources: [RestBudReport]
     info:
       path: RestBudReport/Info.plist
       properties:
         NSExtension:
           NSExtensionPointIdentifier: com.apple.deviceactivityui.report-extension
     settings:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: app.rexcode.restbud.report
     entitlements:
       path: RestBudReport/RestBudReport.entitlements
       properties:                            # declare entitlements HERE
         com.apple.developer.family-controls: true
         com.apple.security.application-groups:
           - group.app.rexcode.restbud

   • entitlements 一定寫在 properties：XcodeGen 的文件寫明，spec 裡一旦定義了 entitlements，它就會「產生並寫入」.entitlements 檔，所有項目都必須寫在 properties 裡。只留 path、自己手改檔案的話，下一次 xcodegen generate 就會被蓋掉——我另一個 App 就被蓋成空的 <dict/>。
   • 場景識別字串（context）兩邊要一致：主 app 用 DeviceActivityReport(context, filter: …) 指名要哪一個畫面，extension 也要註冊同名的場景。我把定義放在同一個檔，讓兩個 target 都編進去。（我最後註冊了中、英各一個，原因在〈踩過的雷〉。）
   • 主 app 要自己給高度：報表是系統嵌進來的 remote view，實測不會自己撐高，要明確寫 .frame(height:)。
   • filter 一定要帶 applications:：Apple 的 DeviceActivityFilter 文件只說它是「要納入報表的 App（可省略）」，沒寫省略時的行為。依我的理解，沒帶就是不限 App，會把這支手機所有 App 都算進去——那不是家長想看的範圍。
   • Declare entitlements under properties: XcodeGen's documentation says that once the spec defines entitlements, it generates and writes the .entitlements file, and all entries must be provided in properties. If you keep only a path and hand-edit the file, the next xcodegen generate overwrites it — on another app of mine it was overwritten with an empty <dict/>.
   • The scene identifier (context) must match on both sides: the main app asks for a view with DeviceActivityReport(context, filter: …), and the extension has to register a scene with the same name. I keep the definition in one file and compile it into both targets. (I ended up registering two, one per language — see "Pitfalls".)
   • The main app must supply the height: the report is a remote view the system embeds, and in my testing it won't size itself, so give it an explicit .frame(height:).
   • Always give the filter applications:: Apple's DeviceActivityFilter documentation only calls it "an optional set of applications to include" and doesn't say what happens when it's omitted. My understanding is that omitting it means no app restriction, so every app on the phone would be counted — which isn't what a parent wants to see.
   來源：Source: XcodeGen · ProjectSpec · Apple · DeviceActivityReport · Apple · DeviceActivityFilter

7. 實機驗證，以及打包前的最後一關

   Verify on a real device — and the last check before shipping

   模擬器沒有 Family Controls 授權，報表永遠是空白；加上主 app 讀不到裡面的數字，連 log 都沒有，所以只能在實機用眼睛驗。我訂的驗收標準：區塊出現；納管的 App 都在；沒納管的不出現；合計等於各列相加；分鐘數跟「設定 → 螢幕使用時間」同一個量級（差幾分鐘可以）；語言跟 App 內設定一致；列不被截掉。其中「合計」和「語言」這兩條，是實機第一眼之後才補上的。

   打包前把 .ipa 解開，對每一個 .appex 跑 codesign -d --entitlements -，確認四個 target 的 entitlements 都真的在。注意：命令列自動簽章的 build 會挑 Apple Development 憑證（get-task-allow=true），只能證明 entitlement 這條鏈通了，不是能上傳的成品。

   The simulator has no Family Controls authorization, so the report is always blank; and since the main app can't read what's inside it, there isn't even a log to look at. The only way to verify is on a real phone, with your eyes. My bar: the block appears; every managed app is listed; unmanaged apps don't appear; the total equals the rows added up; minutes are the same order of magnitude as Settings → Screen Time (a few minutes off is fine); the language matches the app's own setting; no row is clipped. The total and language items were only added after the first look on a real device.

   Before uploading, unpack the .ipa and run codesign -d --entitlements - on every .appex to confirm all four targets really carry their entitlements. Note that a command-line build with automatic signing picks an Apple Development certificate (get-task-allow=true); that only proves the entitlement chain works — it isn't an uploadable product.

踩過的雷

Pitfalls