Skip to content

Upgrade to Sentry 9.22, add Web View + OTLP journeys, enable Web & macOS #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Prithvirajkumar merged 2 commits into from
Jun 19, 2026
Merged

Upgrade to Sentry 9.22, add Web View + OTLP journeys, enable Web & macOS #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30347b4
Upgrade to Sentry 9.22, add Web View + OTLP journeys, enable Web & macOS
Prithvirajkumar Jun 19, 2026
12e8764
Set default SE tag to 'tda' (repo default; SEs shouldn't commit their…
Prithvirajkumar Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion BUILD_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ This guide explains how to use the unified `demo.sh` script to build your Flutte
```bash
./demo.sh build [platform] [build-type]
./demo.sh run [platform]
./demo.sh distribute <android|aab|ios> [file]
./demo.sh upload-size [file] [platform]
./demo.sh verify
```

Expand Down Expand Up @@ -160,7 +162,7 @@ The script automatically uploads symbols for release builds if Sentry is configu
Add to your `.env` file:
```bash
SENTRY_DSN=https://your-key@o0.ingest.sentry.io/0000000
SENTRY_RELEASE=myapp@9.14.0+1
SENTRY_RELEASE=myapp@9.22.0+1
SENTRY_ENVIRONMENT=production
```

Expand Down Expand Up @@ -231,6 +233,46 @@ The script will automatically:

For detailed instructions and CI/CD integration, see the [Size Analysis Guide](SIZE_ANALYSIS_GUIDE.md).

## Build Distribution

Upload a built app to **Sentry Build Distribution** so testers can install it:

```bash
# Android APK
./demo.sh distribute android

# Android App Bundle
./demo.sh distribute aab

# iOS
./demo.sh distribute ios

# Or pass an explicit file
./demo.sh distribute android path/to/app-release.apk
```

The command uploads via `sentry-cli build upload` (resolving the default release artifact per platform), reusing the same uploader as size analysis. This is in addition to `./demo.sh upload-size`.

## Platform Notes

### Android Gradle Plugin
The project requires **AGP 8.9.1** (set in `android/settings.gradle.kts`), needed by the androidx libraries pulled in by `webview_flutter`/`url_launcher`. The Gradle wrapper is 8.12.

### Web & macOS Support
Web and macOS now build and run:

```bash
# Web
flutter build web
flutter run -d chrome

# macOS
flutter run -d macos
```

- The shared code path is web-safe (`dart:io` removed via conditional-import modules in `lib/platform/`; platform checks use `kIsWeb`/`defaultTargetPlatform`).
- Sandboxed macOS apps need the `com.apple.security.network.client` entitlement (enabled in `macos/Runner/DebugProfile.entitlements` and `Release.entitlements`) to reach the network.

## Troubleshooting

### Flutter Not Found
Expand Down
88 changes: 71 additions & 17 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Project Overview

**Application:** Empower Plant (`empower_flutter`)
**Version:** 9.14.0+1 (matches Sentry SDK version)
**Version:** 9.22.0+1 (matches Sentry SDK version)
**Purpose:** Production-ready Flutter e-commerce app with comprehensive Sentry instrumentation demonstrating best practices for error monitoring, performance tracking, session replay, and user feedback.

**Type:** Full-featured plant shopping app + Sentry demo platform
Expand All @@ -24,7 +24,7 @@
- Sentry config: DSN, ORG, PROJECT, AUTH_TOKEN required

### Version Management
- **Format:** `package@version+build` (e.g., `com.example.empower_flutter@9.14.0+1`)
- **Format:** `package@version+build` (e.g., `com.example.empower_flutter@9.22.0+1`)
- Version source: `pubspec.yaml`
- Must match Sentry SDK version for consistency
- Distribution set to build number (currently `'1'`)
Expand All @@ -42,8 +42,21 @@ lib/
├── navbar_destination.dart # Navigation drawer + error triggers
├── product_list.dart # Home screen, catalog, demo triggers (750+ lines)
├── product_details.dart # Product detail view
├── cart.dart # Shopping cart
├── cart.dart # Shopping cart (shows real prices)
├── checkout.dart # Checkout flow with metrics/logging
├── backend_config.dart # Backend base URL selection (standard vs OTLP)
├── platform/ # Web-safe platform abstraction
│ ├── platform_info.dart # kIsWeb/defaultTargetPlatform helpers
│ ├── native_info_io.dart # dart:io-backed native info (mobile/desktop)
│ ├── native_info_web.dart # Web stub for native info
│ ├── file_io_demo.dart # Conditional-import entry for file I/O demo
│ ├── file_io_demo_io.dart # dart:io file I/O demo implementation
│ └── file_io_demo_web.dart # Web-safe file I/O demo stub
├── webview/ # Web View journey (distributed tracing)
│ ├── web_view_screen.dart # Web View drawer screen + transaction
│ ├── web_view_io.dart # In-app WebView (Android/iOS) / browser (desktop)
│ ├── web_view_web.dart # dart:ui_web iframe (Flutter web)
│ └── trace_headers.dart # Builds sentry-trace/baggage query params
└── models/
└── cart_state_model.dart # Provider-based cart state

Expand Down Expand Up @@ -75,22 +88,29 @@ Flutter SDK: >= 3.22.0 < 4.0.0
Dart SDK: >= 3.5.0 < 4.0.0

# Sentry
sentry_flutter: ^9.14.0 # Main SDK
sentry_dio: ^9.14.0 # HTTP client integration
sentry_file: ^9.14.0 # File I/O tracking
sentry_logging: ^9.14.0 # Logging integration
sentry_flutter: ^9.22.0 # Main SDK
sentry_dio: ^9.22.0 # HTTP client integration
sentry_file: ^9.22.0 # File I/O tracking
sentry_logging: ^9.22.0 # Logging integration

# State Management & Utils
provider: ^6.1.5 # State management
flutter_dotenv: ^6.0.0 # Environment variables
dio: ^5.9.1 # HTTP client
logging: ^1.3.0 # Structured logging

# Web View feature
webview_flutter: ^4.13.0 # In-app WebView (Android/iOS)
url_launcher: ^6.3.1 # Desktop fallback (system browser)
web: ^1.1.1 # Flutter web iframe support
```

### External Services
- **Backend API:** `https://flask.empower-plant.com/` (products, checkout)
- **Backend API (default):** `https://flask.empower-plant.com/` (products, checkout)
- **Backend API (OTLP):** `https://flask-otlp.empower-plant.com/` (OpenTelemetry-instrumented; used by the OTLP journey)
- **Web app (React):** `https://empower-plant.com/products` (loaded by the Web View journey)
- **Sentry:** Error monitoring, performance, session replay
- **Sentry CLI:** Optional for symbol upload and size analysis
- **Sentry CLI:** Optional for symbol upload, size analysis, and build distribution

---

Expand Down Expand Up @@ -143,6 +163,14 @@ enableAutoNativeBreadcrumbs: true # Native breadcrumbs

// Privacy (Demo settings)
sendDefaultPii: true # Send PII for demo environment

// Distributed Tracing
tracePropagationTargets: [ # Backends that receive trace headers
'empower-plant.com',
'flask.empower-plant.com',
'flask-otlp.empower-plant.com',
'localhost',
]
```

### Custom Hooks & Privacy
Expand All @@ -152,9 +180,8 @@ sendDefaultPii: true # Send PII for demo environment
- Sets fingerprint: `['{{ default }}', 'se:$se']`

**Session Replay Privacy Masking:**
- Masks Text widgets containing BOTH a financial label AND dollar sign
- Financial labels: `items (`, `shipping & handling`, `total before tax`, `estimated tax`, `order total`, `subtotal`
- Ensures labels remain visible, only values with $ are masked
- Real prices are shown in full in the app UI (e.g. cart item lines and subtotal show `$155.00`); they are masked only in Session Replay
- The `maskCallback` masks Text widgets containing a `$…` value so financial values stay private in replays
- Everything else in replays is visible

### Integrations Enabled
Expand Down Expand Up @@ -283,13 +310,21 @@ await client.get(Uri.parse('https://example.com'));
# Run on device and create Sentry deploy
./demo.sh run [platform]

# Upload a build for size analysis
./demo.sh upload-size [file] [platform]

# Upload a build to Sentry Build Distribution
./demo.sh distribute <android|aab|ios> [file]

# Verify setup (Flutter, Sentry CLI, .env)
./demo.sh verify

# Show help
./demo.sh help
```

**Note:** `distribute` uploads a built app to Sentry Build Distribution via `sentry-cli build upload` (resolving the default release artifact per platform, reusing the same uploader as size analysis).

### Supported Platforms

| Platform | Command | Output Location |
Expand Down Expand Up @@ -324,7 +359,7 @@ await client.get(Uri.parse('https://example.com'));
```bash
SENTRY_AUTH_TOKEN=sntryu_xxx # Sentry auth token
SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
SENTRY_RELEASE=com.example.empower_flutter@9.14.0+1
SENTRY_RELEASE=com.example.empower_flutter@9.22.0+1
SENTRY_ENVIRONMENT=development # development/staging/production
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug
Expand Down Expand Up @@ -377,6 +412,20 @@ SENTRY_SIZE_ANALYSIS_ENABLED=true # Optional: enable size tracking
- Order value gauge metrics
- User feedback collection on errors

### Web View Journey (Distributed Tracing)

- Drawer item **Web View** opens `https://empower-plant.com/products` inside an in-app WebView (Android/iOS), a `dart:ui_web` iframe (Flutter web), or the system browser (desktop)
- Starts its own transaction `webview/empower-plant` (op `navigation`) on a fresh trace
- Implements **Flutter → web distributed tracing**: attaches the active `sentry-trace`/`baggage` to the loaded URL as query params so the web page's Sentry browser SDK continues the same trace (Flutter → React → backend = one trace)
- Transaction finishes when the page loads
- Code: `lib/webview/` (`web_view_screen.dart`, `web_view_io.dart`, `web_view_web.dart`, `trace_headers.dart`)

### OTLP Backend Journey

- Drawer item **OTLP** opens the home/product experience but routes all backend calls (`/products`, `/checkout`) to the OpenTelemetry-instrumented backend `https://flask-otlp.empower-plant.com` instead of the default `https://flask.empower-plant.com`
- Runs as its own new trace and continues into the OTLP backend via propagated trace headers
- Backend selection is centralized in `lib/backend_config.dart` (`BackendConfig.base`, `.products`, `.checkout`; standard vs OTLP base)

---

## Development Workflow
Expand Down Expand Up @@ -524,23 +573,28 @@ SENTRY_SIZE_ANALYSIS_ENABLED=true
## Quick Reference

### Key URLs
- **Backend API:** `https://flask.empower-plant.com/`
- **Backend API (default):** `https://flask.empower-plant.com/`
- **Backend API (OTLP):** `https://flask-otlp.empower-plant.com/`
- **Web app (React):** `https://empower-plant.com/products`
- **Spotlight (Debug):** `http://localhost:8969/`
- **GitHub (Sentry SDK):** `https://github.com/getsentry/sentry-dart`

### Important Version Numbers
- **App Version:** 9.14.0+1
- **App Version:** 9.22.0+1
- **Flutter SDK:** >= 3.22.0
- **Sentry SDK:** ^9.14.0
- **Sentry SDK:** ^9.22.0

### File Locations
- **Config:** `.env`, `lib/se_config.dart`, `pubspec.yaml`
- **Sentry Setup:** `lib/sentry_setup.dart`
- **Backend Selection:** `lib/backend_config.dart`
- **Platform Abstraction:** `lib/platform/`
- **Web View Journey:** `lib/webview/`
- **Build Output:** `build/` directory
- **Debug Symbols:** `build/debug-info/`, `build/app/obfuscation.map.json`

---

*Last Updated: Session creating this CLAUDE.md*
*Current Branch: feature/comprehensive-sentry-integration*
*App Version: 9.14.0+1*
*App Version: 9.22.0+1*
63 changes: 48 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A Flutter e-commerce application showcasing comprehensive Sentry instrumentation for error monitoring, performance tracking, session replay, and user feedback.

**For Solution Engineers:** This guide focuses on **Android** setup, which has been fully tested. iOS and other platforms have not been validated yet.
**For Solution Engineers:** This guide focuses on **Android** setup, which has been fully tested. **Web** and **macOS** now build and run as well (see "Other Platforms" below). iOS, Linux, and Windows have not been fully validated yet.

---

Expand Down Expand Up @@ -33,7 +33,7 @@ A Flutter e-commerce application showcasing comprehensive Sentry instrumentation
```bash
SENTRY_AUTH_TOKEN=sntryu_your_token_here
SENTRY_DSN=https://your_key@o123456.ingest.us.sentry.io/123456
SENTRY_RELEASE=com.example.empower_flutter@9.14.0+1
SENTRY_RELEASE=com.example.empower_flutter@9.22.0+1
SENTRY_ENVIRONMENT=development
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug
Expand Down Expand Up @@ -131,7 +131,7 @@ Navigate through the app (Home → Product Details → Cart → Checkout) and ch
- Trigger any error from the drawer menu
- Go to Sentry Issues → Click on the error
- View the attached session replay showing user actions leading up to the error
- Financial information (prices in checkout) is automatically masked for privacy
- Financial information (prices in cart/checkout) is shown in full in the app UI but automatically masked in Session Replay for privacy (the `maskCallback` in `lib/sentry_setup.dart` masks any `$…` Text)

### 4. Metrics & Logging

Expand All @@ -150,6 +150,21 @@ Trigger from drawer menu: **ANR (Android)**
- Creates ANR event in Sentry with thread states
- Shows which operations were blocking

### 6. Web View (Distributed Tracing) — Cross-Platform

Trigger from drawer menu: **Web View**
- Opens the Empower Plant React web app (`https://empower-plant.com/products`) inside an in-app WebView (Android/iOS), a `dart:ui_web` iframe (Flutter web), or the system browser (desktop)
- Starts its own Sentry transaction (`webview/empower-plant`, op `navigation`) on a fresh trace
- Performs **Flutter → web distributed tracing**: the active `sentry-trace`/`baggage` are attached to the loaded URL as query params so the web page's Sentry browser SDK continues the same trace (Flutter → React → backend = one trace)
- The transaction finishes when the page loads

### 7. OTLP Backend Journey — Cross-Platform

Trigger from drawer menu: **OTLP**
- Opens the home/product experience but routes all backend calls (`/products`, `/checkout`) to the OpenTelemetry-instrumented backend `https://flask-otlp.empower-plant.com` instead of the default `https://flask.empower-plant.com`
- Runs as its own new trace and continues into the OTLP backend via propagated trace headers
- Backend selection is centralized in `lib/backend_config.dart`

---

## Demo Features Reference
Expand Down Expand Up @@ -208,6 +223,16 @@ Both APK and AAB are uploaded with detailed DEX breakdown (thanks to ProGuard ma

For more details, see [SIZE_ANALYSIS_GUIDE.md](SIZE_ANALYSIS_GUIDE.md).

## Build Distribution (Optional)

Upload a built app to Sentry Build Distribution so testers can install it:

```bash
./demo.sh distribute <android|aab|ios> [file]
```

This uploads the build via `sentry-cli build upload` (resolving the default release artifact per platform), reusing the same uploader as size analysis.

---

## Troubleshooting
Expand Down Expand Up @@ -271,8 +296,11 @@ lib/
├── navbar_destination.dart # Navigation drawer + error triggers
├── product_list.dart # Product catalog, performance demos
├── product_details.dart # Product detail view
├── cart.dart # Shopping cart
├── cart.dart # Shopping cart (shows real prices)
├── checkout.dart # Checkout with metrics/logging
├── backend_config.dart # Backend base URL selection (standard vs OTLP)
├── platform/ # Web-safe platform abstraction (conditional imports)
├── webview/ # Web View journey + Flutter→web trace handoff
└── models/
└── cart_state_model.dart # Shopping cart state (Provider)

Expand Down Expand Up @@ -325,27 +353,32 @@ All features are configured at 100% sampling for demo purposes. Adjust in `lib/s

---

## iOS & Other Platforms (Untested)
## Other Platforms

In addition to Android, **Web and macOS now build and run**:

```bash
# Web (build + run)
flutter build web
flutter run -d chrome

# macOS
flutter run -d macos
```

This demo has **only been validated on Android**. iOS, Web, macOS, Linux, and Windows builds may work but have not been tested by the team.
The shared code path is web-safe (`dart:io` removed via conditional-import modules in `lib/platform/`, platform checks use `kIsWeb`/`defaultTargetPlatform`). macOS apps are sandboxed, so the `com.apple.security.network.client` entitlement is enabled in `macos/Runner/DebugProfile.entitlements` and `Release.entitlements` so the app can reach the network.

If you want to try other platforms:
iOS, Linux, and Windows builds may work but have not been fully validated by the team:

```bash
# iOS (requires macOS + Xcode)
./demo.sh build ios

# Web
./demo.sh build web

# Others
./demo.sh build macos
./demo.sh build linux
./demo.sh build windows
```

Platform-specific documentation exists in the codebase but **is not guaranteed to be accurate**.

---

## Support & Resources
Expand All @@ -358,6 +391,6 @@ For issues with this demo, check existing documentation or reach out to the SE t

---

**Current Version:** 9.14.0+1 (matches Sentry SDK)
**Tested Platform:** Android only
**Current Version:** 9.22.0+1 (matches Sentry SDK)
**Tested Platforms:** Android (primary), Web, macOS
**App Name:** Empower Plant (com.example.empower_flutter)
Loading
Loading