External companion app for remote control (using broadcast intents)

[Daksh777]

Hi! I really enjoy using Simple Time Tracker and wanted to share an idea I am thinking to work on.

I want to build a separate Android app (a companion app) that lets you control Simple Time Tracker from a web browser on your computer. The companion app would sit between your browser and Simple Time Tracker, passing commands back and forth using the broadcast intent API that the app already supports.

I am opening this issue to share the idea, ask a few questions about the existing API, and make sure I am not missing anything before I start building.

Related issues and PRs

• Issue Feature Request - PC Web Interface Request #427 - PC Web Interface Request
• PR feat: Add REST API and Web UI for remote time tracking #373 - Open pull request that adds a built-in REST API and web UI

PR #373 adds a small web server directly inside Simple Time Tracker. That is a great approach but it requires changes to the app itself and the INTERNET permission. As discussed in the PR, the concern is not that local HTTP is inherently unsafe, but that adding INTERNET permission to the main app changes its trust surface for everyone, including F-Droid users who would get the permission in the manifest even though the server code is play-flavor only. You noted in the PR discussion that a separate plugin app would be the cleaner workaround:

"There is one workaround... Is to have a separate app, like a plugin, that would be installed separately and would have internet permission... time tracker pass data to plugin app, plugin app calls web api."

That is exactly what I am trying to build here. The main app stays exactly as it is. Users who want the web interface install the companion app separately and explicitly opt in. Users who do not want it, including F-Droid users, are completely unaffected.

How it would work

The companion app would do two things:

1. Receive commands from the web browser and send the matching broadcast intent to Simple Time Tracker
2. Listen for the events that Simple Time Tracker already broadcasts (EVENT_STARTED_ACTIVITY, EVENT_STOPPED_ACTIVITY, EVENT_COMPLETED_GOAL) and forward those to the browser so the web UI stays up to date.

The web dashboard would let you start and stop activities, add past records, edit comments, and see what is currently running, etc.

There are a few options for getting commands from the browser to the companion app running on the phone. I am still deciding between them, but here is what I am considering:

• Option 1: Direct local HTTP server in the companion app. The companion app runs a small server on the local network. The browser sends requests to it directly over Wi-Fi. This is the same model as PR feat: Add REST API and Web UI for remote time tracking #373, but the INTERNET permission lives in the companion app instead of the main app, so the main app's privacy guarantee is preserved. The downside is it only works when the phone and computer are on the same network.

• Option 2: Self-hosted relay server. A small server you run yourself (on a home computer or a cheap VPS) acts as the go-between. The companion app and the browser both connect to it. This works over the internet, and your data only passes through infrastructure you control.

• Option 3: Firebase Cloud Messaging (or a similar push service). The companion app listens for push messages from Firebase, and the web dashboard sends commands through Firebase. This makes setup easier since you do not need to run your own server. However, it does mean that the names of your activities and whatever commands you send pass through Google's servers. This has the same kind of privacy concern that was raised in the PR feat: Add REST API and Web UI for remote time tracking #373 discussion, so I would only offer this as a clearly optional mode for users who are comfortable with it, not as the default.

I plan to support Option 1 and Option 2 from the start. Option 3 would be opt-in only, clearly labelled, and off by default.

Some things I want to ask:

1. Is there any way to query the list of all configured activities via a broadcast intent? Right now I can only learn about activities by listening to events as they happen. A way to ask what activities exist would make the web UI much better from the start. I noticed the internal WearCommunicationAPI already has queryActivities() for the Wear OS integration, but that is not accessible from outside the app via broadcast.

2. Is there a way to query what is currently running? Similar to above, I can track state by listening to start and stop events, but a direct query would be more reliable, especially on app restart or reconnect. Again, queryCurrentActivities() exists internally for Wear OS but is not exposed externally.

3. Would you be open to adding two optional query intents, something like ACTION_QUERY_ACTIVITIES and ACTION_QUERY_RUNNING, that respond with a broadcast containing the answer? If yes, I am happy to submit a small PR for that. One clean way to handle this would be to use a signature-level permission for the response broadcast, which you also mentioned in the PR discussion as a way two apps signed with the same key can share data safely.

