# Usage

## Recommended integration with `DetourService`

`DetourService` is the recommended orchestration layer. It:

- configures native bridge once,
- merges initial and runtime link handling into one pending intent queue,
- exposes startup readiness via `isInitialLinkProcessed`,
- uses explicit consume semantics (`consumePendingIntent()`),
- suppresses short-window duplicate emissions.

```dart
import 'package:detour_flutter_plugin/detour_flutter_plugin.dart';
import 'package:flutter/material.dart';

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final detour = DetourService();

  @override
  void initState() {
    super.initState();
    detour.addListener(_onDetourChanged);
    _startDetour();
  }

  Future<void> _startDetour() async {
    await detour.start(
      const DetourConfig(
        apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
        appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
        shouldUseClipboard: true,
        linkProcessingMode: LinkProcessingMode.all,
      ),
    );
  }

  void _onDetourChanged() {
    final intent = detour.pendingIntent;
    if (intent == null) return;

    // Route once, then mark as consumed.
    // context.go(intent.link.route);
    detour.consumePendingIntent();
  }
}
```

If you want complete, runnable integration, go to [Examples](https://detour.swmansion.com/docs/sdk/flutter/examples).

## Link processing mode

`DetourConfig.linkProcessingMode` controls link sources:

| Value | Universal/App links | Deferred links | Custom scheme links |
| --- | --- | --- | --- |
| `LinkProcessingMode.all` (default) | Yes | Yes | Yes |
| `LinkProcessingMode.webOnly` | Yes | Yes | No |
| `LinkProcessingMode.deferredOnly` | No | Yes | No |

## `DetourResult` and routing fields

`DetourResult` contains:

<PropertyList>
  <Property name="processed" />
  <Property name="link" type={"DetourLink?"} />
</PropertyList>

If `link != null`, routing payload is:

<PropertyList>
  <Property name="link.route">
    Path + query.
  </Property>
  <Property name="link.pathname">
    Path only.
  </Property>
  <Property name="link.params" type={"Map<String, String>"} />
  <Property name="link.url">
    Raw URL string.
  </Property>
  <Property name="link.type" type={"deferred | verified | scheme"} />
</PropertyList>

## Manual processing

You can process arbitrary URLs explicitly:

```dart
final result = await detour.processLink(
  'https://example.godetour.link/abc123?source=push',
);

if (result.link != null) {
  // Navigate with result.link!.route
}
```

Use `emitIntent: false` when you need result inspection without pushing intent into service queue.

## Low-level API (`DetourFlutterPlugin`)

If you need full manual control, use `DetourFlutterPlugin` directly:

```dart
final plugin = DetourFlutterPlugin();

await plugin.configure(
  const DetourConfig(
    apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
    appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
  ),
);

final initial = await plugin.resolveInitialLink();
final stream = plugin.linkStream;
final processed = await plugin.processLink('https://example.godetour.link/path');
```

## Analytics

Use predefined enum events only:

```dart
await detour.logEvent(
  DetourEventName.purchase,
  data: {'value': 9.99, 'currency': 'USD'},
);

await detour.logRetention('home_screen_viewed');
```

`logEvent` accepts `DetourEventName` (not arbitrary event strings).

## Related pages

- [Examples](https://detour.swmansion.com/docs/sdk/flutter/examples)
- [API Reference](https://detour.swmansion.com/docs/sdk/flutter/api-reference)
- [Custom Storage](https://detour.swmansion.com/docs/sdk/flutter/custom-storage)
- [Testing & Troubleshooting](https://detour.swmansion.com/docs/sdk/flutter/testing)