Android SDK

The com.phosra.sdk Kotlin library provides on-device child safety enforcement for Android using UsageStatsManager, DevicePolicyManager, VpnService, and AccessibilityService.

Overview

The SDK has a two-layer architecture:

1. API Client -- Communicates with the Phosra API to register devices, fetch compiled policies, submit enforcement reports, and acknowledge policy versions.
2. Enforcement Engine -- Translates the compiled policy document into native Android API calls to enforce content filters, screen time limits, web filtering, purchase controls, and more.

Requirements

Installation

// Private preview: repo URL + credentials provided by Phosra
dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("<private maven URL provided by Phosra>")
            credentials {
                username = providers.gradleProperty("phosraMavenUser").get()
                password = providers.gradleProperty("phosraMavenToken").get()
            }
        }
    }
}

Then add the dependency to your module-level build.gradle.kts:

kotlin
dependencies {
    implementation("com.phosra:sdk:1.0.0")
}

The SDK pulls in the following transitive dependencies:

• kotlinx-coroutines-android -- Async operations
• kotlinx-serialization-json -- JSON parsing
• okhttp3 -- HTTP networking
• androidx.work:work-runtime-ktx -- Background sync
• androidx.security:security-crypto -- Encrypted key storage

Quick Start

1. 1
   Request Required Permissions

2. 2
   Android requires several special permissions for parental control enforcement. Guide the user through each:

3. 3
   kotlin

   import com.phosra.sdk.permissions.PermissionManager
    
   val permissionManager = PermissionManager(context)
   val missing = permissionManager.getMissingPermissions()
    
   for (permission in missing) {
       permissionManager.requestPermission(activity, permission)
   }

4. 4
   Register the Device

5. 5
   The parent initiates device registration from their authenticated session:

6. 6
   kotlin

   import com.phosra.sdk.PhosraClient
   import com.phosra.sdk.PhosraConfiguration
   import com.phosra.sdk.models.RegisterDeviceRequest
    
   val config = PhosraConfiguration(
       parentToken = parentJWT,
       childId = childUUID
   )
   val client = PhosraClient(config)
    
   val request = RegisterDeviceRequest(
       deviceName = "Emma's Pixel",
       deviceModel = android.os.Build.MODEL,
       osVersion = android.os.Build.VERSION.RELEASE,
       appVersion = BuildConfig.VERSION_NAME,
       capabilities = listOf("UsageStats", "DeviceAdmin", "VPN", "Accessibility")
   )
    
   val response = client.registerDevice(request)

7. 7
   Store the API Key

8. 8
   The API key is returned exactly once during registration. Store it in EncryptedSharedPreferences:

9. 9
   kotlin

   import com.phosra.sdk.storage.KeystoreHelper
    
   KeystoreHelper.saveDeviceKey(context, response.apiKey)

10. 10
    Schedule Background Sync

11. 11
    Set up periodic policy sync using WorkManager:

12. 12
    kotlin

    import com.phosra.sdk.sync.PolicySyncWorker
    import androidx.work.*
    import java.util.concurrent.TimeUnit
     
    val syncRequest = PeriodicWorkRequestBuilder<PolicySyncWorker>(
        15, TimeUnit.MINUTES
    ).setConstraints(
        Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)
            .build()
    ).build()
     
    WorkManager.getInstance(context).enqueueUniquePeriodicWork(
        "phosra_policy_sync",
        ExistingPeriodicWorkPolicy.KEEP,
        syncRequest
    )

13. 13
    Fetch and Apply the Policy

14. 14
    kotlin

    val deviceKey = KeystoreHelper.loadDeviceKey(context)!!
    val deviceConfig = PhosraConfiguration(deviceKey = deviceKey)
    val deviceClient = PhosraClient(deviceConfig)
     
    val policy = deviceClient.fetchPolicy()
    println("Applying policy v${policy.version} for ${policy.ageGroup}")
     
    // Apply via enforcement engine
    val engine = EnforcementEngine(context)
    val results = engine.apply(policy)
     
    // Report results back to Phosra
    deviceClient.submitReport(DeviceReport(
        reportType = ReportType.ENFORCEMENT_STATUS,
        payload = EnforcementStatusPayload(
            policyVersion = policy.version,
            results = results
        )
    ))
    deviceClient.ackPolicyVersion(policy.version)

Device Registration

The registration flow requires parent authentication and produces a device-specific API key:

