Für Entwickler

1. 1

   Paket und Skills einbinden

   Im Ordner deiner App ausführen. Die skills-CLI kopiert die Skills des Pakets lotse in dein Projekt, wo dein Agent sie findet. Nach jedem Update von lotse skills get erneut ausführen.

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

2. 2

   Den Agenten beauftragen

   Vorher in der Console ein Projekt und einen API-Key anlegen. Der Agent fragt nach dem Public Key und deinem Handle und sagt dir, was du in der Console eintragen musst. Ein Secret braucht er nie.

   Binde Lotse mit dem Skill lotse-setup in diese App ein. Richte danach Deep Links mit lotse-deep-links und Push mit lotse-push ein.
   

3. 3

   MCP-Server verbinden

   Mit einem Token aus den Projekteinstellungen liest dein Agent Funnels, Feedback und Links, prüft die Einrichtung und legt, wenn das Token es erlaubt, Links und Segmente an. Hier die Zeile für Claude Code. Cursor, VS Code und Codex stehen auf der Seite KI-Agenten.

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

Tokens, Tools und Grenzen

1. 1

   Projekt anlegen

   In der Console registrieren, ein Projekt anlegen und sein Handle wählen. Aus dem Handle wird die Link-Domain dein-handle.lotse.dev. Die Android-App mit Paketnamen und dem SHA-256-Fingerprint des Signaturschlüssels hinzufügen, die iOS-App mit Bundle ID und Team ID. Dann einen API-Key erzeugen; sein Public Key kommt in die App.

2. 2

   Paket einbinden

   Das SDK ist das Paket lotse auf pub.dev.

   flutter pub add lotse
   

3. 3

   Initialisieren

   Ein Aufruf registriert das Gerät, meldet die Session und löst einen Deferred Link auf. Er wirft nie in die App: Fehler werden geloggt, und der Link ist 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

   Links die App öffnen lassen

   Die Link-Domain im Android-Manifest eintragen, unter iOS die Capability Associated Domains mit applinks:dein-handle.lotse.dev. Lotse liefert assetlinks.json und apple-app-site-association für das Projekt aus. Im Router /l/:slug an Lotse.instance.resolveLink(slug) geben und zu dessen targetPath navigieren.

   <!-- 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

   Push einschalten

   Firebase wie gewohnt in die App einbinden und den Service-Account in der Console hochladen. Für iPhones zusätzlich einen APNs-Schlüssel (.p8) zur iOS-App hochladen; ohne ihn gehen Pushes an iOS über FCM. Das SDK fragt nach der Berechtigung, meldet das Token und sagt Bescheid, wenn ein Push geöffnet wurde.

   // 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})

Verbindet, registriert das Gerät, meldet session_start. Ein zweiter Aufruf tut nichts.

Future<LotseLink?> get deferredLink

Der Link, über den eine Installation kam. Wird einmal geliefert, null, wenn es keinen gab.

Future<LotseLink?> resolveLink(String slug)

Macht aus dem Slug eines geöffneten Links Ziel-Route und Kampagne.

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

Schreibt ein Event mit String-Properties in den Strom.

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

Verbindet das Gerät mit einem angemeldeten Nutzer, mit Traits. userHash kommt aus deinem Backend, sobald das Projekt Identitäten prüft.

Future<void> reset()

Für den Logout: Die nächsten Events gehören nicht mehr zum Nutzer.

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

Im Router eingehängt, wird jeder Screenwechsel zum Event screen_view. screenName bestimmt den Namen, sonst gilt der Routenname.

Future<LotsePush?> get initialPush

Der Push, der die App gestartet hat, falls es einen gab.

Stream<LotsePush> get pushOpened

Pushes, die bei laufender App angetippt werden.

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

Öffnet das Feedback-Sheet: Screenshot, Markierungen, Text und Kategorie. metadata wird mit der Meldung gespeichert, askForEmail ergänzt ein optionales E-Mail-Feld.

Vollständige API-Referenz auf pub.devQuellcode auf GitHub

1. Der SHA-256-Fingerprint in der Console muss zu dem Schlüssel gehören, der den installierten Build signiert hat. Debug und Release unterscheiden sich.
2. adb shell pm get-app-links dein.paket zeigt, ob Android die Domain verifiziert hat.
3. Den Link in einer anderen App antippen. In die Adresszeile eines Browsers getippt, öffnet er nie eine App.
4. Der Host im Manifest muss die Link-Domain des Projekts sein, nicht lotse.dev.
5. Deferred Matching braucht Klick und ersten Start im selben Netz. Ein VPN oder der Wechsel von WLAN zu Mobilfunk bricht es.