https://github.com/jiesou/oppo_cloud_tracker
Use the "Find My Phone" of OPPO (HeyTap) Cloud to locate OPPO/OnePlus devices and integrate into HomeAssistant to provide DeviceTracker. Requires a Selenium Gird
https://github.com/jiesou/oppo_cloud_tracker
homeassistant homeassistant-integration oneplus oppo selenium selenium-grid
Last synced: 4 months ago
JSON representation
Use the "Find My Phone" of OPPO (HeyTap) Cloud to locate OPPO/OnePlus devices and integrate into HomeAssistant to provide DeviceTracker. Requires a Selenium Gird
- Host: GitHub
- URL: https://github.com/jiesou/oppo_cloud_tracker
- Owner: jiesou
- License: mit
- Created: 2025-08-04T10:13:00.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-02-10T01:22:56.000Z (4 months ago)
- Last Synced: 2026-02-10T06:46:55.373Z (4 months ago)
- Topics: homeassistant, homeassistant-integration, oneplus, oppo, selenium, selenium-grid
- Language: Python
- Homepage:
- Size: 84 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# OPPO Cloud HeyTap Tracker
Use the [OPPO (HeyTap) Cloud](https://cloud.oppo.com) "Find My Phone" feature to locate OPPO/OnePlus devices and integrate them into Home Assistant as device tracker entities.
[简体中文文档](README.zh.md)
## Features
This integration provides the following information for your OPPO/OnePlus devices:
- **Device model**
- **Location name**
- **GPS coordinates**
- **Last update time**
- **Online status**
- *Might* support multiple devices, but **not tested**
## Requirements
The integration works via Playwright (Selenium-like) and only supports login by phone number and password.
**Warning: Password storage security is NOT guaranteed**
It requires a **separate remote browser backend supporting CDP, such as [Browserless](https://github.com/browserless/browserless)**, or it also supports [Selenium Grid](https://www.selenium.dev/documentation/grid) instances.
If you don't have a machine to run Browserless locally, you can also consider some cloud-based solutions.
### Remote Browser Backend Setup
#### Option 1: Playwright + CDP (Recommended)
It is recommended to deploy a Playwright + CDP browser backend using the official Docker `browserless/chromium` image.
Example `docker-compose.yml`:
```yaml
name: browserless
services:
browserless-chrome:
container_name: browserless-chrome
image: ghcr.io/browserless/chromium:latest
environment:
- CONCURRENT=3
- TIMEOUT=600000
- TOKEN=[TOKEN(changeme)]
ports:
- target: 3000
published: "3000"
protocol: tcp
restart: unless-stopped
```
Then you will get your "Remote Browser URL", which looks like:
`ws://[your_docker_hostname]:3000/chromium/playwright?token=[TOKEN(changeme)]`
Make sure your Home Assistant instance can access the Docker container.
If you don't need the advanced features of Browserless, a standard `playwright/chrome` image should also work.
#### Option 2: Selenium Grid
You can also use the traditional Selenium Grid API, but it is not recommended.
This implementation is based on [Playwright's support for Selenium Grid](https://playwright.dev/python/docs/selenium-grid). Selenium is less reliable and has worse performance and efficiency compared to Playwright + CDP.
It is recommended to deploy Selenium Grid using the official Docker `selenium/standalone-chrome` image.
Example `docker-compose.yml`:
```yaml
name: selenium
services:
standalone-chrome:
container_name: selenium-chrome
image: selenium/standalone-chrome:latest
shm_size: 2gb
environment:
# External will access standalone-chrome via SE_NODE_GRID_URL, which is necessary if network forward is configured.
- SE_NODE_GRID_URL=http://[your_docker_hostname]:4444
shm_size: 2gb
ports:
- target: 4444
published: "4444"
protocol: tcp
- target: 7900
published: "7900"
protocol: tcp
restart: unless-stopped
```
Then you will get your "Remote Browser URL", which looks like:
`http://[your_docker_hostname]:4444/wd/hub`
Make sure your Home Assistant instance can access the Docker container.
## Installation
### Method 1: HACS (Recommended)
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=jiesou&repository=oppo_cloud_tracker&category=integration)
### Method 2: Manual Installation
1. Download this repository
2. Copy the `custom_components/oppo_cloud_tracker` folder to your Home Assistant's `custom_components` directory
3. Restart Home Assistant
## Configuration
### Step 1: Add Integration
1. Go to **Settings** → **Devices & Services**
2. Click **Add Integration**
3. Search for "OPPO Cloud HeyTap Tracker"
4. Click to add the integration
### Step 2: Configure Connection
You will need to provide:
- **Remote Browser URL**: The URL of your remote browser instance
- For Browserless: `ws://[your_docker_hostname]:3000/chromium/playwright?token=[TOKEN(changeme)]`
- For Selenium Grid: `http://[your_docker_hostname]:4444/wd/hub`
- Make sure your Home Assistant instance can access the Docker container
- **OPPO Phone Number**: Your OPPO account phone number (**only +86 supported**)
- **OPPO Password**: Your OPPO account password (**Warning again: password security is NOT guaranteed**)
After setup, you can also configure the scan interval (default: 300 seconds / 5 minutes).
The integration creates a virtual switch called "Keep Browser Session" to control session behavior:
- **ON**: Keeps the browser session active between updates
- Allows higher refresh frequency
- Requires devices to continuously report GPS (high battery consumption)
- Better for real-time tracking
- **OFF** (default): Closes the browser session after each update
- Restarts the browser and re-logs into OPPO Cloud for each update
- Lower battery impact on devices
- Suitable for periodic location checks
It also provides a `oppo_cloud_tracker.locate` service for manually triggering an immediate device location update in automations.
## FAQ
1. **Cannot connect to the remote browser**
- Verify the Remote Browser URL is correct
- For Selenium Grid, check that SE_NODE_GRID_URL is configured correctly. Ensure Home Assistant can access it: **SE_NODE_GRID_URL should be set to the external port and hostname**.
- Ensure Home Assistant can access the Docker container
- Check if the container is running
2. **OPPO login failed**
- Verify your phone number and password are correct
- Only +86 (China) phone numbers are supported
- Try logging in manually to the OPPO Cloud website first
3. **Selenium Grid: session not created from unknown error: cannot create default profile directory**
- You need to add `shm_size: 2gb` in your `docker-compose.yml`, see [SeleniumHQ/docker-selenium](https://github.com/SeleniumHQ/docker-selenium#--shm-size2g)
- Check if the disk space is full
4. **Strange errors or timeouts**
- Since the integration operates via a browser, initialization and fetching usually take more than 10 seconds, which is normal. It is recommended to set a 60s `TIMEOUT` for the Browserless container.
- If it consistently takes more than 30 seconds, it's best to check and restart the remote browser container.
- Restart the Docker container:
```bash
docker restart browserless-chrome
```
- Check container logs:
```bash
docker logs browserless-chrome
```
### Tips & Tricks
- Selenium Grid web VNC viewer: http://[your_docker_hostname]:7900
- Home Assistant logs will show integration activity under `custom_components.oppo_cloud_tracker`
## Disclaimer
This integration is not affiliated with or endorsed by OPPO. It is based on publicly available web interfaces, and all actions on the website follow your configuration. If OPPO changes their website, the integration may stop working. Use at your own risk.