> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timetracker.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Android widget

> Start and stop the TimeTracker timer and tick off tasks from your Android home screen, without opening the app. What the widget shows and how it stays fresh.

The Android widget puts your tasks and the timer on your home screen. One tap
starts a timer. No app to open.

<Warning>
  The widget ships with the TimeTracker mobile app, which is **not yet published**
  to Google Play. There is no download link to give you today. This page describes
  what the widget does so you know what is coming.
</Warning>

## The two widgets

| Widget           | Size           | What it shows                                   |
| ---------------- | -------------- | ----------------------------------------------- |
| **Task list**    | 4×2, resizable | Your tasks, with a play or stop control on each |
| **Active timer** | 2×2            | The running task and a live counter             |

### Task list

A scrollable list of tasks assigned to you.

| Part                        | What it does                                                |
| --------------------------- | ----------------------------------------------------------- |
| Open tasks                  | Listed at the top                                           |
| **Completed (n)**           | A section header, with your completed tasks under it        |
| A row's circle              | Tap to complete the task. Tap a completed row to reopen it. |
| A row's play or stop button | Start or stop a timer on that task                          |
| The running row             | Shows a live counter that ticks on its own                  |

### Active timer

| State                       | What it shows                                         |
| --------------------------- | ----------------------------------------------------- |
| A timer is running          | The task title and a live counter, with a stop button |
| Nothing is running          | **No timer running**, with a start control            |
| The task cannot be resolved | **Timer running**, with the counter                   |

There is also a refresh control.

## What you can do

| Action                  | From          |
| ----------------------- | ------------- |
| Start a timer on a task | Either widget |
| Stop the running timer  | Either widget |
| Complete a task         | Task list     |
| Reopen a completed task | Task list     |
| Refresh                 | Either widget |

Taps respond immediately. The widget repaints straight away and then confirms
with the server, so it never feels like it is waiting.

## Setting it up

There is nothing to pair. No code, no token, no linking screen.

<Steps>
  <Step title="Install the mobile app">
    See [Mobile app](/integrations/mobile-app).
  </Step>

  <Step title="Sign in">
    The same account and workspace as the web app.
  </Step>

  <Step title="Add the widget">
    Long-press your Android home screen, find TimeTracker in the widget list, and
    drag one out.
  </Step>
</Steps>

The app sets up the widget's access quietly the first time you are signed in. If
that does not succeed, it tries again the next time you open the app.

<Note>
  The widget talks to TimeTracker directly, which is why taps are near-instant. It
  never has more access than you do – it can only see and change your own tasks and
  your own timer.
</Note>

## How it stays up to date

| Trigger             | When                                                                     |
| ------------------- | ------------------------------------------------------------------------ |
| A silent push       | Within seconds of your timer or tasks changing, even with the app closed |
| A periodic refresh  | About every 30 minutes, as a backstop                                    |
| The refresh control | Whenever you tap it                                                      |

So if you start a timer on your laptop, the widget on your phone catches up
within seconds without you touching it.

## Everything goes through the same rules

A tap on the widget runs exactly the same logic as the same action inside
TimeTracker.

| Widget action   | Still applies                                                       |
| --------------- | ------------------------------------------------------------------- |
| Start a timer   | Only one timer runs at a time                                       |
| Stop a timer    | Your rate is snapshotted onto the entry                             |
| Complete a task | Watchers are notified, recurrence fires, the audit trail records it |

There is no shortcut path. A time entry started from the widget is the same
record as one started at your desk.

## Example

Jonas Bergman keeps the task list widget on his home screen.

<Steps>
  <Step title="Morning">
    He taps play on "API integration" for Harbor Logistics – Mobile App. The row
    starts counting.
  </Step>

  <Step title="Lunch">
    He taps stop. Two hours are recorded. At $120/hour that is $240 of billable
    value.
  </Step>

  <Step title="Afternoon">
    He finishes the task and taps its circle. It moves under **Completed**.
    Priya gets the notification. Jonas does not – he did it.
  </Step>

  <Step title="Later">
    A review reopens the task on the web. Within seconds the widget shows it back
    under open work.
  </Step>
</Steps>

## Permissions

| To use the widget     | You need     |
| --------------------- | ------------ |
| Start and stop timers | `time.track` |

Anyone who may run a timer may use the widget. It shows your own tasks only.

## When your access ends

The widget stops working immediately when your access does.

| Event                              | What happens                                                  |
| ---------------------------------- | ------------------------------------------------------------- |
| You are removed from the workspace | The widget's access is revoked in the same moment             |
| Your account is deleted            | Same                                                          |
| The workspace is deleted           | Same                                                          |
| You sign out of the app            | Access is revoked and the credentials on your phone are wiped |

The widget's next request fails and it shows itself as signed out. There is no
window where a removed person's widget keeps working.

## Common questions

<AccordionGroup>
  <Accordion title="Where do I get it?">
    It ships with the mobile app, which is not published yet. There is no Google
    Play listing to point you at.
  </Accordion>

  <Accordion title="Do I need to pair or enter a code?">
    No. Sign in to the app once, then add the widget from your home screen. The
    app handles the rest quietly.
  </Accordion>

  <Accordion title="Is there an iPhone widget?">
    The Android widgets are the ones described here. Check the app's own release
    notes for iOS.
  </Accordion>

  <Accordion title="Does the widget drain my battery?">
    It does not poll. It waits for a silent push and repaints, with an occasional
    periodic refresh as a backstop.
  </Accordion>

  <Accordion title="Can I see someone else's tasks on the widget?">
    No. It shows tasks assigned to you, in your current workspace.
  </Accordion>

  <Accordion title="I started a timer on the web. Does the widget know?">
    Yes, within seconds. It is one timer on one account.
  </Accordion>

  <Accordion title="Does the widget bypass location rules?">
    No. Widget actions run the same checks as the app.
  </Accordion>
</AccordionGroup>

## Troubleshooting

**The widget says I am signed out.** Open the app and sign in. If you were
removed from the workspace, your access ended – ask an Owner or Admin.

**The widget is stale.** Tap refresh. If it stays stale, open the app once to
re-establish its access.

**A timer will not start.** Another timer is already running. Stop it first.

**My tasks are missing.** The widget shows tasks assigned to you in your current
workspace. If you switched workspaces on the web, open the app to catch up.

## Related guides

<CardGroup cols={2}>
  <Card title="Mobile app" icon="mobile" href="/integrations/mobile-app">
    The app the widget ships with.
  </Card>

  <Card title="Using the timer" icon="play" href="/time-tracking/using-the-timer">
    How the timer works everywhere.
  </Card>

  <Card title="My tasks" icon="square-check" href="/tasks/my-tasks">
    The tasks the widget lists.
  </Card>

  <Card title="Track your first hour" icon="clock" href="/getting-started/track-your-first-hour">
    Start here if you are new.
  </Card>

  <Card title="Integrations overview" icon="plug" href="/integrations/overview">
    Everything TimeTracker connects to.
  </Card>

  <Card title="Remove a member" icon="user-minus" href="/team/remove-a-member">
    What ending access does.
  </Card>
</CardGroup>