README.md

React Native Screen Time API

Access the Screen Time API for iOS and Wellbeing API for Android (coming soon). This is far from complete and needs more work. Please don't hesitate to request specific screen time features

NOTE: The app/category-token-to-app/category-name API portion of this library is a hackish implementation because Apple intentionally obfuscates this information from developers. Your app may be rejected by Apple if you use that particular feature of this API as it would circumvent their obfuscation. The approach also uses OCR and is quite buggy, so just use it for experimentation and learning purposes.

Table of Contents

• Installation
• Set up for iOS
  • Configure Podfile
  • Add FamilyControls capability to your app
  • Request Family Controls capabilities
• Sample code
• Contributing
• Contributors

Installation

npm install react-native-screen-time-api

or

yarn add react-native-screen-time-api

Set up for iOS

Configure Podfile

Ensure that your deployment target is set to iOS 16.0 or higher in your Xcode project and ios/Podfile

platform :ios, '16.0'

Always run npx pod-install after installing or updating this package.

Add FamilyControls capability to your app

See https://developer.apple.com/documentation/Xcode/adding-capabilities-to-your-app

Open ios/[your-app]/[your-app].entitlements file, add this definition:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.developer.family-controls</key>
    <true/>
  </dict>
</plist>

Request Family Controls capabilities

In addition to adding the Family Controls entitlement, for distribution, you will also need to request Family Controls capabilities

Sample code

import React from 'react';
import {
  StyleSheet,
  Text,
  TouchableHighlight,
  View,
} from 'react-native';

import { FamilyActivitySelection, ScreenTime } from 'react-native-screen-time-api';

const MyApp = () => {

  const [activitySelection, setActivitySelection] = React.useState<FamilyActivitySelection>();

  const selectActivities = React.useCallback(async () => {
    try {
      await ScreenTime.requestAuthorization('individual');
      const status = await ScreenTime.getAuthorizationStatus();
      console.log('Authorization status:', status); // 'approved', 'denied', or 'notDetermined'
      if (status !== 'approved') {
        throw new Error('user denied screen time access');
      }
      const selection = await ScreenTime.displayFamilyActivityPicker({});
      console.log('Family activity selection:', selection);
      // selection will be `null` if user presses cancel
      if (selection) {
        setActivitySelection(selection);
        await ScreenTime.setActivitySelection(selection); // sets the shields
      }
    } catch (error) {
      console.error(error);
    }
  }, []);

  const getNames = React.useCallback(async () => {
    try {

      if (!activitySelection) {
        throw new Error('no activity selection');
      }

      const applicationName = await ScreenTime.getApplicationName(activitySelection.applicationTokens[0]);
      console.log('First Application:', applicationName);

      const categoryName = await ScreenTime.getCategoryName(activitySelection.categoryTokens[0]);
      console.log('First Category:', categoryName);

    } catch (error) {
      console.error(error);
    }
  }, [activitySelection]);

  return (
    <View style={ styles.view }>
      <TouchableHighlight onPress={ () => selectActivities() }>
        <Text>Select Activities</Text>
      </TouchableHighlight>
      {activitySelection && (
        <TouchableHighlight onPress={ () => getNames() }>
          <Text>Get Names</Text>
        </TouchableHighlight>
      )}
    </View>
  );
};

const styles = StyleSheet.create({
  view: {
    alignItems: 'center',
    flexDirection: 'column',
    flexGrow: 1,
    backgroundColor: 'white',
    gap: 6,
    justifyContent: 'center',
  },
});

export default MyApp;

Contributing

To contribute feel free to either make a PR or request to be added as a collaborator. Once your feature is added you may also add yourself to the Contributors list below.

To begin development, clone the repository and open /ScreenTimeExample/ios/ScreenTimeExample.xcworkspace directory. This will open the example project in Xcode. You can then run the project in the simulator or on a physical device. You may need to run yarn install followed by npx pod-install inside the ScreenTimeExample directory to install the necessary pods.

You can first modify the code under Pods/Development Pods/ReactNativeScreenTimeAPI while debugging or tryng to add new features. Once you are satisfied with your changes, you will need to copy your files and changes to the ReactNativeScreenTimeAPI project under the Pods project, then make a pull request.

Contributors

Thom Morgan

Duc Filan

Ashish Ramachandran