Parent App                    Phosra API                  Child Device
    |                             |                           |
    |-- POST /children/{id}/devices ------------------------> |
    |   (Authorization: Bearer parentJWT)                     |
    |                             |                           |
    |   <-- { device, api_key } --|                           |
    |                             |                           |
    |   -- Transfer api_key ------------------------------>   |
    |                             |                           | EncryptedSharedPrefs
    |                             |                           |

The RegisterDeviceRequest includes device metadata and capability declarations:

RegisterDeviceRequest(
    deviceName = "Emma's Pixel",
    deviceModel = "Pixel 8 Pro",
    osVersion = "14",
    appVersion = "1.0.0",
    capabilities = listOf(
        "UsageStats",        // UsageStatsManager access
        "DeviceAdmin",       // DevicePolicyManager enrollment
        "VPN",               // Local VPN for DNS filtering
        "Accessibility",     // Foreground app detection
        "NotificationListener" // Notification filtering
    )
)

Policy Sync

WorkManager-Based Sync

The SDK uses WorkManager for reliable background policy synchronization:

class PolicySyncWorker(
    context: Context,
    params: WorkerParameters
) : CoroutineWorker(context, params) {
 
    override suspend fun doWork(): Result {
        val deviceKey = KeystoreHelper.loadDeviceKey(applicationContext) ?: return Result.failure()
        val client = PhosraClient(PhosraConfiguration(deviceKey = deviceKey))
 
        return try {
            val currentVersion = PreferenceManager.getCurrentPolicyVersion(applicationContext)
            val policy = client.fetchPolicy(sinceVersion = currentVersion) ?: return Result.success()
 
            val engine = EnforcementEngine(applicationContext)
            val results = engine.apply(policy)
 
            client.submitReport(DeviceReport(
                reportType = ReportType.ENFORCEMENT_STATUS,
                payload = EnforcementStatusPayload(
                    policyVersion = policy.version,
                    results = results
                )
            ))
            client.ackPolicyVersion(policy.version)
 
            PreferenceManager.setCurrentPolicyVersion(applicationContext, policy.version)
            Result.success()
        } catch (e: Exception) {
            Result.retry()
        }
    }
}

Firebase Cloud Messaging (FCM)

For immediate policy refresh when a parent modifies rules, handle FCM data messages:

class PhosraMessagingService : FirebaseMessagingService() {
 
    override fun onMessageReceived(message: RemoteMessage) {
        val event = message.data["phosra_event"] ?: return
        val version = message.data["phosra_version"]?.toIntOrNull() ?: return
 
        if (event == "policy.updated") {
            val currentVersion = PreferenceManager.getCurrentPolicyVersion(this)
            if (version > currentVersion) {
                // Enqueue immediate one-time sync
                val syncRequest = OneTimeWorkRequestBuilder<PolicySyncWorker>()
                    .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
                    .build()
                WorkManager.getInstance(this).enqueue(syncRequest)
            }
        }
    }
}

Enforcement Engine

Each enforcer handles a specific policy section and maps it to the appropriate Android API.

Content Filter Enforcer

Monitors the foreground app using UsageStatsManager and AccessibilityService. Blocks restricted apps by displaying a full-screen overlay.

// Detect foreground app and block if restricted
val usageStatsManager = context.getSystemService(UsageStatsManager::class.java)
val events = usageStatsManager.queryEvents(startTime, System.currentTimeMillis())
 
val event = UsageEvents.Event()
while (events.hasNextEvent()) {
    events.getNextEvent(event)
    if (event.eventType == UsageEvents.Event.ACTIVITY_RESUMED) {
        if (event.packageName in policy.contentFilter.blockedApps) {
            showBlockingOverlay(event.packageName)
        }
    }
}

Screen Time Enforcer

Tracks cumulative daily usage and enforces time limits.

Web Filter Enforcer

Runs a local VPN service that intercepts DNS queries and blocks restricted domains.

class PhosraVpnService : VpnService() {
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        val builder = Builder()
            .addAddress("10.0.0.2", 32)
            .addDnsServer("10.0.0.1")
            .setSession("Phosra Web Filter")
 
        val tunnel = builder.establish()
        // DNS query interception loop
        // Block domains matching policy.webFilter.blockedDomains
        return START_STICKY
    }
}

Purchase Enforcer

Social Enforcer

Notification Enforcer

Permission Management

Android requires several special permissions. Each must be granted by the parent through system settings.

