Skip to content

Ask Projection Permission

Summary

  • Internal name: AskProjectionPermission
  • Category: Media Projection
  • Purpose: Request (or reuse) the Android MediaProjection permission needed to capture the device screen, and start the background screen-streaming service.
  • Task type: Normal

Compatibility

  • Minimum AndroMate version: 1.1.0

  • Maximum AndroMate version: 1.1.0

  • Minimum Android: Android 13 (API 33)

  • Maximum Android tested: Android 16 (API 36)

  • Supported manufacturers:

    • ✅ All manufacturers

  • Required permissions:

    • User-granted MediaProjection consent (system dialog) — not a manifest permission, a one-time runtime prompt per app session

Detailed description

The Ask Projection Permission task obtains the system's screen-capture permission (MediaProjection) and starts the screen-streaming service that keeps a live capture available for later tasks — most notably ocr_task, which reads text off whatever the projection last captured.

Run this task once, before any ocr_task in the workflow. If the permission was already granted earlier in the same app session, the task reuses it immediately instead of prompting again.

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
timeout_ms Integer No Milliseconds to wait for the user to respond to the permission dialog Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 5000

Output parameters

The Ask Projection Permission task produces no outputs. It only prepares the screen-streaming service for later tasks (e.g. ocr_task) to use.

Exceptions

Code Exception Name Description
MEDIA-PROJ-001 Media Projection Permission Refused The user dismissed or denied the MediaProjection system permission dialog.

Execution flowchart

flowchart TD
    Start([▶ AskProjectionPermission]) --> Check{Permission already\ngranted this session?}
    Check -->|Yes| Info[ℹ️ Log: already granted]
    Check -->|No| Prompt[📲 Show system MediaProjection dialog]
    Prompt --> Wait{User response\nwithin timeout_ms?}
    Wait -->|Granted| StartStream[🔴 Start screen-streaming service]
    Wait -->|Canceled/Denied| E1[❌ MEDIA-PROJ-001\nPERMISSION_REFUSED]
    Info --> Success([✅ VoidResult])
    StartStream --> Success
    E1 --> Error([❌ Exception])

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style E1 fill:#ffcdd2

How it works:

  1. Check existing permission: if MediaProjection was already granted earlier in this app session, skip straight to success.
  2. Prompt: otherwise, show the Android system MediaProjection consent dialog.
  3. Wait: block until the user responds or timeout_ms elapses.
  4. Start streaming: on grant, start the background screen-streaming service that later tasks (ocr_task) read from.
  5. Refused: if the user cancels/denies, raise MEDIA-PROJ-001.

Input parameter details

1. Input parameter: timeout_ms

How long to wait for the user to respond to the permission dialog, in milliseconds.

Example

"timeout_ms": 10000

Details

  • Optional — defaults to 5000 (5 seconds) if omitted.
  • Not resolved as a $variable — read as a literal integer from the JSON.

Complete JSON example

{
  "AskProjectionPermission": [
    {
      "id": "1",
      "timeout_ms": 8000
    }
  ]
}