Practical decision guide
5 min read
Updated
Ask for a permission when its purpose is clear
Explain camera, microphone or location access, handle refusal and show when the capability is actually active.
Direct answer
Connect each permission request to a deliberate action and a specific purpose. Explain what will be used before the platform prompt, request only the necessary capability and preserve an alternative after refusal. Permission granted, hardware available and active capture are three different states.
01
Tie access to a task
For an expense app, scan a receipt should request camera access when chosen, not on the dashboard’s first load. Explain that the camera supplies a receipt image and identify any later upload separately.
Avoid requesting camera, microphone and location together for convenience. A permission explanation is not consent for unrelated processing, retention or sharing; those boundaries need their own clear contract.
- ask for microphone permission only when needed
- camera denied alternative
For an expense app, scan a receipt should request camera access when chosen, not on the dashboard’s first load. Explain that the camera supplies a receipt image and identify any later upload separately. Avoid requesting camera, microphone and location together for convenience. A permission explanation is not consent for unrelated processing, retention or sharing; those boundaries need their own clear contract.
02
Model the actual states
Distinguish not asked, prompt pending, granted, denied, unavailable and active. A permission query may be unsupported or insufficient to predict whether capture will succeed; handle the actual capability call too.
Only show Recording when capture has started. A denied prompt or missing device must never leave an active indicator. Stop access when the user stops or leaves the capture task.
Distinguish not asked, prompt pending, granted, denied, unavailable and active. A permission query may be unsupported or insufficient to predict whether capture will succeed; handle the actual capability call too. Only show Recording when capture has started. A denied prompt or missing device must never leave an active indicator. Stop access when the user stops or leaves the capture task.
03
Example: attach a receipt
Offer Take a photo and Choose a file. Explain the camera need, request it after selection, then show the captured preview before a separate submit action. Let users retake or discard the image.
After refusal, retain Choose a file and a brief explanation of how to change access in browser settings. Do not repeatedly open prompts or imply the alternative requires granting the permission.
Offer Take a photo and Choose a file. Explain the camera need, request it after selection, then show the captured preview before a separate submit action. Let users retake or discard the image. After refusal, retain Choose a file and a brief explanation of how to change access in browser settings. Do not repeatedly open prompts or imply the alternative requires granting the permission.
04
Handle revocation and failure
If access disappears during use, stop capture and retain only data already accepted under the stated policy. Explain whether the draft image survived. Reopening should reflect actual state, not a cached granted flag.
Secure-context, browser and operating-system restrictions vary. Link to supported setup instructions without bypassing security warnings or telling users to broadly disable protections.
If access disappears during use, stop capture and retain only data already accepted under the stated policy. Explain whether the draft image survived. Reopening should reflect actual state, not a cached granted flag. Secure-context, browser and operating-system restrictions vary. Link to supported setup instructions without bypassing security warnings or telling users to broadly disable protections.
05
Verify without collecting real private data
Use a fixture image and exercise grant, refusal, no device and revocation. Check that the fallback works and capture stops when requested. Do not upload a real receipt merely to test the flow.
This guide covers interaction boundaries, not legal consent or native-device certification. A mocked permission test does not establish behavior on every physical phone.
Use a fixture image and exercise grant, refusal, no device and revocation. Check that the fallback works and capture stops when requested. Do not upload a real receipt merely to test the flow. This guide covers interaction boundaries, not legal consent or native-device certification. A mocked permission test does not establish behavior on every physical phone.
Keep this
Verify in your product
- 01The request follows an intentional action.
- 02Only necessary access is requested.
- 03Granted and active differ.
- 04Refusal retains a usable alternative.
- 05Leaving stops capture.
- 06Upload and retention are explained separately.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- Web permissions best practices (opens in a new tab)Google web.dev · Primary reference for the documented mechanism. The worked scenario and decision checklist are original SkillCodex editorial guidance, not a certified implementation.
- Using the Permissions API (opens in a new tab)MDN · Primary reference for the documented mechanism. The worked scenario and decision checklist are original SkillCodex editorial guidance, not a certified implementation.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “Ask for a permission when its purpose is clear” step by step
# Apply the “Ask for a permission when its purpose is clear” guide in your agent ## Objective Connect each permission request to a deliberate action and a specific purpose. Explain what will be used before the platform prompt, request only the necessary capability and preserve an alternative after refusal. Permission granted, hardware available and active capture are three different states. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Explain camera, microphone or location access, handle refusal and show when the capability is actually active. - Preserve the correct decisions already in place. ## Guide steps - 1. Tie access to a task — For an expense app, scan a receipt should request camera access when chosen, not on the dashboard’s first load. Explain that the camera supplies a receipt image and identify any later upload separately. Avoid requesting camera, microphone and location together for convenience. A permission explanation is not consent for unrelated processing, retention or sharing; those boundaries need their own clear contract. - 2. Model the actual states — Distinguish not asked, prompt pending, granted, denied, unavailable and active. A permission query may be unsupported or insufficient to predict whether capture will succeed; handle the actual capability call too. Only show Recording when capture has started. A denied prompt or missing device must never leave an active indicator. Stop access when the user stops or leaves the capture task. - 3. Example: attach a receipt — Offer Take a photo and Choose a file. Explain the camera need, request it after selection, then show the captured preview before a separate submit action. Let users retake or discard the image. After refusal, retain Choose a file and a brief explanation of how to change access in browser settings. Do not repeatedly open prompts or imply the alternative requires granting the permission. - 4. Handle revocation and failure — If access disappears during use, stop capture and retain only data already accepted under the stated policy. Explain whether the draft image survived. Reopening should reflect actual state, not a cached granted flag. Secure-context, browser and operating-system restrictions vary. Link to supported setup instructions without bypassing security warnings or telling users to broadly disable protections. - 5. Verify without collecting real private data — Use a fixture image and exercise grant, refusal, no device and revocation. Check that the fallback works and capture stops when requested. Do not upload a real receipt merely to test the flow. This guide covers interaction boundaries, not legal consent or native-device certification. A mocked permission test does not establish behavior on every physical phone. ## Acceptance criteria — Verify in your product - The request follows an intentional action. - Only necessary access is requested. - Granted and active differ. - Refusal retains a usable alternative. - Leaving stops capture. - Upload and retention are explained separately. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:a50fa6cb39067099b9d8fd7de9da764236e171afff64a482e5f02255fd9f94a8
Diagnose a problem
Diagnose a “Ask for a permission when its purpose is clear” guide gap
# Diagnose a failed application of the “Ask for a permission when its purpose is clear” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. Tie access to a task — For an expense app, scan a receipt should request camera access when chosen, not on the dashboard’s first load. Explain that the camera supplies a receipt image and identify any later upload separately. Avoid requesting camera, microphone and location together for convenience. A permission explanation is not consent for unrelated processing, retention or sharing; those boundaries need their own clear contract. - 2. Model the actual states — Distinguish not asked, prompt pending, granted, denied, unavailable and active. A permission query may be unsupported or insufficient to predict whether capture will succeed; handle the actual capability call too. Only show Recording when capture has started. A denied prompt or missing device must never leave an active indicator. Stop access when the user stops or leaves the capture task. - 3. Example: attach a receipt — Offer Take a photo and Choose a file. Explain the camera need, request it after selection, then show the captured preview before a separate submit action. Let users retake or discard the image. After refusal, retain Choose a file and a brief explanation of how to change access in browser settings. Do not repeatedly open prompts or imply the alternative requires granting the permission. - 4. Handle revocation and failure — If access disappears during use, stop capture and retain only data already accepted under the stated policy. Explain whether the draft image survived. Reopening should reflect actual state, not a cached granted flag. Secure-context, browser and operating-system restrictions vary. Link to supported setup instructions without bypassing security warnings or telling users to broadly disable protections. - 5. Verify without collecting real private data — Use a fixture image and exercise grant, refusal, no device and revocation. Check that the fallback works and capture stops when requested. Do not upload a real receipt merely to test the flow. This guide covers interaction boundaries, not legal consent or native-device certification. A mocked permission test does not establish behavior on every physical phone. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Verify in your product - The request follows an intentional action. - Only necessary access is requested. - Granted and active differ. - Refusal retains a usable alternative. - Leaving stops capture. - Upload and retention are explained separately. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:999c79bee7d7df26e293e390a9833b41c2d8e6aa689bd7d1ec7ddd96c1c6270e
Pack digest: sha256:cf26808b6f5c1cfc616b4cd742433bd3a6ca8d759015fb1b14810505f1586b9d