# Add Deep Links to a Flutter App

Yes. An agent wires Android App Links and iOS Universal Links into your go_router routes, adds the site association files, tests the redirect, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-deep-links/flutter/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the router before it touches a platform file, because a link is only useful if the route it names survives startup. In an app like gskinnerTeam/flutter-wonderous-app, `lib/router.dart` defines `ScreenPaths` with `/`, `/welcome`, `/home` and `/settings`, builds wonder links as `/home/wonder/<type>?t=<tab>`, and appends `video`, `search`, `maps`, `timeline`, `artifact` and `collection` segments to the current path. The `GoRouter` has a `redirect` that, while `appLogic.isBootstrapComplete` is false, stores the requested URI in `_initialDeeplink` and sends every request to the splash route; `lib/logic/app_logic.dart` waits one millisecond "to give GoRouter time to catch the initial deeplink" and then calls `appRouter.go(initialDeeplink ?? ScreenPaths.home)`, unless `hasCompletedOnboarding` is false, in which case it goes to the intro and the stored link is dropped. `_parseWonderType` falls back to `WonderType.chichenItza` for any unknown segment, so a mistyped link opens the wrong wonder rather than a not-found page.

The platform side is half done. `ios/Runner/Info.plist` already sets `FlutterDeepLinkingEnabled` to true, but `ios/Runner/Runner.entitlements` carries only `aps-environment` and the `group.com.gskinner.flutter.wonders.widget` app group, with no associated domains. `android/app/src/main/AndroidManifest.xml` has the `MAIN` and `LAUNCHER` intent filter and a `PROCESS_TEXT` query and nothing that handles `VIEW`; `android/app/build.gradle.kts` sets `applicationId` to `com.gskinner.flutter.wonders`. `pubspec.yaml` pins `go_router ^17.0.1` on Flutter `^3.41.9` and lists no link package, and the `web/` directory holds the site the `build_and_deploy_web_*` workflows publish. There is no `test/` directory.

The agent adds an `intent-filter` with `android:autoVerify="true"`, the `VIEW` action, `DEFAULT` and `BROWSABLE` categories, the `https` scheme, the site's host and a `pathPrefix` of `/home/wonder`, plus a second filter for a `wonders://` custom scheme, to `AndroidManifest.xml`. On iOS it adds `com.apple.developer.associated-domains` with `applinks:<host>` to `Runner.entitlements` and a `CFBundleURLTypes` entry for the custom scheme to `Info.plist`. Under `web/.well-known/` it writes `assetlinks.json` with the package name and a placeholder for the release signing certificate's SHA-256 fingerprint, and `apple-app-site-association` with the team id placeholder, the bundle id and the `/home/wonder/*` path, so the deployed site answers the verification requests. In `router.dart` it makes an unknown `detailsType` reach `errorPageBuilder` instead of the Chichén Itzá fallback, and in `app_logic.dart` it carries `initialDeeplink` through the intro so a first-time user who taps a link still lands on the wonder after onboarding.

Tests are new to this repository, so the agent creates `test/router_test.dart` with `flutter_test`: it navigates the real `appRouter` to `/home/wonder/petra?t=1` and asserts the matched route and parameters, checks that an unknown type produces the not-found page, and checks the redirect stores the link while bootstrap is incomplete. It runs `flutter analyze` under the `analysis_options.yaml` rules (`always_declare_return_types`, `always_use_package_imports`, `prefer_single_quotes`), `flutter test`, `flutter build apk --debug` so the manifest merge is checked, and `flutter build web` so the `.well-known` files appear in `build/web`, on the Flutter 3.41.9 that `build_web.yml` pins.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "codex",
  "input": "Add deep links to this Flutter app and open a pull request. Read pubspec.yaml, lib/main.dart, lib/router.dart, lib/logic/app_logic.dart, lib/logic/settings_logic.dart, android/app/src/main/AndroidManifest.xml, android/app/build.gradle.kts, ios/Runner/Info.plist, ios/Runner/Runner.entitlements, web/index.html and .github/workflows/build_web.yml first. Add an autoVerify https intent filter for the wonder details path and a custom scheme filter on Android, associated domains and a URL type on iOS, and assetlinks.json and apple-app-site-association files under web/.well-known with placeholders for the signing fingerprint and team id. Make an unknown wonder type in a link show the not-found page instead of the default wonder, and keep the initial deep link through onboarding. Add router tests under test/ for a wonder link, an unknown type and the bootstrap redirect. Run flutter analyze, flutter test, flutter build apk --debug and flutter build web, and put the output and the placeholders a person must fill in the pull request description.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch. The diff edits `AndroidManifest.xml`, `Info.plist` and `Runner.entitlements`, adds `web/.well-known/assetlinks.json` and `web/.well-known/apple-app-site-association`, changes the type parsing and the onboarding branch in `lib/router.dart` and `lib/logic/app_logic.dart`, and adds `test/router_test.dart`. The description lists the two placeholders, the signing fingerprint and the Apple team id, that only the account owner can fill.

