# AdTogether Native Android SDK — LLM Integration Reference

**Version:** 0.1.26

**Package:** `com.relaxsoftwareapps.adtogether:sdk`
**Distribution:** Maven Central
**Targets:** Android API 21+ (minSdk 21)
**Frameworks:** Jetpack Compose, XML Views

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

### Install via Gradle

Add to your module-level `build.gradle.kts`:

```kotlin
dependencies {
    implementation("com.relaxsoftwareapps.adtogether:sdk:0.1.26")
}
```

### Initialize

```kotlin
import com.adtogether.sdk.AdTogether

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AdTogether.initialize(this, "YOUR_APP_ID")
    }
}
```

Register `MyApp` in `AndroidManifest.xml`:

```xml
<application android:name=".MyApp" ... >
```

**`AdTogether.initialize()` signature:**
```kotlin
fun initialize(
    context: Context,
    appId: String,
    baseUrl: String? = null,       // Override API base URL (optional)
    allowSelfAds: Boolean = true,  // Show own ads as fallback (default: true)
    bundleId: String? = null       // Explicit package ID (optional, auto-detected from context.packageName)
)
```

> **Key difference from other SDKs:** Android requires a `Context` as the first parameter.

**Auto-detected metadata:** The SDK automatically detects `appName`, `appVersion`, and `bundleId` from the `PackageManager`. These are included in impression/click tracking payloads along with `platform: "android"` and `environment: "development"|"production"` (based on the app's debuggable flag).

### Banner Ad (Jetpack Compose)

```kotlin
import com.adtogether.sdk.views.AdTogetherView

@Composable
fun MainScreen() {
    Column {
        Text("My App")
        AdTogetherView(
            adUnitId = "home_banner", // optional — any label for this placement
            modifier = Modifier.fillMaxWidth().height(50.dp),
            showCloseButton = true,
            onAdLoaded = { println("Ad loaded!") },
            onAdClosed = { println("User closed the ad") }
        )
    }
}
```

**`AdTogetherView` composable signature:**
```kotlin
@Composable
fun AdTogetherView(
    adUnitId: String = "default",
    size: AdSize = AdSize.FLUID,
    showCloseButton: Boolean = false,
    onAdLoaded: (() -> Unit)? = null,
    onAdFailedToLoad: ((String) -> Unit)? = null,
    onAdClosed: (() -> Unit)? = null,
    modifier: Modifier = Modifier
)
```

**`AdTogetherView` 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`, `LARGE_BANNER`, `MEDIUM_RECTANGLE`) |
| `showCloseButton` | `Boolean` | `false` | Show a dismissable close button overlay |
| `onAdLoaded` | `(() -> Unit)?` | — | Fires when ad data loads |
| `onAdFailedToLoad` | `((String) -> Unit)?` | — | Fires on load failure |
| `onAdClosed` | `(() -> Unit)?` | — | Fires when user closes the ad |
| `modifier` | `Modifier` | `Modifier` | Jetpack Compose modifier |

### Interstitial Ad (Jetpack Compose)

```kotlin
import com.adtogether.sdk.views.AdTogetherInterstitial

@Composable
fun MainScreen() {
    var showAd by remember { mutableStateOf(false) }

    Column {
        Text("My App")

        Button(onClick = { showAd = true }) {
            Text("Show Interstitial")
        }

        if (showAd) {
            AdTogetherInterstitial(
                adUnitId = "level_complete", // optional placement label
                closeDelay = 3,
                onDismiss = { showAd = false },
                onAdLoaded = { println("Interstitial loaded") }
            )
        }
    }
}
```

**`AdTogetherInterstitial` composable signature:**
```kotlin
@Composable
fun AdTogetherInterstitial(
    adUnitId: String = "default",    // optional placement label
    closeDelay: Int = 3,            // Seconds before close button appears
    onDismiss: () -> Unit,
    onAdLoaded: (() -> Unit)? = null,
    onAdFailedToLoad: ((String) -> Unit)? = null,
    modifier: Modifier = Modifier
)
```

### Android-Specific Notes

- **XML Layout Support**: If you are using classic XML views, you can bridge the Compose view using `ComposeView` into your XML layout. Native XML `AdTogetherBannerView` is coming soon.
- **ProGuard/R8**: If using ProGuard/R8, add the following keep rule:
  ```
  -keep class com.adtogether.sdk.** { *; }
  ```
- **Tracking metadata**: All impression/click events automatically include `platform`, `environment`, `appName`, `appVersion`, and `bundleId`. No manual configuration needed.