[Google] How To: Find Hub Trackers

Google Find Hub Trackers (Experimental)

Warning

This feature is experimental. It is off unless you set it up, and setting it up means running a small server of your own. Nothing on this page applies to you if you only use AirTags or other Apple Find My tags.

OpenTagViewer can show trackers from Google's Find Hub network next to your Apple tags:

• Add a Google tracker as its own device, with its location and history on the map like any other tag.
• Link a Google tracker to an existing device. This is for DIY tags that advertise on both networks at once: the reports from both end up on one marker.
• Ring it and see it "Nearby" over Bluetooth, the same as an Apple tag.

How it works, and why it needs a server

The app does not sign in to Google itself. It talks to googlefind-service, a small Docker service you run yourself, which talks to Google on your behalf. That service is built on GoogleFindMyTools.

It is a separate service for two reasons: signing in to Google this way needs a desktop browser, and GoogleFindMyTools is GPL-3.0, so building it into this app would put the whole app under that licence. Doing all of this inside the app instead is tracked in #257.

Before you start: what the service holds

Caution

The service's secrets.json contains a Google master token for your whole Google account: not only Find Hub, but also your email, files and everything else on that account. Treat that file like your Google password.

So:

• Run the service on a machine you control.
• If it can be reached from outside your home network, put it behind HTTPS.
• Give it a long, random API token. That token can read every location the service holds.

In the app, the API token and the HTTP password are stored encrypted. The settings screen warns you if the address you enter is http://, because then the token is sent unencrypted.

What you need

• A computer with Google Chrome and Python, once, to sign in to Google.
• A machine that can run Docker and stays on: a home server, a NAS or a small VPS.
• A Google account with Find Hub trackers on it.

Set up the service

The exact commands are in the googlefind-service README. In short:

1. Sign in once, on a desktop. Run GoogleFindMyTools' main.py and sign in to Google in the Chrome window it opens.
2. In the same run, fetch the location of one tracker. This opens a second browser step that retrieves the key needed to decrypt locations. Without it, the service cannot decrypt anything.
3. Copy the result to the service. Copy Auth/secrets.json to the service's data/secrets.json, and make it readable only by its owner (chmod 600).
4. Start the service. Set API_TOKEN in its .env, run docker compose up -d --build, then check that http://localhost:8090/health answers.
5. Make it reachable from your phone. On your home network, http://<the machine's address>:8090 works, but the token then travels unencrypted over that network. To use it away from home, put it behind a reverse proxy with HTTPS. HTTP Basic Auth on the proxy is optional; the app supports it.

If Google ever stops accepting the service's tokens, /health shows an error. Repeat steps 1 to 3 and restart the service.

Set up the app

1. Open Settings → Extra location sources (experimental).
2. Enter the service's address and API token. If your reverse proxy uses Basic Auth, enter that username and password too.
3. Tap Test connection. It should say how many trackers the service found.

Then, either:

• Add a tracker as a device: in the ⋮ menu on the map or on My Devices, choose Add from Google Find Hub (experimental) and pick the tracker.
• Or link one to a device you already have: on that device's page, open the ⋮ menu, choose Link Google tracker (experimental) and pick it. Choose None to remove the link.

When a position came from Google, the map card says so ("· Google").

What to expect

• Positions from Google can be hours or days old. Google answers with the last position its network has, not necessarily a fresh one.
• Google is only asked for a fresh location when you refresh a tag. The refresh waits up to about 25 seconds for Google's answer. A tracker that has never been located is also asked for once on its own, at most every 30 minutes.
• Ringing has only been tried on a few trackers. Some vendors' trackers may refuse the ring request. If one does, the app tells you why.
• Battery levels are not shown for Google trackers. Their Bluetooth advertisements encrypt it.

Reporting problems

• Problems with the app: open an issue here.
• Problems with the service itself: googlefind-service.