val intent = Intent(Settings.ACTION_USAGE_ACCESS_SETTINGS)
startActivity(intent)

Reporting

The SDK submits two types of reports to the Phosra API:

Enforcement Status Report

Sent after applying a policy, contains per-category results:

DeviceReport(
    reportType = ReportType.ENFORCEMENT_STATUS,
    payload = EnforcementStatusPayload(
        policyVersion = 3,
        results = listOf(
            CategoryEnforcementResult(
                category = "content_rating",
                status = "enforced",   // "enforced", "partial", "failed", "unsupported"
                framework = "UsageStatsManager"
            ),
            CategoryEnforcementResult(
                category = "web_filter_level",
                status = "enforced",
                framework = "VpnService"
            )
        )
    )
)

Screen Time Report

Aggregated daily usage data:

DeviceReport(
    reportType = ReportType.SCREEN_TIME,
    payload = ScreenTimePayload(
        byCategory = mapOf("social-media" to 45, "gaming" to 30, "education" to 60),
        topApps = mapOf("com.instagram.android" to 25, "com.google.android.youtube" to 20),
        totalMinutes = 135,
        date = "2026-02-23"
    )
)

CompiledPolicy Structure

The compiled policy is fetched from GET /device/policy and contains all enforcement rules organized by section:

{
  "version": 3,
  "child_id": "uuid",
  "child_age": 10,
  "age_group": "tween",
  "policy_id": "uuid",
  "status": "active",
  "generated_at": "2026-02-23T14:30:00Z",
  "content_filter": {
    "age_rating": "E10+",
    "max_ratings": { "esrb": "E10+", "mpaa": "PG" },
    "blocked_apps": ["com.instagram.android"],
    "allowed_apps": [],
    "allowlist_mode": false
  },
  "screen_time": {
    "daily_limit_minutes": 120,
    "per_app_limits": [
      { "bundle_id": "com.google.android.youtube", "daily_minutes": 30 }
    ],
    "downtime_windows": [
      { "days_of_week": ["monday","tuesday","wednesday","thursday","friday"],
        "start_time": "21:00", "end_time": "07:00" }
    ],
    "always_allowed_apps": ["com.android.dialer", "com.android.mms", "com.google.android.apps.maps"]
  },
  "purchases": {
    "require_approval": true,
    "block_iap": false,
    "spending_cap_usd": 10.00
  },
  "privacy": {
    "location_sharing_enabled": true,
    "profile_visibility": "private",
    "account_creation_approval": true,
    "data_sharing_restricted": true
  },
  "social": {
    "chat_mode": "friends_only",
    "dm_restriction": "contacts_only",
    "multiplayer_mode": "friends_only"
  },
  "notifications": {
    "curfew_start": "21:00",
    "curfew_end": "07:00",
    "usage_timer_minutes": 30
  },
  "web_filter": {
    "level": "moderate",
    "safe_search": true,
    "blocked_domains": ["reddit.com"],
    "allowed_domains": ["khanacademy.org"],
    "blocked_categories": ["gambling", "adult"]
  }
}

Supported Rule Categories

The 45 OCSS rule categories the Android SDK maps to native framework primitives (of the 123 categories in the OCSS rule registry; the remainder are policy-only or census-enforced and carry no client-side Android verb):

Content Rules

Time Rules

Purchase Rules

Social Rules

Web Rules

Privacy Rules

Monitoring Rules

Engagement Rules

Notification Rules

Legislation-Driven Rules

Compliance Rules

Parental / Legislative Rules

Google Play Compliance

Required Declarations

1. Permissions Declaration Form: Submit in Play Console for QUERY_ALL_PACKAGES, PACKAGE_USAGE_STATS, and Accessibility Service usage.

2. Data Safety section: Declare all data collected from child devices. Phosra collects:

   • App usage statistics (aggregated)
   • Web activity (domain-level, via DNS)
   • Device metadata (model, OS version)

3. VPN usage: Declare that the VPN is used exclusively for local DNS filtering, not for routing traffic through external servers.

4. Target audience: Set to "Parents" -- the app is a parental control tool, not a child-facing app.

5. Families Policy: If your app appears in the Play Store's Family section, ensure compliance with Google's Families Policy.

Tips for Approval

• Provide a detailed app description explaining the parental control use case
• Include a demo video showing the parent setup flow and enforcement in action
• Reference applicable child safety legislation (COPPA, KOSA, etc.)
• Respond promptly to any review team questions about permission usage