# Apple build and entitlement setup

## Build targets

| Target | Bundle ID suffix | Extension point |
|---|---|---|
| FamilyQuests | `.app` | App |
| ActivityMonitor | `.app.monitor` | `com.apple.deviceactivity.monitor-extension` |
| ShieldConfiguration | `.app.shield` | `com.apple.ManagedSettingsUI.shield-configuration-service` |
| ShieldAction | `.app.shieldaction` | `com.apple.ManagedSettings.shield-action-service` |

The prefix is `APC_BUNDLE_PREFIX`. All targets use `APC_APP_GROUP`; the app and monitor actually exchange state through it. Defaults are in `ios/Config/Base.xcconfig`. Copy `Local.xcconfig.example` to the gitignored `Local.xcconfig` and supply the team and identifiers you control.

Enable the Family Controls capability and shared App Group for the app and applicable extensions, and use provisioning profiles containing the corresponding entitlements. The checked-in entitlement file does not grant Apple's permission by itself. Request Family Controls distribution authorization for the App IDs you intend to distribute and regenerate the matching profiles. Development provisioning and distribution approval are separate steps.

XcodeGen supplies the Info.plist extension identifiers/principal classes and embeds the extensions. Generated `.xcodeproj` and plists are gitignored. `make ios-project` is required after cloning or changing the specification. No signing certificates, profiles, private keys, Apple credentials or CI configuration are committed.

The app requests FamilyControls authorization for a **child**. Test with the intended Family Sharing child account and a guardian available to approve. There is no automatic fallback to `.individual`. An adult's test phone cannot stand in for testing the guardian/child authorization and anti-removal behavior.

## Network and local development

Use the parent dashboard's real HTTPS origin on the phone, with a trusted certificate. Configure the same origin on the server; a mismatching browser Origin causes parent mutations to fail. The iPhone's `localhost` refers to that iPhone, not the build server. Debug loopback HTTP is for simulator/local harness work only. A local-network usage description is included; inspect the phone's Local Network permission when testing a private LAN server.

Do not expose an unsigned debug API on the LAN or put the parent administration token in the iPhone app. Screen Time changes are applied on the child's device, not by the Mac browser calling Apple's settings remotely.

## Remaining distribution work

Supply app icons, final display metadata, privacy declarations/manifests appropriate to the actual shipped functionality, provisioning, signing/export options and deployment automation. No App Store/TestFlight approval or successful archive is claimed. Keep native Screen Time safety restrictions in place while validating the prototype.

## Primary references

- [Meet the Screen Time API](https://developer.apple.com/videos/play/wwdc2021/10123/)
- [What's new in Screen Time API](https://developer.apple.com/videos/play/wwdc2022/110336/)
- [Family Controls authorization](https://developer.apple.com/documentation/familycontrols/authorizationcenter/requestauthorization(for:))
- [DeviceActivity event includesPastActivity](https://developer.apple.com/documentation/deviceactivity/deviceactivityevent/includespastactivity)
- [DeviceActivity startMonitoring](https://developer.apple.com/documentation/deviceactivity/deviceactivitycenter/startmonitoring(_:during:events:))
- [Requesting the Family Controls entitlement](https://developer.apple.com/documentation/familycontrols/requesting-the-family-controls-entitlement)
- [XcodeGen project specification](https://github.com/yonaskolb/XcodeGen/blob/master/Docs/ProjectSpec.md)

These describe platform mechanisms, not evidence that this particular prototype works correctly on your hardware. Record the OS, Xcode, provisioning and observed behavior in the acceptance checklist.