Happy to hear any concerns or suggestions. Thanks for building such a reliable app.

@av1m I would also really appreciate your inputs and help into this if @Razeeman approves this instead of 373!

[Razeeman]

Hello! Thank you very much for the detailed feedback and great understanding on the discussion in the 373 PR. This is exactly what was meant the "plugin app". This would be a great help and very much appreciated.

Is there any way to query the list of all configured activities via a broadcast intent?
Is there a way to query what is currently running?

Currently there is no broadcast intent for these, but it could be added relatively easy. The only thing is to decide how the answer would look like. Intents are not very good for passing big structured amounts of data. Two options probably are:

• simple answer, something like a comma separated list of activity names and hex color, for example "activity1:ffffff,activity2:ababab" and for currently running something like a comma separated list of activity names and time started, for example "activity1:1772789225". This is very limited, but more user friendly and readable, can be used with apps like Tasker.
• full answer, similar to wear api, with internal data like activity ids, and for currently running also full required data, like comments and tags. Answer could be passed as a json string, and decoded in the companion app.

Also it probably would be possible to add both types of intents, maybe pass an extra in the request intent with the type of answer that is requested, something like "extraAnswerType" with options "simple"/"json" with "simple" being default.
Alternatively, return a versioned json, with v1 being a simple MVP, and expanded in later version if required, with the required version passed in the request.

One clean way to handle this would be to use a signature-level permission for the response broadcast

Intents can be used even without signature-level permission, so the companion app wouldn't be required to be signed with the same signing key as the main app. In this case companion app can be fully third-party community developed, meaning it could be your repo, instead of being integrated in this repo, if this would be more preferable to you. If you don't care about this companion app being integrated in this repo, it would probably be better in the end to go with route of the signature level permission and signing with the same signing key, and use full api (wear api extracted and reused if it would be possible, like 373 PR suggested). It would be much easier to support and version than working with intents.

Separate concern is about data safety with using "Option 2: Self-hosted relay server" is that someone could access it and gain control of tracking data. So maybe it will need some way of session auth or token. Also sensing intents is currently closed behind an explicit settings "Send events" which is disabled by default. Maybe it would be good to also close receiving intents by the similar settings, so it would be explicitly required to opt in.

We can de something like this:

• add ACTION_QUERY_ACTIVITIES / ACTION_QUERY_RUNNING with "simple" answer or "v1 json" answer, no signature level permission required.
• these intents can be used for building a MVP companion app, to see how it would work, confirm usability.
• after that we can either:
  • add intents with full "json" answer or "v2/v3/etc json" answer, and expand companion app MVP, it would be your repo if you want, and mentioned and linked in the readme in this repo as a way to use web interface, or it could be integrated in this repo.
  • go with the full api (wear api reused) and signature level permissions and signing with the same key, companion app will be integrated this repo, you will be mentioned in the app as a contributor same as developers of wear os app and other people who helped with the development.

I would be happy with the either choice, so it is completely up to you.

Sorry if I'm rumbling, hope this makes sense. What do you think?

[av1m]

Thanks @Razeeman and @Daksh777; this makes sense.

I think a good path can be :

1. MVP first:
   Add ACTION_QUERY_ACTIVITIES and ACTION_QUERY_RUNNING with default simple response (Tasker-friendly), plus optional extraAnswerType=json for richer clients.

2. Response format strategy:
   I’d prefer versioned JSON for long-term stability (extraApiVersion=1), while keeping simple as compatibility mode.

3. Security/opt-in:
   Keep receiving/query intents behind an explicit setting (same spirit as “Send events”), disabled by default.

4. Companion transport:
   Start with "Option 1 (local LAN)" for MVP; add auth token/pairing from day one.
   Option 2 (self-hosted relay) can be phase 2.
   Option 3 (FCM) should stay optional and clearly marked.

Another practical idea

Instead of only polling from browser, use WebSocket or SSE between browser ↔ companion app for live updates (lower latency + less overhead).

