apptrail 0.4.0__tar.gz

apptrail-0.4.0/.dockerignore

@@ -0,0 +1,19 @@
+.git
+.venv
+.env
+__pycache__
+*.sqlite3*
+.apptrail
+test-results
+dist
+.pytest_cache
+.ruff_cache
+tests
+docs
+temp
+.idea
+.DS_Store
+.playwright-mcp
+credentials.json
+setup-token
+.env.*

apptrail-0.4.0/.github/scripts/check_installed.py

@@ -0,0 +1,107 @@
+"""Boot the installed wheel outside the checkout and exercise its packaged UI."""
+
+import http.cookiejar
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import apptrail
+
+checkout = Path(__file__).resolve().parents[2]
+assert not Path(apptrail.__file__).resolve().is_relative_to(checkout / "src"), (
+    "This smoke check must run against the installed wheel, not an editable checkout."
+)
+environment = {
+    key: value
+    for key, value in os.environ.items()
+    if key not in {"SERPAPI_KEY", "SERPAPI_API_KEY", "APPTRAIL_ORIGIN", "PYTHONPATH"}
+}
+
+with tempfile.TemporaryDirectory(prefix="apptrail-wheel-") as temporary:
+    directory = Path(temporary)
+    with (directory / "server.log").open("w+") as log:
+        process = subprocess.Popen(
+            [sys.executable, "-m", "apptrail.cli", "--no-browser", "--data-dir", str(directory)],
+            cwd=directory,
+            env=environment,
+            stdout=log,
+            stderr=log,
+        )
+        try:
+            deadline = time.monotonic() + 15
+            url = None
+            while time.monotonic() < deadline:
+                log.seek(0)
+                output = log.read()
+                if process.poll() is not None:
+                    raise AssertionError(f"Installed app exited during startup:\n{output}")
+                match = re.search(r"Web UI: (http://[^\s]+)", output)
+                if match:
+                    url = match.group(1)
+                    try:
+                        with urllib.request.urlopen(url + "/healthz", timeout=0.5) as response:
+                            if json.load(response)["status"] == "ok":
+                                break
+                    except (OSError, urllib.error.URLError):
+                        pass
+                time.sleep(0.05)
+            else:
+                raise AssertionError(f"Installed app did not become ready:\n{output}")
+
+            browser = urllib.request.build_opener(
+                urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar())
+            )
+            try:
+                browser.open(url + "/api/state", timeout=5)
+            except urllib.error.HTTPError as error:
+                assert error.code == 401
+            else:
+                raise AssertionError("The installed app exposed anonymous workspace data")
+            request = urllib.request.Request(
+                url + "/api/auth/setup",
+                data=json.dumps(
+                    {
+                        "username": "package-check",
+                        "password": "Package smoke test password 1!",
+                        "setup_token": (directory / "setup-token").read_text(),
+                    }
+                ).encode(),
+                headers={"Content-Type": "application/json", "X-AppTrail-Request": "1"},
+            )
+            with browser.open(request, timeout=5) as response:
+                assert json.load(response)["csrf_token"]
+            with browser.open(url + "/api/state", timeout=5) as response:
+                state = json.load(response)
+                assert state["apps"] == [] and state["monitors"] == []
+                assert state["configured"] is False
+            with browser.open(url + "/api/regions", timeout=5) as response:
+                assert json.load(response)["countries"]["gb"] == "United Kingdom"
+            for path in (
+                "/",
+                "/static/app.js",
+                "/static/history-chart.js",
+                "/static/tracking.js",
+                "/static/insights-data.js",
+                "/static/insights-ui.js",
+                "/static/vendor/chart.umd.min.js",
+                "/static/vendor/chart-LICENSE.md",
+            ):
+                with browser.open(url + path, timeout=5) as response:
+                    assert response.status == 200 and response.read(), path
+            print(
+                "Installed wheel passed startup, owner setup, region catalog, state, and UI assets."
+            )
+        finally:
+            process.terminate()
+            try:
+                process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=5)

