# AdTogether Flutter SDK — LLM Integration Reference

**Version:** 0.1.26

**Package:** `adtogether_sdk: ^0.1.26`
**Distribution:** pub.dev
**Targets:** Android, iOS, and Flutter Web — all from ONE Dart package

> **Internal architecture:** On mobile the SDK uses native Platform Channels (Kotlin for Android, Swift for iOS). On Flutter Web it renders ads via `HtmlElementView` loading the Web SDK (`sdk.js`) under the hood.

### Install

```bash
flutter pub add adtogether_sdk
```

### Initialize (required before rendering any ads)

```dart
import 'package:adtogether_sdk/adtogether_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AdTogether.initialize(appId: 'YOUR_APP_ID');
  runApp(MyApp());
}
```

**`AdTogether.initialize()` signature:**
```dart
static Future<void> initialize({
  required String appId,
  String? baseUrl,       // Override API base URL (optional)
  String? bundleId,      // Explicit bundle/package ID (optional, auto-detected via package_info_plus)
  bool allowSelfAds = true,
})
```

**Auto-detected metadata:** The SDK automatically detects `appName`, `appVersion`, and `bundleId` using the `package_info_plus` package. Impression/click tracking payloads include `platform` (e.g. `"android"`, `"ios"`, `"web"`), `environment: "development"|"production"`, `appName`, and `appVersion`.

### Banner Ad

```dart
import 'package:adtogether_sdk/adtogether_sdk.dart';

class MyPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          Expanded(child: Text("App Content")),
          AdTogetherBanner(
            adUnitId: 'home_banner', // optional — any label for this placement
            size: AdSize.banner,
            showCloseButton: true,
            onAdLoaded: () => print('Ad loaded!'),
            onAdFailedToLoad: (error) => print('Error: $error'),
            onAdClosed: () => print('User closed the ad'),
          ),
        ],
      ),
    );
  }
}
```

**`AdTogetherBanner` constructor parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `adUnitId` | `String` | `'default'` | Optional label for this ad placement (e.g. `'home_banner'`, `'chat_bottom'`). Used for analytics grouping only — not validated server-side. |
| `size` | `AdSize` | `AdSize.fluid` | Ad size preset (`fluid`, `banner`, `largeBanner`, `mediumRectangle`) |
| `showCloseButton` | `bool` | `false` | Show a dismissable close button overlay |
| `onAdLoaded` | `VoidCallback?` | — | Fires when ad data loads |
| `onAdFailedToLoad` | `Function(String)?` | — | Fires on load failure |
| `onAdClosed` | `VoidCallback?` | — | Fires when user closes the ad |

### Interstitial Ad

```dart
// Show as a full-screen dialog (imperative API)
AdTogetherInterstitial.show(
  context: context,
  adUnitId: 'level_complete', // optional placement label
  closeDelay: const Duration(seconds: 3),
  onAdLoaded: () => print('Interstitial ready'),
  onAdClosed: () => print('User closed'),
);
```

**`AdTogetherInterstitial.show()` signature:**
```dart
static Future<void> show({
  required BuildContext context,
  String adUnitId = 'default',  // optional placement label
  Duration closeDelay = const Duration(seconds: 3),
  VoidCallback? onAdLoaded,
  Function(String)? onAdFailedToLoad,
  VoidCallback? onAdClosed,
})
```

> **Note:** Flutter uses an imperative `.show()` pattern (not a declarative widget like React). The interstitial opens as a dialog and closes when the user taps the close button.

### Flutter-Specific Notes

- On **iOS**: Ensure `io.flutter.embedded_views_preview` is enabled in `Info.plist` if using older Flutter engines.
- On **Flutter Web**: The SDK renders ads via `HtmlElementView` — no native plugin code runs. Ensure your web host serves the `sdk.js` script.
- On **Android**: Platform Views are used. Minimum SDK version 19 required.
- **Tracking metadata**: All impression/click events automatically include `platform`, `environment`, `appName`, `appVersion`, and `bundleId`. No manual configuration needed.