# Flutter

> One widget around your app — iOS, Android, macOS, Windows, Linux and the web.

Source: https://docs.usejot.co/docs/install/flutter

## Install

```bash
flutter pub add usejot
```

Jot needs Flutter 3.41 or newer.

Wrap your app once:

```dart title="lib/main.dart"
import 'package:usejot/usejot.dart';

void main() => runApp(
  Jot(projectKey: 'jot_pk_your_key', child: const MyApp()),
);
```

Then give your app's navigator the observer, so every pin knows which screen it was left on:

```dart
MaterialApp(
  navigatorObservers: [Jot.navigatorObserver],
  // …
)
```

That is the whole install. A small Jot button appears on the edge of the screen. Reviewers tap
it, tap the thing that is wrong, and type one sentence.

## Platforms

| Platform            | Recording                                         | Crashes                                   |
| ------------------- | ------------------------------------------------- | ----------------------------------------- |
| iOS, Android, macOS | video, encoded natively                           | native and Dart                           |
| Windows, Linux      | video when the machine can encode it, else frames | native and Dart, or Dart only with frames |
| Web                 | frames                                            | Dart                                      |

On iOS, Android and macOS, recording runs in Jot's native core: frames are masked and encoded
to video on a background thread. Windows and Linux use the same native core when the machine
has a video encoder (on Linux, GStreamer with an H.264 encoder). Without one, and on Flutter
web, Jot falls back to a lighter recording made of individual frames, at a lower frame rate.
Everything else — pins, screenshots, annotations, threads and live updates — works the same
everywhere.

Jot needs iOS 13, macOS 11 and Android 7 (API 24) or newer.

## Screens

`Jot.navigatorObserver` follows your app's page routes. The route on top is the screen: its
name if it has one (`/checkout`), otherwise the page widget's type. Every Jot, pin and recording
is filed under that screen.

Name your routes and the dashboard reads like your app:

```dart
MaterialPageRoute(
  settings: const RouteSettings(name: '/details'),
  builder: (_) => const ProductDetails(),
)
```

## Options

```dart
Jot(
  projectKey: 'jot_pk_your_key',
  environment: 'staging',
  authScheme: 'shop.acme',
  position: JotPosition.bottomLeft,
  child: const MyApp(),
)
```

