# AdTogether Native iOS SDK — LLM Integration Reference

**Version:** 0.1.26

**Package:** `AdTogether`
**Distribution:** Swift Package Manager (SPM)
**Targets:** iOS 15+, iPadOS 15+
**Frameworks:** SwiftUI, UIKit

> **Only for pure Swift/UIKit apps.** If you're using Flutter, use SDK #3 (Flutter SDK) instead.

### Install via SPM

In Xcode: **File → Add Packages** → enter the repository URL:

```
https://github.com/undecided2003/AdTogether.git
```

Or add directly to `Package.swift`:

```swift
.package(url: "https://github.com/undecided2003/AdTogether.git", from: "0.1.26")
```

### Initialize

```swift
import AdTogether

@main
struct MyApp: App {
    init() {
        AdTogether.initialize(appId: "YOUR_APP_ID")
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

**`AdTogether.initialize()` signature:**
```swift
public static func initialize(
    appId: String,
    baseUrl: String? = nil,        // Override API base URL (optional)
    allowSelfAds: Bool = true,     // Show own ads as fallback (default: true)
    bundleId: String? = nil        // Explicit bundle ID (optional, auto-detected from Bundle.main.bundleIdentifier)
)
```

**Auto-detected metadata:** The SDK automatically detects `appName` (from `CFBundleName`/`CFBundleDisplayName`), `appVersion` (from `CFBundleShortVersionString`), and `bundleId` (from `Bundle.main.bundleIdentifier`). These are included in impression/click tracking payloads along with `platform: "ios"` and `environment: "development"|"production"` (based on the `DEBUG` compiler flag).

### Banner Ad (SwiftUI)

```swift
import AdTogether

struct ContentView: View {
    var body: some View {
        VStack {
            Text("My App")
            AdTogetherView(
                adUnitId: "home_banner", // optional — any label for this placement
                showCloseButton: true,
                onAdLoaded: { print("Ad loaded!") },
                onAdClosed: { print("User closed the ad") }
            )
            .frame(height: 50)
        }
    }
}
```

**`AdTogetherView` init:**
```swift
public init(
    adUnitId: String = "default",
    size: AdSize = .fluid,
    showCloseButton: Bool = false,
    onAdLoaded: (() -> Void)? = nil,
    onAdFailedToLoad: ((Error) -> Void)? = nil,
    onAdClosed: (() -> Void)? = nil
)
```

**`AdTogetherView` parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `adUnitId` | `String` | `"default"` | Optional label for this ad placement. Used for analytics grouping only. |
| `size` | `AdSize` | `.fluid` | Ad size preset (`.fluid`, `.banner`, `.largeBanner`, `.mediumRectangle`) |
| `showCloseButton` | `Bool` | `false` | Show a dismissable close button overlay |
| `onAdLoaded` | `(() -> Void)?` | — | Fires when ad data loads |
| `onAdFailedToLoad` | `((Error) -> Void)?` | — | Fires on load failure |
| `onAdClosed` | `(() -> Void)?` | — | Fires when user closes the ad |

### Interstitial Ad (SwiftUI)

```swift
import AdTogether

struct ContentView: View {
    @State private var showAd = false

    var body: some View {
        VStack {
            Text("My App")

            Button("Show Interstitial") {
                showAd = true
            }
            .fullScreenCover(isPresented: $showAd) {
                AdTogetherInterstitialView(adUnitId: "level_complete") { // optional placement label
                    showAd = false
                } onAdLoaded: {
                    print("Interstitial loaded")
                }
            }
        }
    }
}
```

**`AdTogetherInterstitialView` init:**
```swift
public init(
    adUnitId: String = "default",   // optional placement label
    closeDelay: Int = 3,           // Seconds before close button appears
    onDismiss: @escaping () -> Void,
    onAdLoaded: (() -> Void)? = nil,
    onAdFailedToLoad: ((Error) -> Void)? = nil
)
```


### iOS-Specific Notes

- Request **App Tracking Transparency (ATT)** permissions before initializing the SDK for personalized ad tracking.
- Add `NSUserTrackingUsageDescription` to `Info.plist` with a human-readable explanation.
- **Tracking metadata**: All impression/click events automatically include `platform`, `environment`, `appName`, `appVersion`, and `bundleId`. No manual configuration needed.