The run's record keeps the `flutter analyze` and `flutter test` output, the debug APK build with its manifest merge, and the web build showing the `.well-known` files in `build/web`, so a reviewer can see the configuration compile on both platforms before a device is involved.

Before merging, a reviewer checks that the host in the intent filter and the entitlement is the one the web workflows deploy to, that the association files are served without a redirect and with a JSON content type, and that the custom scheme is not one another installed app claims.

## Run it on every new shareable screen

A repository webhook on your server can send this request whenever a pull request that adds a route to `lib/router.dart` is merged, with the prompt naming the new path. Each run extends the intent filter's path list, the site association's `paths` and the router test for that one screen, so links stay in step with the routes rather than being added in a batch later.

The key's `webhook_url` posts `run.completed` when the turn ends, with `data.session_url` for the pull request link; a `request_id` in each body makes a retry safe.

## Why run it on Rush?

Deep links fail quietly: a link opens the browser instead of the app because a fingerprint is wrong, or opens the app and lands on the home screen because the router dropped the path during startup. In a Rush sandbox the agent installs the pinned Flutter SDK, runs the analyzer and the new router tests, and builds the Android and web targets, so the pull request shows the configuration is consistent before anyone taps a link on a phone.

The work crosses two platform manifests, an entitlements file, two JSON files on the website, the router and the bootstrap logic. One run returns all of it with its log, and the same prompt runs against several Flutter apps at once, each in its own sandbox reading its own `router.dart`.

## Frequently asked questions

### Does this need the app_links or uni_links package?

No. go_router reads the launching link through Flutter's built-in deep link support, which `FlutterDeepLinkingEnabled` already turns on for iOS and the Android embedding handles when the intent filter exists. The router's existing `_initialDeeplink` capture is kept and fixed rather than replaced.

### Why are there placeholders in the association files?

`assetlinks.json` must carry the SHA-256 fingerprint of the certificate that signs the release build, and `apple-app-site-association` must carry the Apple team id. Neither is in the repository, and the agent must not invent them, so the pull request names both and where to find them.

### What happens to a link with a wonder that does not exist?

Today `_parseWonderType` falls back to Chichén Itzá. After the change an unknown segment reaches the router's `errorPageBuilder` and shows `PageNotFound` with the requested path, and the new test asserts that.

### Will a first-time user lose the link during onboarding?

Not after the change. `bootstrap()` used to go to the intro and discard `initialDeeplink`; now the intro completes into the stored link, falling back to `/home` when there is none. The test covers the redirect while bootstrap is incomplete.

## More Flutter jobs

- [Set Up Dependabot for a Flutter App's Pub, Gradle and Actions Dependencies](https://getrush.ai/run/add-dependabot/flutter/)
- [Add Fastlane to a Flutter App](https://getrush.ai/run/add-fastlane/flutter/)
- [Add GitHub Actions CI to a Flutter App](https://getrush.ai/run/add-github-actions-ci/flutter/)

## The same job on other stacks

- [Add Deep Links to a React Native App](https://getrush.ai/run/add-deep-links/react-native/)
- [Add Deep Link Handling to a Tauri App](https://getrush.ai/run/add-deep-links/tauri/)
- [Add Deep Link Handling to an Electron App from a Linear Issue](https://getrush.ai/run/add-deep-links/electron/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
