{"id":30226625,"url":"https://github.com/jiesou/oppo_cloud_tracker","last_synced_at":"2026-02-11T06:05:04.980Z","repository":{"id":308312567,"uuid":"1031779031","full_name":"jiesou/oppo_cloud_tracker","owner":"jiesou","description":"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","archived":false,"fork":false,"pushed_at":"2026-02-10T01:22:56.000Z","size":86,"stargazers_count":4,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-10T06:46:55.373Z","etag":null,"topics":["homeassistant","homeassistant-integration","oneplus","oppo","selenium","selenium-grid"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jiesou.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T10:13:00.000Z","updated_at":"2026-02-10T01:23:00.000Z","dependencies_parsed_at":"2025-08-05T09:53:31.716Z","dependency_job_id":null,"html_url":"https://github.com/jiesou/oppo_cloud_tracker","commit_stats":null,"previous_names":["jiesou/oppo_cloud_tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jiesou/oppo_cloud_tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiesou%2Foppo_cloud_tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiesou%2Foppo_cloud_tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiesou%2Foppo_cloud_tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiesou%2Foppo_cloud_tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jiesou","download_url":"https://codeload.github.com/jiesou/oppo_cloud_tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiesou%2Foppo_cloud_tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29327955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T03:52:29.695Z","status":"ssl_error","status_checked_at":"2026-02-11T03:52:23.094Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["homeassistant","homeassistant-integration","oneplus","oppo","selenium","selenium-grid"],"created_at":"2025-08-14T17:01:44.223Z","updated_at":"2026-02-11T06:05:04.975Z","avatar_url":"https://github.com/jiesou.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OPPO Cloud HeyTap Tracker\n\nUse 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.\n\n[简体中文文档](README.zh.md)\n\n\u003cimg width=\"560\" alt=\"ha device\" src=\"https://github.com/user-attachments/assets/5b8dda5c-f751-4f9a-b184-27affb0f72d5\" /\u003e\n\u003cimg width=\"560\" alt=\"device tracker\" src=\"https://github.com/user-attachments/assets/db90e6ea-19fd-416e-9c64-4d0439ff036d\" /\u003e\n\n## Features\n\nThis integration provides the following information for your OPPO/OnePlus devices:\n\n- **Device model**\n- **Location name**\n- **GPS coordinates**\n- **Last update time**\n- **Online status**\n- *Might* support multiple devices, but **not tested**\n\n## Requirements\n\nThe integration works via Playwright (Selenium-like) and only supports login by phone number and password.\n\n**Warning: Password storage security is NOT guaranteed**\n\nIt 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.\n\nIf you don't have a machine to run Browserless locally, you can also consider some cloud-based solutions.\n\n### Remote Browser Backend Setup\n\n#### Option 1: Playwright + CDP (Recommended)\nIt is recommended to deploy a Playwright + CDP browser backend using the official Docker `browserless/chromium` image.\n\nExample `docker-compose.yml`:\n```yaml\nname: browserless\nservices:\n  browserless-chrome:\n    container_name: browserless-chrome\n    image: ghcr.io/browserless/chromium:latest\n    environment:\n      - CONCURRENT=3\n      - TIMEOUT=600000\n      - TOKEN=[TOKEN(changeme)]\n    ports:\n      - target: 3000\n        published: \"3000\"\n        protocol: tcp\n    restart: unless-stopped\n```\n\nThen you will get your \"Remote Browser URL\", which looks like:\n`ws://[your_docker_hostname]:3000/chromium/playwright?token=[TOKEN(changeme)]`\nMake sure your Home Assistant instance can access the Docker container.\n\nIf you don't need the advanced features of Browserless, a standard `playwright/chrome` image should also work.\n\n#### Option 2: Selenium Grid\n\nYou can also use the traditional Selenium Grid API, but it is not recommended.\nThis 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.\n\nIt is recommended to deploy Selenium Grid using the official Docker `selenium/standalone-chrome` image.\n\nExample `docker-compose.yml`:\n```yaml\nname: selenium\nservices:\n  standalone-chrome:\n    container_name: selenium-chrome\n    image: selenium/standalone-chrome:latest\n    shm_size: 2gb\n    environment:\n      # External will access standalone-chrome via SE_NODE_GRID_URL, which is necessary if network forward is configured.\n      -  SE_NODE_GRID_URL=http://[your_docker_hostname]:4444\n    shm_size: 2gb\n    ports:\n      - target: 4444\n        published: \"4444\"\n        protocol: tcp\n      - target: 7900\n        published: \"7900\"\n        protocol: tcp\n    restart: unless-stopped\n```\n\nThen you will get your \"Remote Browser URL\", which looks like:\n`http://[your_docker_hostname]:4444/wd/hub`\nMake sure your Home Assistant instance can access the Docker container.\n\n## Installation\n\n### Method 1: HACS (Recommended)\n\n[![Open a repository in your Home Assistant HACS.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=jiesou\u0026repository=oppo_cloud_tracker\u0026category=integration)\n\n### Method 2: Manual Installation\n\n1. Download this repository\n2. Copy the `custom_components/oppo_cloud_tracker` folder to your Home Assistant's `custom_components` directory\n3. Restart Home Assistant\n\n## Configuration\n\n### Step 1: Add Integration\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Click **Add Integration**\n3. Search for \"OPPO Cloud HeyTap Tracker\"\n4. Click to add the integration\n\n### Step 2: Configure Connection\n\nYou will need to provide:\n\n- **Remote Browser URL**: The URL of your remote browser instance\n  - For Browserless: `ws://[your_docker_hostname]:3000/chromium/playwright?token=[TOKEN(changeme)]`\n  - For Selenium Grid: `http://[your_docker_hostname]:4444/wd/hub`\n  - Make sure your Home Assistant instance can access the Docker container\n- **OPPO Phone Number**: Your OPPO account phone number (**only +86 supported**)\n- **OPPO Password**: Your OPPO account password (**Warning again: password security is NOT guaranteed**)\n\nAfter setup, you can also configure the scan interval (default: 300 seconds / 5 minutes).\n\nThe integration creates a virtual switch called \"Keep Browser Session\" to control session behavior:\n\n- **ON**: Keeps the browser session active between updates\n  - Allows higher refresh frequency\n  - Requires devices to continuously report GPS (high battery consumption)\n  - Better for real-time tracking\n\n- **OFF** (default): Closes the browser session after each update\n  - Restarts the browser and re-logs into OPPO Cloud for each update\n  - Lower battery impact on devices\n  - Suitable for periodic location checks\n\nIt also provides a `oppo_cloud_tracker.locate` service for manually triggering an immediate device location update in automations.\n\n## FAQ\n\n1. **Cannot connect to the remote browser**\n   - Verify the Remote Browser URL is correct\n   - 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**.\n   - Ensure Home Assistant can access the Docker container\n   - Check if the container is running\n\n2. **OPPO login failed**\n   - Verify your phone number and password are correct\n   - Only +86 (China) phone numbers are supported\n   - Try logging in manually to the OPPO Cloud website first\n\n3. **Selenium Grid: session not created from unknown error: cannot create default profile directory**\n   - You need to add `shm_size: 2gb` in your `docker-compose.yml`, see [SeleniumHQ/docker-selenium](https://github.com/SeleniumHQ/docker-selenium#--shm-size2g)\n   - Check if the disk space is full\n\n4. **Strange errors or timeouts**\n   - 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.\n   - If it consistently takes more than 30 seconds, it's best to check and restart the remote browser container.\n   - Restart the Docker container:\n     ```bash\n     docker restart browserless-chrome\n     ```\n   - Check container logs:\n     ```bash\n     docker logs browserless-chrome\n     ```\n\n### Tips \u0026 Tricks\n\n- Selenium Grid web VNC viewer: http://[your_docker_hostname]:7900\n- Home Assistant logs will show integration activity under `custom_components.oppo_cloud_tracker`\n\n## Disclaimer\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiesou%2Foppo_cloud_tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiesou%2Foppo_cloud_tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiesou%2Foppo_cloud_tracker/lists"}