apptrail-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: Tests and package
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest -m "not live and not browser" --strict-markers --durations=10
+      - run: uv run ruff check src tests .github/scripts
+      - run: uv run ruff format --check src tests .github/scripts
+      - run: uv build
+      - name: Check packaged UI and migrations
+        run: |
+          uv run python - <<'PY'
+          from pathlib import Path
+          from zipfile import ZipFile
+          wheel = next(Path("dist").glob("*.whl"))
+          with ZipFile(wheel) as archive:
+              for name in ("static/auth.html", "static/auth.js", "static/auth.css", "auth.py", "regions.json", "static/index.html", "static/style.css", "static/app.js", "static/history-chart.js", "static/tracking.js", "static/insights-data.js", "static/insights-ui.js", "static/favicon.svg", "static/vendor/chart.umd.min.js", "static/vendor/chart-LICENSE.md", "static/vendor/lucide-icons.js", "static/vendor/lucide-LICENSE.txt", "migrations/001_initial.sql"):
+                  assert archive.read(f"apptrail/{name}"), name
+              license_name = next(name for name in archive.namelist() if name.endswith(".dist-info/licenses/LICENSE"))
+              assert archive.read(license_name)
+          PY
+      - run: uvx --from ./dist/*.whl apptrail --version
+      - run: uv run --isolated --no-project --with ./dist/*.whl python .github/scripts/check_installed.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions-${{ matrix.os }}-${{ matrix.python }}
+          path: dist/*
+  frontend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: node --test tests/*.test.mjs
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run playwright install --with-deps chromium
+      - run: uv run pytest -m browser --strict-markers --durations=10 --basetemp=browser-artifacts
+        env:
+          APPTRAIL_BROWSER_TESTS: "1"
+          APPTRAIL_BROWSER_CHANNEL: ""
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: browser-failure-artifacts
+          path: browser-artifacts/**/*.png

apptrail-0.4.0/.github/workflows/live.yml

@@ -0,0 +1,32 @@
+name: Live SerpApi integration tests
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: live-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+jobs:
+  live:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name != 'pull_request' ||
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - name: Run live tests with the repository secret
+        run: |
+          uv run python -c 'import os; assert os.getenv("SERPAPI_KEY"), "Configure the SERPAPI_KEY repository secret before running live tests."'
+          uv run pytest -m live -v --tb=short --strict-markers --durations=10
+        env:
+          SERPAPI_KEY: ${{ secrets.SERPAPI_KEY }}