| Option        | What it does                                                                                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectKey`  | Your project's public key. Required.                                                                                                                             |
| `environment` | Tags every Jot (`staging`, `preview`…) so you can filter by it.                                                                                                  |
| `authScheme`  | Optional, and most apps never set it. Only for **Continue with Google**, and only to replace the default scheme `jot.` plus your app id. See [Sign-in](#sign-in) |
| `trigger`     | `JotTrigger.fab` (the Jot button, default) or `JotTrigger.tab`, a slim edge tab                                                                                  |
| `position`    | Where it sits. Button: a top or bottom corner, or centre (default `bottomRight`). Tab: `left` or `right` (default), or laid along the top or bottom              |
| `label`       | The tab's text and the trigger's accessible name, up to 24 characters. Default "Feedback"                                                                        |
| `icon`        | `JotTriggerIcon.jot` (default), `chat`, `bug` or `none` (the tab's default)                                                                                      |
| `offset`      | A side tab's position down the edge, 0–100 (percent). Default 50                                                                                                 |
| `edge`        | Deprecated: use `position`                                                                                                                                       |

Open Jot from your own UI with `Jot.of(context).open()`, or `Jot.open()` from anywhere.
`Jot.of(context)` also has `close()` and `isOpen`.

## Pins land on the same widget

A pin remembers the widget under the reviewer's finger — its text, its semantics label, its
type and its place in the widget tree — and the spot inside it. Later, on another phone, a
tablet, a resized window or in landscape, Jot finds the same widget and puts the pin back at
the same spot. You don't have to set anything up. If the widget is gone, the pin hides; if
nothing matches well enough, the pin shows where it was dropped, marked approximate.

For the few widgets that matter most, give them a name and the match is exact, on every device:

```dart
JotAnchor(
  id: 'checkout.pay',
  child: ElevatedButton(onPressed: pay, child: const Text('Pay now')),
)
```

`JotAnchor` sets the id as the child's semantics identifier, so accessibility tools see it too.
Layout does not change.

## Privacy

Masking happens on the device, before an image or a recording exists. Nothing unmasked ever
leaves it.

* Password fields (`obscureText: true`) are always blacked out.
* Wrap anything else in `JotMask`:

```dart
JotMask(child: CardNumberField())
```

* To mask without shipping a build, add ids under **Project → Settings → Masked element ids
  (native apps)**. Any `JotAnchor` with that id, and any widget with that
  `ValueKey<String>`, is blacked out from the next session on.

Recorded network calls never include credentials: auth headers, cookies, tokens and anything
that looks like a password are replaced on the device before they are stored. Whatever was
typed into a masked field is blanked out of recorded requests too. Request and response bodies
are kept only when **Capture request and response bodies** is on in **Project → Settings →
Recording privacy**.

## Recording and crashes

Reviewers can press **Record**, reproduce the problem, then press **Stop & describe**. Jot keeps
the last two minutes. The recording carries the screen, console output, network calls, screen
changes, app lifecycle, taps (positions only — never keystrokes) and crashes. Nothing is
uploaded unless the reviewer sends the Jot. On iOS the upload carries on in the background if
the reviewer leaves the app; Jot hooks into your app delegate itself, so there is no code to add.

What is captured on its own:

* **Network calls made with `dart:io`** — `package:http`, Dio and plain `HttpClient`. Jot chains
  to any `HttpOverrides` your app installed first.
* **`debugPrint` output**, screen changes and errors.

What needs one line from you:

* **Network calls on the web.** `dart:io` doesn't exist there; wrap your client:

  ```dart
  final client = JotHttpClient(http.Client());
  ```

  `JotHttpClient` works on every platform, so you can use it everywhere.

* **`print` output.** Start your app inside `Jot.runZoned`:

  ```dart
  void main() => Jot.runZoned(
    () => runApp(Jot(projectKey: 'jot_pk_your_key', child: const MyApp())),
  );
  ```

If the app crashes — with or without a recording running — Jot saves the error before the app
closes. On the next launch it asks the reviewer whether to send it to the team. If they agree,
the crash becomes a **Bug** Jot on the screen it happened on, with the stack trace and whatever
was recorded.

## Sign-in

Invited reviewers sign in with a 6-digit code sent to their email. That works everywhere with
no setup.

To offer **Continue with Google** too:

* **iOS, Android and macOS** — add your scheme under **Project → Settings → App redirect
  schemes**. By default it is `jot.` plus your bundle id (iOS, macOS) or package name (Android),
  lowercased, with any `_` turned into `-`: `com.acme.my_shop` gives `jot.com.acme.my-shop`. If
  your bundle id and package name differ, add both. Nothing else to set up.

* **A scheme of your own** (optional; skip this unless you need a different scheme) — pass
  `authScheme` to `Jot`, and on Android set the same value in
  `android/app/build.gradle.kts`, since Android declares the scheme at build time:

  ```kotlin
  android {
      defaultConfig {
          manifestPlaceholders["jotAuthScheme"] = "shop.acme"
      }
  }
  ```

* **macOS, Windows and Linux** — turn on **Allow desktop sign-in (loopback)** in the same
  section. Sign-in then opens in the system browser and returns to the app on its own. On
  Windows and Linux this is how Google sign-in works, so the setting is required there. On
  macOS, without it, Jot uses the app redirect scheme instead.

* **macOS release builds** — a sandboxed app needs the incoming network entitlement for desktop
  sign-in, and the outgoing one to reach Jot at all. Flutter's template leaves both out of
  release builds; add them to `macos/Runner/Release.entitlements`, and the outgoing one to
  `DebugProfile.entitlements` if it is missing there:

  ```xml title="macos/Runner/Release.entitlements"
  <key>com.apple.security.network.client</key>
  <true/>
  <key>com.apple.security.network.server</key>
  <true/>
  ```

* **Web** — nothing more; sign-in opens in a popup.

## Allow your app

Under **Project → Settings → Allowed apps**, add your iOS and macOS bundle id and your Android
package name, for example `com.acme.shop`. A project with no allowed apps accepts every app.
Flutter web runs in a browser, so it follows **Allowed domains** instead.

Like an allowed domain, an app id can be spoofed. It is a convenience gate, not a password —
the reviewer's sign-in is what protects your feedback.

The app settings appear on Flutter and React Native projects.

## Phones and desktops

On screens narrower than 640 points, Jot opens as a bottom sheet. On tablets and desktops,
cards open beside the pin. <kbd>Esc</kbd> closes whatever is open.
