# Flutter SDK

Use `smartlinks_flutter` to connect an iOS or Android Flutter app to SmartLinks. The umbrella package includes analytics, deep linking and optional engagement modules. This guide targets the 2.0.3 package API.

## Install

```bash
flutter pub add smartlinks_flutter:^2.0.3
```

Use a Flutter toolchain compatible with the package's Dart constraint (`^3.9.2`). Check native plugin requirements when setting Android and iOS deployment targets. The native bridge is required for mobile API and AI calls; this is not a web SDK.

## Initialize before using the SDK

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:smartlinks_flutter/smartlinks_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final ready = await SmartLinks.initialize(
    apiKey: 'YOUR_API_KEY',
    isDebug: kDebugMode,
    initializeAds: false,
  );

  if (ready) {
    await SmartLinks.analytics.sendEvent('integration_test', {
      'screen': 'home',
    });
    await SmartLinks.analytics.getLink((route) {
      // Validate route.route and route.parameters, then navigate in your app.
      // Defer navigation until your app's navigator is ready.
    });
  }

  runApp(const MaterialApp(
    home: Scaffold(body: Center(child: Text('SmartLinks integration'))),
  ));
}
```

Replace the placeholder in your own private configuration. Handle an unsuccessful initialization without blocking normal app startup. The example disables optional ads; enable them after configuring placements.

## Android App Links

Register the actual application ID and signing fingerprints in your private app configuration. Add this inside your main activity's Android manifest entry:

```xml
<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="smartlinks.live"
          android:pathPrefix="/l/YOUR_APP_SLUG/" />
</intent-filter>
```

Use your own slug and configured link domain. This filter matches long-form `/l/YOUR_APP_SLUG/...` links; short links use different paths and need corresponding filters. Test the exact links you distribute, using the signing certificate of the installed build.

## iOS Universal Links

Run `pod install` from the `ios` directory after dependency installation. In Xcode, add **Associated Domains** with `applinks:smartlinks.live` (or your configured link domain). Ensure your SmartLinks app configuration has the correct Apple Team ID and bundle identifier.

Test both installed-app links and a new-install flow on a device. A simulator launch alone does not verify deferred attribution.

## Add engagement modules

From an active widget with a valid `BuildContext`, you can open the built-in feedback page:

```dart
await SmartLinks.openFeedback(
  customNavigation: (page) => Navigator.push(
    context,
    MaterialPageRoute(builder: (_) => page),
  ),
);
```

Other entry points include `SmartLinks.openApps`, `SmartLinks.community.open`, `SmartLinks.blogs.open` and `SmartLinks.showPromoDialog`. Community authentication, ads, purchase verification and AI Gateway need their own dashboard and platform setup.

For AI requests, enable AI Gateway and use `SmartLinks.ai`; keep provider secrets on the server. Do not embed provider credentials in Dart code.

## Verify and troubleshoot

- Run a debug build, trigger `integration_test`, and confirm it under the same app in the private dashboard.
- For missing-plugin errors, perform a full native rebuild after installing the package; hot reload does not install native plugins.
- For `401` or missing events, follow [API keys and security](/docs/authentication).
- Review the [published package documentation](https://pub.dev/packages/smartlinks_flutter) and [API reference](https://pub.dev/documentation/smartlinks_flutter/latest/) for detailed module signatures.