apptrail-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+jobs:
+  build:
+    if: startsWith(github.event.release.tag_name, 'v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Verify the release commit belongs to main
+        run: |
+          if ! git merge-base --is-ancestor HEAD origin/main; then
+            echo "::error::The release tag must point to a commit on main."
+            exit 1
+          fi
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - name: Verify the release tag matches the package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          from apptrail import __version__
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          if os.environ["RELEASE_TAG"] != expected:
+              raise SystemExit(f"Release tag must be {expected} to match pyproject.toml.")
+          if __version__ != version:
+              raise SystemExit("src/apptrail/__init__.py must match the package version.")
+          PY
+      - run: uv run pytest -m "not live and not browser" --strict-markers --durations=10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: node --test tests/*.test.mjs
+      - run: uv run playwright install --with-deps chromium
+      - run: uv run pytest -m browser --strict-markers --durations=10
+        env:
+          APPTRAIL_BROWSER_TESTS: "1"
+          APPTRAIL_BROWSER_CHANNEL: ""
+      - run: uv build
+      - run: uv run --isolated --no-project --with ./dist/*.whl python .github/scripts/check_installed.py
+      - run: uv run --isolated --no-project --with ./dist/*.tar.gz python .github/scripts/check_installed.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment:
+      name: pypi
+      url: https://pypi.org/project/apptrail/
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - run: uv publish --trusted-publishing always

apptrail-0.4.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.env
+dist/
+*.sqlite3*
+.apptrail/
+test-results/
+.playwright-mcp/
+*.egg-info/
+.idea/
+.DS_Store
+credentials.json
+setup-token
+.env.*
+!.env.example
+
+/temp/

apptrail-0.4.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.14-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:0.12.19 /uv /usr/local/bin/uv
+WORKDIR /build
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT=/opt/venv
+COPY pyproject.toml uv.lock README.md LICENSE ./
+COPY src ./src
+RUN uv sync --locked --no-dev --no-install-project \
+    && uv build --wheel \
+    && uv pip install --python /opt/venv/bin/python --no-deps dist/*.whl
+
+FROM python:3.14-slim
+RUN groupadd --gid 10001 apptrail && useradd --uid 10001 --gid apptrail --create-home apptrail \
+    && mkdir /data && chown apptrail:apptrail /data
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH" APPTRAIL_DATA_DIR=/data PYTHONUNBUFFERED=1
+USER apptrail
+VOLUME ["/data"]
+EXPOSE 80
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:80/healthz', timeout=4)" || exit 1
+ENTRYPOINT ["apptrail"]
+CMD ["--host", "0.0.0.0", "--port", "80", "--no-browser"]

apptrail-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppTrail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apptrail-0.4.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: apptrail
+Version: 0.4.0
+Summary: Open-source app visibility tracking across the App Store, Google Play, and AI search.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115,<1
+Requires-Dist: uvicorn>=0.30,<1
+Requires-Dist: serpapi>=0.1.5,<1
+Requires-Dist: sqlalchemy>=2.0,<3
+Requires-Dist: platformdirs>=4,<5
+Requires-Dist: filelock>=3.16,<4
+Requires-Dist: python-dateutil>=2.9,<3
+Requires-Dist: argon2-cffi>=25.1,<26
+Requires-Dist: pillow>=12,<13
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/serpapi/apptrail
+Project-URL: Documentation, https://github.com/serpapi/apptrail/blob/main/README.md
+Project-URL: Repository, https://github.com/serpapi/apptrail
+Project-URL: Issues, https://github.com/serpapi/apptrail/issues
+Description-Content-Type: text/markdown
+
+# AppTrail
+
+**Open-source app visibility tracking across the App Store, Google Play, and AI search.**
+
+![AppTrail dashboard](https://raw.githubusercontent.com/serpapi/apptrail/main/docs/images/apptrail-banner.png)
+
+Your next user might search the App Store, browse Google Play, or ask an AI which app to use. AppTrail follows those searches and keeps a history of where your app appears.
+
+Connect your [SerpApi](https://serpapi.com/) account, choose your app, and add the keywords and questions you want to follow. Open any check to see the saved results and the evidence behind a match.
+
+## What you can track
+
+- **Store rankings.** Follow your app's position for the keywords people use in the App Store and Google Play. See which searches bring your app near the top and how those positions change over time.
+- **Competitor comparisons.** Track competing apps alongside your own for the same keywords and AI questions. See where you lead, where competitors appear ahead of you, and how the gap changes.
+- **Countries and regions.** Follow store rankings and Google AI visibility in the countries you care about. Compare the same keyword or question across markets to see where your app is easier to find.
+- **AI mentions and citations.** See whether Google AI Mode, Google AI Overviews, and Bing Copilot mention your app when answering questions. Read the saved answers and check whether they link to your store listing or website.
+- **Listing history.** Keep a timeline of changes to your app's or a competitor's store listing. Compare titles, descriptions, pricing, icons, and screenshots to see what changed between checks.
+- **Ranking alerts.** Get in-app notifications when your app loses ground after ranking in the top 10. See which keyword and country changed, then open the saved results.
+- **Scheduled or manual checks.** Run checks on demand, or schedule them daily, weekly, every two weeks, or monthly. Review expected credit usage before starting and see your remaining SerpApi balance in Settings.
+- **Your history to keep.** Export results as CSV files for your own analysis and download backups of your workspace, including saved history.
+
+## Run AppTrail
+
+You need Python 3.11 or newer and a [SerpApi API key](https://serpapi.com/manage-api-key). Enter the key in the setup wizard. Docker includes Python.
+
+Run [apptrail](https://pypi.org/project/apptrail/) with uvx, or install it with pip.
+
+### uvx
+
+```bash
+uvx apptrail
+```
+
+### pip
+
+```bash
+pip install apptrail
+apptrail
+```
+
+Both commands open the web interface on a free localhost port. On first launch, use the setup code printed in the terminal to create your owner account. Sign in before connecting SerpApi or accessing the dashboard. Your account and database stay in a shared user data directory across restarts and package upgrades.
+
+### Docker
+
+Run the image from [Docker Hub](https://hub.docker.com/r/serpapi/apptrail):
+
+```bash
+docker run -d --name apptrail \
+  -p 80:80 \
+  -v apptrail-data:/data \
+  --restart unless-stopped \
+  --stop-timeout 360 \
+  serpapi/apptrail:latest
+```
+
+Run `docker logs apptrail` to find the one-time setup code, then open [localhost](http://localhost), or `http://SERVER_IP` for a remote server, and create your owner account. Connect SerpApi after signing in. The named volume preserves your account and data when the container is replaced.
+
+The image supports Intel/AMD and ARM Linux. If port `80` is already in use, change the mapping to `-p 8080:80` and open `http://localhost:8080`. See [self-hosting](https://github.com/serpapi/apptrail/blob/main/docs/SELF_HOSTING.md) for CapRover, Coolify, Docker Compose, building from source, HTTPS, and backups.
+
+## Get Started
+
+### Set up tracking
+
+1. Create your AppTrail owner account using the server’s setup code, then connect SerpApi and verify your key.
+2. Search for your iOS or Android app, or paste its store URL. Select at least one listing; AppTrail verifies and saves its identifier.
+3. Add store keywords such as “habit tracker” and AI questions such as “Which is the best iOS app for building a daily routine?”
+4. Choose one or more countries, a language, and a refresh frequency. Review the usage estimate and start tracking.
+
+The first checks run immediately. Keep the AppTrail process or Docker container running for automatic checks; the browser can be closed. If the process stops, your history remains saved and overdue checks resume when it starts again. Missed historical results cannot be reconstructed.
+
+Skipped queries during setup? The **Finish setting up** checklist on Overview links directly to store keywords and AI questions. Each step is optional, and the checklist closes when every step is completed or skipped. Reopen it from **Settings → Setup checklist**.
+
+To compare countries, open the Overview chart and choose **Compare → Countries**. Choose a store or AI source, narrow to a keyword or question, and select the countries to show. Bing Copilot has global results and is available in the Sources view.
+
+### Compare competitors
+
+Choose **Add competitors** beneath any search in Overview, Store rankings, or AI visibility. The **Apps & competitors** panel shows each app’s position or AI mentions and citations from the same saved check. Select apps from your workspace, or use **Find a competitor** to verify a new app’s store listing.
+
+Adding an existing app to a search reuses saved results and shares future checks, so it does not use extra tracking searches. Discovering a new app, verifying its listings, and manual store-detail refreshes can use separate credits. Store comparisons require a verified listing on the matching platform.
+
+### Explore changes
+
+Open **Apps & competitors → Open query matrix** beneath a query to compare saved results across its countries. Each cell includes its check time and opens the underlying evidence. Different languages, devices, and search depths stay separate.
+
+On Overview, switch the history panel from **Trend** to **Distribution** to see counts and percentages for positions 1–3, 4–10, 11–50, 51+, and results where the app was not found. Click a group to inspect its queries. Changes compare the latest check for each app/query combination with the preceding equal-length period. Only combinations checked successfully in both periods contribute to the change counts; failed checks and featured-only placements are shown separately.
+
+The notification bell reports a drop of at least five positions from a previous top-10 rank, an exit from the top 10, or disappearance from a sufficiently deep checked result set. Two successful checks must confirm a loss. An intervening failed check resets confirmation, and continuing losses do not produce duplicate alerts until the ranking recovers. Notifications, matrices, and distributions use saved search data and consume no extra SerpApi credits.
+
+### Track listing history
+
+Open **Listing history → Track a listing**. Collection is off by default. Select an app, store, country, and frequency; Google Play also supports a language choice. The credit estimate appears before you enable tracking. Each scheduled check uses one SerpApi product request, with an initial baseline check when tracking starts. Manual checks and retries can consume additional credits.
+
+The timeline highlights changes to the fields returned by the store, including titles, descriptions, versions, pricing, and images. Text comparisons highlight additions and removals. Screenshots can be compared in order, with added and moved images labeled. Supported images are archived locally in the database and included in backups. If an image cannot be archived, the comparison shows an unavailable-image placeholder. AppTrail never substitutes the live image for a missing historical image.
+
+Use **Manage** to change frequency, pause or resume collection, or request a manual check. Pausing preserves history. Unchanged checks are hidden until you select **Show unchanged checks**. Collection requires the AppTrail process to remain running, and begins when you enable it; earlier listing versions cannot be reconstructed.
+
+### Account access
+
+AppTrail requires login for the dashboard and every workspace API, including searches, exports, and backups. First-time setup requires a code from the server terminal, and registration closes after the owner account is created. New server runs require a fresh login. Change your password in Settings, or recover access from the server terminal with `apptrail --reset-password`.
+
+See the [self-hosting guide](https://github.com/serpapi/apptrail/blob/main/docs/SELF_HOSTING.md#public-https-hosting) for optional HTTPS proxy configuration and [authentication details](https://github.com/serpapi/apptrail/blob/main/docs/AUTHENTICATION.md).
+
+## A few useful details
+
+AppTrail uses your own [SerpApi account](https://serpapi.com/) to fetch data. Discovery, product verification, and tracking requests can consume credits. Identical tracked searches are shared across apps. Settings shows an estimate of monthly usage and your account-wide remaining balance.
+
+### Development
+
+To contribute or customize AppTrail, start with the [development guide](https://github.com/serpapi/apptrail/blob/main/docs/DEVELOPMENT.md). It covers local setup with uv, the project layout, running tests, and building packages.
+
+### Self-hosting
+
+Keep AppTrail running on your own server with persistent storage for your workspace. The [self-hosting guide](https://github.com/serpapi/apptrail/blob/main/docs/SELF_HOSTING.md) walks through Docker, Docker Compose, CapRover, and Coolify, with instructions for HTTPS, backups, and updates.

apptrail-0.4.0/README.md

@@ -0,0 +1,113 @@
+# AppTrail
+
+**Open-source app visibility tracking across the App Store, Google Play, and AI search.**
+
+![AppTrail dashboard](https://raw.githubusercontent.com/serpapi/apptrail/main/docs/images/apptrail-banner.png)
+
+Your next user might search the App Store, browse Google Play, or ask an AI which app to use. AppTrail follows those searches and keeps a history of where your app appears.
+
+Connect your [SerpApi](https://serpapi.com/) account, choose your app, and add the keywords and questions you want to follow. Open any check to see the saved results and the evidence behind a match.
+
+## What you can track
+
+- **Store rankings.** Follow your app's position for the keywords people use in the App Store and Google Play. See which searches bring your app near the top and how those positions change over time.
+- **Competitor comparisons.** Track competing apps alongside your own for the same keywords and AI questions. See where you lead, where competitors appear ahead of you, and how the gap changes.
+- **Countries and regions.** Follow store rankings and Google AI visibility in the countries you care about. Compare the same keyword or question across markets to see where your app is easier to find.
+- **AI mentions and citations.** See whether Google AI Mode, Google AI Overviews, and Bing Copilot mention your app when answering questions. Read the saved answers and check whether they link to your store listing or website.
+- **Listing history.** Keep a timeline of changes to your app's or a competitor's store listing. Compare titles, descriptions, pricing, icons, and screenshots to see what changed between checks.
+- **Ranking alerts.** Get in-app notifications when your app loses ground after ranking in the top 10. See which keyword and country changed, then open the saved results.
+- **Scheduled or manual checks.** Run checks on demand, or schedule them daily, weekly, every two weeks, or monthly. Review expected credit usage before starting and see your remaining SerpApi balance in Settings.
+- **Your history to keep.** Export results as CSV files for your own analysis and download backups of your workspace, including saved history.
+
+## Run AppTrail
+
+You need Python 3.11 or newer and a [SerpApi API key](https://serpapi.com/manage-api-key). Enter the key in the setup wizard. Docker includes Python.
+
+Run [apptrail](https://pypi.org/project/apptrail/) with uvx, or install it with pip.
+
+### uvx
+
+```bash
+uvx apptrail
+```
+
+### pip
+
+```bash
+pip install apptrail
+apptrail
+```
+
+Both commands open the web interface on a free localhost port. On first launch, use the setup code printed in the terminal to create your owner account. Sign in before connecting SerpApi or accessing the dashboard. Your account and database stay in a shared user data directory across restarts and package upgrades.
+
+### Docker
+
+Run the image from [Docker Hub](https://hub.docker.com/r/serpapi/apptrail):
+
+```bash
+docker run -d --name apptrail \
+  -p 80:80 \
+  -v apptrail-data:/data \
+  --restart unless-stopped \
+  --stop-timeout 360 \
+  serpapi/apptrail:latest
+```
+
+Run `docker logs apptrail` to find the one-time setup code, then open [localhost](http://localhost), or `http://SERVER_IP` for a remote server, and create your owner account. Connect SerpApi after signing in. The named volume preserves your account and data when the container is replaced.
+
+The image supports Intel/AMD and ARM Linux. If port `80` is already in use, change the mapping to `-p 8080:80` and open `http://localhost:8080`. See [self-hosting](https://github.com/serpapi/apptrail/blob/main/docs/SELF_HOSTING.md) for CapRover, Coolify, Docker Compose, building from source, HTTPS, and backups.
+
+## Get Started
+
+### Set up tracking
+
+1. Create your AppTrail owner account using the server’s setup code, then connect SerpApi and verify your key.
+2. Search for your iOS or Android app, or paste its store URL. Select at least one listing; AppTrail verifies and saves its identifier.
+3. Add store keywords such as “habit tracker” and AI questions such as “Which is the best iOS app for building a daily routine?”
+4. Choose one or more countries, a language, and a refresh frequency. Review the usage estimate and start tracking.
+
+The first checks run immediately. Keep the AppTrail process or Docker container running for automatic checks; the browser can be closed. If the process stops, your history remains saved and overdue checks resume when it starts again. Missed historical results cannot be reconstructed.
+
+Skipped queries during setup? The **Finish setting up** checklist on Overview links directly to store keywords and AI questions. Each step is optional, and the checklist closes when every step is completed or skipped. Reopen it from **Settings → Setup checklist**.
+
+To compare countries, open the Overview chart and choose **Compare → Countries**. Choose a store or AI source, narrow to a keyword or question, and select the countries to show. Bing Copilot has global results and is available in the Sources view.
+
+### Compare competitors
+
+Choose **Add competitors** beneath any search in Overview, Store rankings, or AI visibility. The **Apps & competitors** panel shows each app’s position or AI mentions and citations from the same saved check. Select apps from your workspace, or use **Find a competitor** to verify a new app’s store listing.
+
+Adding an existing app to a search reuses saved results and shares future checks, so it does not use extra tracking searches. Discovering a new app, verifying its listings, and manual store-detail refreshes can use separate credits. Store comparisons require a verified listing on the matching platform.
+
+### Explore changes
+
+Open **Apps & competitors → Open query matrix** beneath a query to compare saved results across its countries. Each cell includes its check time and opens the underlying evidence. Different languages, devices, and search depths stay separate.
+
+On Overview, switch the history panel from **Trend** to **Distribution** to see counts and percentages for positions 1–3, 4–10, 11–50, 51+, and results where the app was not found. Click a group to inspect its queries. Changes compare the latest check for each app/query combination with the preceding equal-length period. Only combinations checked successfully in both periods contribute to the change counts; failed checks and featured-only placements are shown separately.
+
+The notification bell reports a drop of at least five positions from a previous top-10 rank, an exit from the top 10, or disappearance from a sufficiently deep checked result set. Two successful checks must confirm a loss. An intervening failed check resets confirmation, and continuing losses do not produce duplicate alerts until the ranking recovers. Notifications, matrices, and distributions use saved search data and consume no extra SerpApi credits.
+
+### Track listing history
+
+Open **Listing history → Track a listing**. Collection is off by default. Select an app, store, country, and frequency; Google Play also supports a language choice. The credit estimate appears before you enable tracking. Each scheduled check uses one SerpApi product request, with an initial baseline check when tracking starts. Manual checks and retries can consume additional credits.
+
+The timeline highlights changes to the fields returned by the store, including titles, descriptions, versions, pricing, and images. Text comparisons highlight additions and removals. Screenshots can be compared in order, with added and moved images labeled. Supported images are archived locally in the database and included in backups. If an image cannot be archived, the comparison shows an unavailable-image placeholder. AppTrail never substitutes the live image for a missing historical image.
+
+Use **Manage** to change frequency, pause or resume collection, or request a manual check. Pausing preserves history. Unchanged checks are hidden until you select **Show unchanged checks**. Collection requires the AppTrail process to remain running, and begins when you enable it; earlier listing versions cannot be reconstructed.
+
+### Account access
+
+AppTrail requires login for the dashboard and every workspace API, including searches, exports, and backups. First-time setup requires a code from the server terminal, and registration closes after the owner account is created. New server runs require a fresh login. Change your password in Settings, or recover access from the server terminal with `apptrail --reset-password`.
+
+See the [self-hosting guide](https://github.com/serpapi/apptrail/blob/main/docs/SELF_HOSTING.md#public-https-hosting) for optional HTTPS proxy configuration and [authentication details](https://github.com/serpapi/apptrail/blob/main/docs/AUTHENTICATION.md).
+
+## A few useful details
+
+AppTrail uses your own [SerpApi account](https://serpapi.com/) to fetch data. Discovery, product verification, and tracking requests can consume credits. Identical tracked searches are shared across apps. Settings shows an estimate of monthly usage and your account-wide remaining balance.
+
+### Development
+
+To contribute or customize AppTrail, start with the [development guide](https://github.com/serpapi/apptrail/blob/main/docs/DEVELOPMENT.md). It covers local setup with uv, the project layout, running tests, and building packages.
+
+### Self-hosting
+
+Keep AppTrail running on your own server with persistent storage for your workspace. The [self-hosting guide](https://github.com/serpapi/apptrail/blob/main/docs/SELF_HOSTING.md) walks through Docker, Docker Compose, CapRover, and Coolify, with instructions for HTTPS, backups, and updates.

apptrail-0.4.0/compose.yaml

@@ -0,0 +1,12 @@
+services:
+  apptrail:
+    build: .
+    ports:
+      - "80:80"
+    volumes:
+      - apptrail-data:/data
+    restart: unless-stopped
+    stop_grace_period: 6m
+
+volumes:
+  apptrail-data: