Guide

This guide explains the choices a person sees in BloqueApp. The Android interface uses the English labels shown in quotation marks.

A quick map of access choices

flowchart TD
    A[Managed app] --> S{Protected sleep?}
    S -->|No| B{Choose a way to access}
    S -->|Yes| E[Bank credit is unavailable]
    E --> E2[Request an explicit sleep exception if policy permits]
    B --> C[Use banked time]
    C --> C1[Credit is spent during active use]
    C1 --> C2[Unused credit stays in the bank]
    B --> D[Ask for extra time]
    D --> D1{Partner approves?}
    D1 -->|Yes| D2[Fixed allowance until its deadline]
    D1 -->|No| D3[No allowance]

Bank time follows actual use. An approved extra-time request has a deadline that keeps running, including while you are away from the phone.

Choose how to access a managed app

Use banked time

A time bank is shared by the apps in its group. On Home, choose Use banked time to start a session deliberately. Credit is deducted only while a managed group app is in active use. Leaving those apps, returning Home, locking the phone, or turning off the screen pauses spending. On Home, End banked time stops the session; in the detailed bank screen, the action is End bank session. Both keep unused credit.

Groups have separate balances. Credit saved by one group is not transferred into another group automatically. Refill and daily-minimum rules come from the signed policy. One example configuration adds 3 minutes per 30 allowed minutes outside the protected sleep schedule and caps the balance at 30 minutes; those values describe an example, not a universal setting.

Request temporary extra time

On first launch, Getting started explains the choices; Review setup opens Settings so you can connect with your partner and sync policy. From Home, Ask for extra time opens the request flow. Or, in Apps, select an eligible app and choose Request extra time; that selected app carries into the request. Choose a duration, review the details, and tap Send request only when you are ready to submit. The Include a sleep exception option appears only when policy allows it and starts unchecked.

The request screen reports Waiting for approval, Your request was denied, Access available until [time], or Allowance ended as the state changes. Approval by the server and access on the phone are separate steps: Android must verify the signed grant and successfully apply access. If the server approved but Android could not open access, the app says so and directs you to check Settings; approval alone does not prove that the operating system released the app.

If a request is still waiting, refresh its status or retry the saved request. When the result is uncertain, BloqueApp retains the request so a retry uses the same request and content. Do not create a replacement request just because the network response was lost.

An approved allowance is a fixed elapsed-time window that starts when the server records approval. It can begin while you are away from the phone. Delivery delay does not add time. The allowance preserves your bank balance; after it ends, current app rules apply again. A normal approval does not bypass sleep.

How a temporary request becomes access

sequenceDiagram
    participant Phone as Android phone
    participant Server
    participant Approver
    participant OS as Android system
    Phone->>Server: Send request for selected app and duration
    Server->>Approver: Show pending request
    Note over Server,Approver: Optional notification is only a hint, delivery is not guaranteed
    Approver->>Server: Submit decision
    Server-->>Approver: Acknowledge and save decision
    alt Approved
        Server->>Phone: Signed grant is available on receipt refresh
        Phone->>Phone: Verify signature, scope and deadline
        Phone->>OS: Apply temporary access
        OS-->>Phone: Report whether access was applied
    else Denied
        Server->>Phone: Denial is available on receipt refresh
    end

The phone must refresh the receipt and verify the signed grant before Android can apply access. A push notification, SignalR hint, or approval message does not grant access, and Android is not guaranteed to wake in the background.

Ask to always allow an eligible app

An eligible unlisted app can have a separate Always allow this app request. In Apps, open that app and choose Ask to always allow. This permanent-policy request is not a bank session or a timed allowance. The app remains available only after the server decision and a refreshed, verified current policy make it unrestricted. If the policy later changes, the app follows the new rules. If BloqueApp cannot verify the current pairing and signed policy, it sends no request.

Sleep and offline use

Sleep prevents using bank credit. During sleep, a managed app can open only under a valid partner allowance whose signed scope explicitly includes an enabled sleep exception. Sleep does not stop the timer on a fixed allowance; its deadline remains the one set at approval.

After pairing and a successful policy sync, Android evaluates its saved verified rules locally. Bank accounting and already accepted time windows do not need a connection for every access check. While offline, the phone cannot learn a newer policy or a server-side revocation until it reconnects. An unresolved request is not treated as approved.

Set up the phone

Open Settings to connect with the approver, sync policy, and review Android access. These permissions have different roles:

• Usage Access lets Android measure foreground app use for bank accounting. It is enabled manually in Android settings.
• Exact alarms support scheduled expiry and enforcement recovery. Android controls this access; BloqueApp does not silently enable it.
• Notifications may show the active bank-session indicator. They do not grant access. On supported Android versions, a session can still run without notification-shade permission, with the system’s own indication.

If access or accounting cannot be checked safely, the app closes the bank session and keeps saved credit rather than guessing. Review the status in Home and Settings, restore the relevant Android access, then explicitly start a new bank session when available. Do not assume a permission change or restart has resumed a session.

Approver browser notifications are a separate, optional setup. The approver can sign in to the web page and choose Enable notifications in Browser notifications on the browser account they use to review requests. This setting does not belong in the restricted phone’s Android notification settings. Once enabled, supported push notifications can arrive while the approver page is closed; the approver can also reopen the page to review requests. The approver does not need a custom Android app or an open browser tab. A notification still requires an acknowledged server decision before it counts as saved.

Requests and decisions

The approver reviews a request in the web page or from a supported browser notification action. The server must acknowledge a decision before the interface reports it as saved. If the page or phone cannot confirm a result, refresh the receipt when connected. A push notification, SignalR update, or screen message is only a hint; the durable server receipt and a verified signed allowance determine the result.

Prepare a policy proposal

The Policy proposal page lets a paired approver prepare a policy draft and review policy-change requests sent from the phone. Temporary access requests, permanent Always allow this app requests, and policy proposals are separate workflows. A policy proposal changes rules only after an authorized approver accepts it or publishes a saved draft.

Edit a proposal

Open Policy proposal while signed in with a confirmed pairing. Review the current policy's source and effective revisions, then edit app assignments, sleep schedules, date exceptions, shared time-bank limits, or partner approval limits. Familiar app names are display hints. Assignments describe policy membership and do not inspect which apps are installed. Custom package identifiers are an advanced, manual entry.

The advanced JSON editor is optional. After editing JSON, choose Apply JSON to guided editor before saving; pending JSON edits otherwise block submission. Guided changes refresh the JSON view. Server validation remains authoritative.

Save and review

Choose Save draft and review to send the proposal to the server. The saved draft is scoped to your pairing and stored separately from the operator's published policy. The editor shows a comparison only after the server acknowledges the save. Review the before-and-after values, warnings, and any badge identifying changes that loosen restrictions. A comparison describes the proposal; it does not mean the change has been published or applied on the phone.

If the network is unavailable, edits remain unsaved in the open page and can be retried after reconnecting. The editor does not store private policy JSON in browser storage, so closing or reloading the page loses unsaved edits. A draft already acknowledged by the server remains available when you return.

If another draft version was saved, a conflict preserves the edits in the current page and offers the latest server version. If the underlying policy changed, the draft is stale. You can load the latest version or explicitly restart the proposal from the current policy; restarting discards the older proposal.

Review a phone proposal

Review lists each requested change separately. A reason appears only when supplied, and the server-check explanation is separate from your reason. Review summaries and validation errors are brought into view. New live decisions are also revealed once while the proposal screen is open; routine refreshes keep your scroll position.

On the phone, open Settings and choose Suggest policy changes. The form uses the current verified policy as its baseline and supports bank capacity, refill and daily minimum, plus weekday and weekend sleep times. An optional reason helps your partner understand the request. Choose Review changes, check the exact before-and-after values, then Send this proposal. A waiting status means the server saved the proposal; it does not change access. Your reason appears separately under Your reason. BloqueApp stores the exact retry request encrypted on the phone so an uncertain network result can be reconciled safely. The phone checks proposal status when the screen opens and receives live decision hints while that screen stays open. Check proposal status remains available for recovery. On Home, Suggest policy changes opens the same flow. If the app is backgrounded, killed or asleep, reopen the proposal screen to learn the result; native background notifications are not implemented.

The approver reviews the reason, readable changes and any warning that a proposal may loosen restrictions on the Policy proposal page. Only an approver account enabled by the server can decide it. Accept publishes the requested change for this pairing only when the policy base is still current. If that base changed, acceptance returns a conflict and the approver can reject the stale proposal. This does not edit the operator's source policy.

With browser notifications enabled, a new phone proposal can alert the approver even when the page is closed. Tap the notification to open that exact proposal, then review and decide in the authenticated page. Policy notifications have no Approve/Deny shortcut. While an approver page is open, live hints refresh pending requests and publication reports automatically without replacing unsaved editor changes. Notification delivery is not guaranteed; the durable proposal remains available when the page reopens.

Publish a saved draft

An approver account must be enabled by the operator in server configuration before it can publish. No account is enabled by default, and the page cannot grant itself authority. After saving and reviewing a draft, the approver can publish it only while that saved review is current, with no unsaved edits or unapplied JSON changes. Publication creates an effective policy revision for this pairing and leaves the operator source policy unchanged. A later source update can supersede it. Existing timed allowances keep their deadline, and saved bank state follows the existing policy-transition rules.

The dashboard reports Published, Received by phone, and Applied / verified by phone separately. Receipt means Android stored the verified policy in its durable cache. Applied means Android reconciled operating-system access and reported the result under the same pairing. Missing timestamps mean unknown; displayed times are the last device reports, not continuous proof. The phone syncs policy when it is active, so publishing does not wake it or guarantee instant delivery.

See requests for retries and decision states, offline behavior for local enforcement, and limitations for capabilities that are not available.