Another API idea

For query replies, support a callback-style response target (e.g., caller-provided action/package) to reduce broad broadcasts and make routing cleaner.

[Daksh777]

Thank you so much for the detailed response, don't worry about the rumbling ahah, it was all completely understandable @Razeeman!
Also thank you @av1m for your inputs :)

To answer your question directly: I would prefer to keep the companion app in my own repo, at least for now. That feels like the lower friction path to getting something working quickly, and it keeps the scope of changes to this repo small.
If at some point it makes sense to integrate it here, I am happy to revisit that and then merge it with this repo, I'm okay in anything honestly :P

With that in mind, here is what I am thinking for next steps:

For this repo (small PRs I can submit):

1. Add ACTION_QUERY_ACTIVITIES and ACTION_QUERY_RUNNING intents with a simple default answer (comma separated, Tasker friendly) and an optional extraAnswerType extra that accepts "simple" (default) or "json" for structured clients. I like the versioned JSON idea too, so maybe extraAnswerType="json" returns a v1 payload to start, which gives us room to expand later without breaking existing integrations.

2. Add a setting to opt in to receiving query intents, similar to how "Send events" works today and disabled by default. Good call on that, I had not thought about it.

For the companion app repo:

• Start with local LAN HTTP server as the MVP transport. Agree with @av1m that an auth token or pairing step should be in from the start rather than bolted on later, even if it is just a simple shared secret for v1.
• WebSocket or SSE between the browser and the companion app for live updates is a good idea, I was already leaning that way over polling.

Also side thought, the intent payload size should not be a concern in practice. Even with generous estimates for activity names, colors, tags and timestamps, a full JSON response for a typical user would be well under 50KB, far below the 1MB Binder transaction limit.

One question before I start on the PR though @Razeeman: For the json answer type, would you prefer I reuse the WearActivityDTO and WearCurrentStateDTO shapes from the wear_api module as a starting point, or define new intent-specific DTOs? Reusing the wear shapes seems cleaner since the data is essentially the same, but I want to make sure that fits how you want the public API to look before I commit to it.

Also is there any way to contact you (Telegram, Discord, etc.)? I'm sure I might get stuck at some places and would need some help because Kotlin and Java are not my forte, I'd really love some help on a better contact channel if you're okay with it!

Happy to start on the query intents PR whenever you give the go ahead. Thanks again for taking the time to think through all of this.

[Razeeman]

Sure, let's start with intents. Something like this should work?

ACTION_EXTERNAL_QUERY_ACTIVITIES with optional string extra "extra_answer_type". If this broadcast is received, a response intent will be sent with name ACTION_EXTERNAL_RESPONSE_ACTIVITIES with extra named "data":

• if "extra_answer_type" is not present in query intent or it has value "simple" - "data" extra in the response will be a string of comma separated "{activityName}:{colorHex}" for example "work:ff00ff,reading:000aa".
• if "extra_answer_type" is equaled to "json" - "data" extra will a string with json encoded data.

ACTION_EXTERNAL_QUERY_RUNNING with same extra "extra_answer_type". If broadcast is received, a response intent will be sent with name ACTION_EXTERNAL_RESPONSE_RUNNING with same extra named "data":

• if "extra_answer_type" is not present in query intent or it has value "simple" - "data" extra in the response will be a string of comma separated "{activityName}:{timeStartedTimestamp}" for example "work:1772789225,reading:1772789225".
• if "extra_answer_type" is equaled to "json" - "data" extra will a string with json encoded data.

For query replies, support a callback-style response target (e.g., caller-provided action/package) to reduce broad broadcasts and make routing cleaner.

Good idea @av1m , replies should be limited to caller package if this would be possible.

Reusing Wear DTOs would be good. Can be reused as is for now, I'll renamed them later to something more general, like ExternalApiDTO. Also if json will be versioned later, these DTOs also will be versioned. For now let's assume that they are v1.

For the contacting, can we use this thread? So it would be visible to all, maybe it will help someone in the future. I will be checking github more frequently and will try to answer any questions.