# PrimeAds — Integration Guide

This guide is for **app publishers** who want to add PrimeAds to their Android
app. The integration is fully transparent: you add the SDK to your `build.gradle`,
declare it in your `AndroidManifest.xml`, and disclose it in your Privacy Policy.

---

## 1. Register on the publisher panel

Go to `https://ads.pmsoft.pk/publisher/index.php?action=register` and create an
account. Wait for super-admin approval (usually within 24 hours).

After approval:
1. Add your app — provide name, package name, category. You'll receive an
   **API key** (64-hex token).
2. For each placement in your app, create an **ad unit**. Pick the format
   (banner / interstitial / rewarded / native / app_open). You'll receive a
   **unit ID** (12 chars).

---

## 2. Add the SDK

### Option A — local module

Drop the `primeads-sdk/` folder into your project root, then in
`settings.gradle`:

```gradle
include ':app', ':primeads-sdk'
```

In your app's `build.gradle`:

```gradle
dependencies {
    implementation project(':primeads-sdk')
}
```

### Option B — pre-built AAR

Build the AAR once:

```
./gradlew :primeads-sdk:assembleRelease
```

The output lands at `primeads-sdk/build/outputs/aar/primeads-sdk-release.aar`.
Copy it into `app/libs/`, then:

```gradle
dependencies {
    implementation files('libs/primeads-sdk-release.aar')
}
```

---

## 3. Initialize once

Create or extend an `Application` class:

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        PrimeAds.initialize(
            context  = this,
            apiKey   = "YOUR_API_KEY",
            serverUrl = "https://ads.pmsoft.pk",
            debug    = BuildConfig.DEBUG,
        )
    }
}
```

Declare in `AndroidManifest.xml`:

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

---

## 4. Show a banner

### XML

```xml
<pk.pmsoft.primeads.formats.BannerAdView
    android:id="@+id/banner"
    android:layout_width="match_parent"
    android:layout_height="50dp"
    app:adUnitId="YOUR_BANNER_UNIT_ID" />
```

```kotlin
findViewById<BannerAdView>(R.id.banner).loadAd()
```

### Programmatically

```kotlin
val banner = BannerAdView(this).apply {
    adUnitId = "YOUR_BANNER_UNIT_ID"
    listener = object : BannerAdView.Listener {
        override fun onAdLoaded() { /* shown */ }
        override fun onAdFailedToLoad(reason: String) { /* hide or fallback */ }
    }
    loadAd()
}
parent.addView(banner)
```

---

## 5. Other ad types (Phase 2 / 3)

The SDK exposes the API surface for all five formats today. Banner is fully
functional. Interstitial, Rewarded, Native, and App-Open will become functional
as their server-side and full-screen rendering is added in subsequent phases.
The integration code you write today will not change when those phases ship.

```kotlin
// Interstitial
val interstitial = InterstitialAd(context).apply {
    adUnitId = "YOUR_INTERSTITIAL_UNIT_ID"
}
interstitial.load()
// later:
if (interstitial.isReady()) interstitial.show(activity)

// Rewarded
val rewarded = RewardedAd(context).apply { adUnitId = "YOUR_REWARDED_UNIT_ID" }
rewarded.load()
rewarded.show(activity) { reward ->
    // grant the user `reward.amount` of `reward.type`
}

// App Open
val appOpen = AppOpenAd().apply { adUnitId = "YOUR_APP_OPEN_UNIT_ID" }
appOpen.load()
// on app foreground:
appOpen.showAdIfAvailable(activity)
```

---

## 6. Privacy & Play Store compliance

PrimeAds is a transparent, disclosed advertising SDK. You **must** disclose its
use to comply with Google Play policies and the GDPR (if you target the EU).

See `PRIVACY.md` for a Privacy Policy snippet you can paste into your existing
policy.

In the Play Console > Data Safety form, declare:
- **Data collected:** Device or other IDs (advertising ID), App activity
  (advertising interactions), Device info (OS version, model)
- **Purpose:** Advertising or marketing
- **Sharing:** Yes — with PrimeAds (Prime Soft Pvt Ltd) and any advertisers
  via aggregated reporting
- **Encryption in transit:** Yes (HTTPS)

---

## 7. Troubleshooting

| Symptom                              | Fix                                                                  |
|--------------------------------------|----------------------------------------------------------------------|
| `must call PrimeAds.initialize()`    | Move `initialize` into your `Application.onCreate()`                 |
| Banner stays blank                   | Check the unit ID & app status in publisher panel; enable `debug=true` |
| HTTP 401 in logs                     | API key is wrong or app status is not `active`                       |
| HTTP 204 (no fill)                   | No ads matched targeting — normal. Will fill once advertisers are live |
| Image loads slowly                   | Server-side: enable HTTP/2 and gzip in Hostinger control panel       |