For developers

1. 1

   Add the package and its skills

   Run this in your app’s folder. The skills CLI copies the skills of the lotse package into your project, where your agent finds them. Run skills get again after every update of lotse.

   flutter pub add lotse
   dart pub global activate skills
   skills get --package lotse --all
   

2. 2

   Ask your agent

   Create a project and an API key in the console first. The agent asks you for the public key and your handle and tells you what to enter in the console. It never needs a secret.

   Add Lotse to this app with the lotse-setup skill. Then set up deep links with lotse-deep-links and push with lotse-push.
   

3. 3

   Connect the MCP server

   With a token from the project settings, your agent reads funnels, feedback and links, checks your setup and, if the token allows it, creates links and segments. This is the line for Claude Code. Cursor, VS Code and Codex are on the AI agents page.

   claude mcp add --transport http --scope local lotse https://api.lotse.dev/mcp --header 'Authorization: Bearer ${LOTSE_MCP_TOKEN}'
   

Tokens, tools and limits

1. 1

   Create a project

   Sign up in the console, create a project and choose its handle. The handle becomes your link domain, your-handle.lotse.dev. Add your Android app with its package name and the SHA-256 fingerprint of your signing key, and your iOS app with its bundle ID and Team ID. Then create an API key; its public key goes into the app.

2. 2

   Add the package

   The SDK is the package lotse on pub.dev.

   flutter pub add lotse
   

3. 3

   Initialise

   One call registers the device, reports the session and resolves a deferred link. It never throws into your app: failures are logged and the link is null.

   Future<void> main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await Lotse.init(
       publicKey: 'lt_pk_…',
       serverUrl: 'https://api.lotse.dev/',
     );
   
     // Set on the first start after an install that came from a link.
     final link = await Lotse.instance.deferredLink;
     runApp(MyApp(initialLocation: link?.targetPath ?? '/'));
   }
   

4. 4

   Let links open the app

   Declare your link domain in the Android manifest, and on iOS add the Associated Domains capability with applinks:your-handle.lotse.dev. Lotse serves assetlinks.json and apple-app-site-association for your project. Route /l/:slug in your router to Lotse.instance.resolveLink(slug) and go to its targetPath.

   <!-- android/app/src/main/AndroidManifest.xml, inside <activity> -->
   <intent-filter android:autoVerify="true">
     <action android:name="android.intent.action.VIEW"/>
     <category android:name="android.intent.category.DEFAULT"/>
     <category android:name="android.intent.category.BROWSABLE"/>
     <data android:scheme="https"
           android:host="your-handle.lotse.dev"
           android:pathPrefix="/l/"/>
   </intent-filter>
   

5. 5

   Turn on push

   Add Firebase to your app as usual and upload the service account in the console. For iPhones, also upload an APNs key (.p8) for the iOS app; without one, pushes to iOS go through FCM. The SDK asks for permission, reports the token and tells you when a push was opened.

   // A push tapped while the app was closed, and pushes tapped while it runs.
   final push = await Lotse.instance.initialPush;
   Lotse.instance.pushOpened.listen((push) => router.go(push.targetPath ?? '/'));
   

static Future<void> Lotse.init({required String publicKey, required String serverUrl})

Connects, registers the device, reports session_start. Calling it again does nothing.

Future<LotseLink?> get deferredLink

The link an install came from. Completes once, with null if there was none.

Future<LotseLink?> resolveLink(String slug)

Turns the slug of an opened link into its target route and campaign.

Future<void> track(String name, {Map<String, String>? props})

Writes an event with string properties to the stream.

Future<void> identify(String userId, {Map<String, String>? traits, String? userHash})

Ties the device to a signed-in user, with traits. userHash comes from your backend once the project verifies identities.

Future<void> reset()

For logout: the next events no longer belong to the user.

LotseScreenObserver({String? Function(Route<dynamic> route)? screenName})

Hand it to your router and every screen change becomes a screen_view event. screenName picks the name, the route name by default.

Future<LotsePush?> get initialPush

The push that started the app, if any.

Stream<LotsePush> get pushOpened

Pushes tapped while the app is running.

Future<void> showFeedback(BuildContext context, {Map<String, String>? metadata, bool askForEmail = false, LotseFeedbackTexts? texts})

Opens the feedback sheet: screenshot, marks, text and category. metadata is stored with the message, askForEmail adds an optional e-mail field.

Full API reference on pub.devSource code on GitHub

1. The SHA-256 fingerprint in the console must belong to the key that signed the installed build. Debug and release differ.
2. adb shell pm get-app-links your.package shows whether Android verified the domain.
3. Tap the link in another app. Typing it into the address bar of a browser never opens an app.
4. The host in the manifest must be your project’s link domain, not lotse.dev.
5. Deferred matching needs the click and the first start in the same network. A VPN or a switch from wifi to mobile data breaks it.