admanagekit-mcp-server 1.0.0

package/content/wiki/Rewarded-Ads.md

@@ -0,0 +1,420 @@
+# Rewarded Ads
+
+RewardedAdManager provides a comprehensive solution for integrating rewarded video ads with automatic retry, analytics tracking, and premium user handling.
+
+## Features
+
+- **Automatic Retry**: Exponential backoff on load failures
+- **Premium User Handling**: Automatically skips ads for purchased users
+- **Timeout Support**: For splash screens and time-sensitive scenarios
+- **Firebase Analytics**: Tracks requests, fills, impressions, and show rates
+- **Configurable Auto-Reload**: Automatically reload after ad dismissal
+- **Full Lifecycle Callbacks**: Reward earned, shown, dismissed, clicked, failed
+
+## Quick Start
+
+### 1. Initialize
+
+```kotlin
+// In Application.onCreate() or Activity
+RewardedAdManager.initialize(context, "ca-app-pub-xxx/yyy")
+```
+
+### 2. Show Rewarded Ad
+
+```kotlin
+if (RewardedAdManager.isAdLoaded()) {
+    RewardedAdManager.showAd(activity, object : RewardedAdManager.RewardedAdCallback {
+        override fun onRewardEarned(rewardType: String, rewardAmount: Int) {
+            // Grant reward to user
+            userCoins += rewardAmount
+        }
+
+        override fun onAdDismissed() {
+            // Continue app flow
+        }
+    })
+} else {
+    // Ad not ready - show alternative or wait
+    Toast.makeText(context, "Ad not ready yet", Toast.LENGTH_SHORT).show()
+}
+```
+
+## Callback Interfaces
+
+### RewardedAdCallback (Recommended)
+
+Full lifecycle callback with all events:
+
+```kotlin
+interface RewardedAdCallback {
+    // Required
+    fun onRewardEarned(rewardType: String, rewardAmount: Int)
+    fun onAdDismissed()
+
+    // Optional (default empty implementations)
+    fun onAdShowed() {}
+    fun onAdFailedToShow(error: AdError) {}
+    fun onAdClicked() {}
+}
+```
+
+### OnRewardedAdLoadCallback
+
+For load-specific events:
+
+```kotlin
+interface OnRewardedAdLoadCallback {
+    fun onAdLoaded()
+    fun onAdFailedToLoad(error: LoadAdError)
+}
+```
+
+## Loading Methods
+
+### Basic Load
+
+```kotlin
+// Simple load (auto-retries on failure)
+RewardedAdManager.loadRewardedAd(context)
+```
+
+### Load with Callback
+
+```kotlin
+RewardedAdManager.loadRewardedAd(context, object : RewardedAdManager.OnRewardedAdLoadCallback {
+    override fun onAdLoaded() {
+        // Ad ready to show
+        showWatchAdButton()
+    }
+
+    override fun onAdFailedToLoad(error: LoadAdError) {
+        // Handle error
+        Log.e("Ads", "Failed: ${error.message}")
+    }
+})
+```
+
+### Load with Timeout (Splash Screens)
+
+Perfect for splash screens where you need to proceed after a timeout:
+
+```kotlin
+RewardedAdManager.loadRewardedAdWithTimeout(
+    context = this,
+    timeoutMillis = 5000, // 5 seconds
+    callback = object : RewardedAdManager.OnRewardedAdLoadCallback {
+        override fun onAdLoaded() {
+            // Show ad or proceed
+            showRewardedOffer()
+        }
+
+        override fun onAdFailedToLoad(error: LoadAdError) {
+            // Timeout or error - proceed anyway
+            navigateToMain()
+        }
+    }
+)
+```
+
+**Note**: If the ad loads after timeout, it's saved for next use (not wasted).
+
+## Display Methods
+
+### Show with Callback
+
+```kotlin
+RewardedAdManager.showAd(
+    activity = this,
+    callback = object : RewardedAdManager.RewardedAdCallback {
+        override fun onRewardEarned(rewardType: String, rewardAmount: Int) {
+            // Grant reward
+            addCoins(rewardAmount)
+            showRewardAnimation()
+        }
+
+        override fun onAdDismissed() {
+            // User closed the ad
+            continueGame()
+        }
+
+        override fun onAdShowed() {
+            // Ad is now visible
+            pauseGame()
+        }
+
+        override fun onAdFailedToShow(error: AdError) {
+            // Couldn't show - maybe show alternative
+            Log.e("Ads", "Show failed: ${error.message}")
+        }
+
+        override fun onAdClicked() {
+            // User clicked the ad
+        }
+    },
+    autoReload = true // Reload after dismissal
+)
+```
+
+### Control Auto-Reload
+
+```kotlin
+// Disable auto-reload for this show
+RewardedAdManager.showAd(activity, callback, autoReload = false)
+
+// Or configure globally
+AdManageKitConfig.rewardedAutoReload = false
+```
+
+## State Checking
+
+```kotlin
+// Check if ad is ready
+if (RewardedAdManager.isAdLoaded()) {
+    showWatchAdButton()
+}
+
+// Check if loading
+if (RewardedAdManager.isLoading()) {
+    showLoadingIndicator()
+}
+
+// Check if currently showing
+if (RewardedAdManager.isShowingAd()) {
+    // Don't interrupt
+}
+```
+
+## Preloading
+
+Preload during natural pauses to improve show rate:
+
+```kotlin
+// In Activity.onResume()
+override fun onResume() {
+    super.onResume()
+    RewardedAdManager.preload(this)
+}
+
+// After completing a level
+fun onLevelComplete() {
+    showResults()
+    RewardedAdManager.preload(this) // Preload for next opportunity
+}
+```
+
+## Analytics & Debugging
+
+### Get Statistics
+
+```kotlin
+val stats = RewardedAdManager.getAdStats()
+
+// Available stats:
+// - session_requests: Int
+// - session_fills: Int
+// - session_impressions: Int
+// - fill_rate_percent: Float
+// - show_rate_percent: Float
+// - is_loaded: Boolean
+// - is_loading: Boolean
+// - retry_attempts: Int
+
+Log.d("Ads", """
+    Requests: ${stats["session_requests"]}
+    Fills: ${stats["session_fills"]}
+    Impressions: ${stats["session_impressions"]}
+    Fill Rate: ${stats["fill_rate_percent"]}%
+    Show Rate: ${stats["show_rate_percent"]}%
+""".trimIndent())
+```
+
+### Reset Statistics
+
+```kotlin
+// Reset at start of new session
+RewardedAdManager.resetAdStats()
+```
+
+### Firebase Events
+
+RewardedAdManager automatically logs these Firebase Analytics events:
+
+| Event | Description |
+|-------|-------------|
+| `ad_request` | Ad load requested |
+| `ad_fill` | Ad loaded successfully |
+| `ad_failed_to_load` | Ad failed to load |
+| `ad_impression` | Standard impression event |
+| `ad_impression_detailed` | Detailed with fill/show rates |
+| `ad_dismissed` | User closed the ad |
+| `ad_failed_to_show` | Ad couldn't be shown |
+| `ad_paid_event` | Revenue event for tROAS |
+| `rewarded_ad_reward` | User earned reward |
+
+## Automatic Retry
+
+RewardedAdManager automatically retries failed loads using exponential backoff:
+
+```kotlin
+// Configure retry behavior
+AdManageKitConfig.apply {
+    autoRetryFailedAds = true      // Enable auto-retry (default: true)
+    maxRetryAttempts = 3           // Max attempts (default: 3)
+    baseRetryDelay = 1.seconds     // Base delay (default: 1s)
+    maxRetryDelay = 30.seconds     // Max delay (default: 30s)
+    enableExponentialBackoff = true // Exponential backoff (default: true)
+}
+```
+
+**Retry Schedule** (with exponential backoff):
+- Attempt 1: 1 second delay
+- Attempt 2: 2 seconds delay
+- Attempt 3: 4 seconds delay
+- (capped at maxRetryDelay)
+
+**Manual Load Cancels Retry**: If you manually call `loadRewardedAd()` while a retry is pending, the pending retry is cancelled and a fresh load starts.
+
+## Premium User Handling
+
+RewardedAdManager automatically checks purchase status:
+
+```kotlin
+// If user has purchased premium, these return early:
+RewardedAdManager.loadRewardedAd(context)  // Skips loading
+RewardedAdManager.isAdLoaded()             // Returns false
+RewardedAdManager.showAd(...)              // Calls onAdDismissed() immediately
+```
+
+This requires setting up BillingConfig:
+
+```kotlin
+// In Application.onCreate()
+BillingConfig.setPurchaseProvider(BillingPurchaseProvider())
+```
+
+## Best Practices
+
+### 1. Initialize Early
+
+```kotlin
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        RewardedAdManager.initialize(this, "ca-app-pub-xxx/yyy")
+    }
+}
+```
+
+### 2. Preload Strategically
+
+```kotlin
+// Good places to preload:
+// - After showing an ad (if autoReload is off)
+// - When entering a screen with "Watch Ad" button
+// - After user completes an action
+// - In onResume()
+```
+
+### 3. Handle All States
+
+```kotlin
+fun onWatchAdClicked() {
+    when {
+        RewardedAdManager.isAdLoaded() -> {
+            RewardedAdManager.showAd(activity, callback)
+        }
+        RewardedAdManager.isLoading() -> {
+            showToast("Ad loading, please wait...")
+        }
+        else -> {
+            showToast("No ad available")
+            RewardedAdManager.loadRewardedAd(context)
+        }
+    }
+}
+```
+
+### 4. Don't Block UI
+
+```kotlin
+// DON'T: Block user while loading
+fun showAd() {
+    showBlockingDialog()
+    RewardedAdManager.loadRewardedAd(context, callback) // Bad UX
+}
+
+// DO: Use preloading and show when ready
+fun showAd() {
+    if (RewardedAdManager.isAdLoaded()) {
+        RewardedAdManager.showAd(activity, callback)
+    } else {
+        showToast("Ad not ready")
+    }
+}
+```
+
+## Migration from Legacy API
+
+### Before (Legacy)
+
+```kotlin
+RewardedAdManager.showAd(
+    activity,
+    OnUserEarnedRewardListener { reward ->
+        addCoins(reward.amount)
+    },
+    object : RewardedAdManager.OnAdDismissedListener {
+        override fun onAdDismissed() {
+            continueFlow()
+        }
+    }
+)
+```
+
+### After (New API)
+
+```kotlin
+RewardedAdManager.showAd(activity, object : RewardedAdManager.RewardedAdCallback {
+    override fun onRewardEarned(rewardType: String, rewardAmount: Int) {
+        addCoins(rewardAmount)
+    }
+
+    override fun onAdDismissed() {
+        continueFlow()
+    }
+
+    // Now you also get:
+    override fun onAdShowed() { pauseGame() }
+    override fun onAdFailedToShow(error: AdError) { handleError(error) }
+    override fun onAdClicked() { trackClick() }
+})
+```
+
+## Troubleshooting
+
+### Ad Not Loading
+
+1. Check internet connection
+2. Verify ad unit ID is correct
+3. Check if user is premium: `BillingConfig.getPurchaseProvider().isPurchased()`
+4. Check retry status: `RewardedAdManager.getAdStats()["retry_attempts"]`
+
+### Ad Not Showing
+
+1. Check if loaded: `RewardedAdManager.isAdLoaded()`
+2. Check if already showing: `RewardedAdManager.isShowingAd()`
+3. Verify Activity is not finishing
+
+### Low Fill Rate
+
+1. Check `getAdStats()["fill_rate_percent"]`
+2. Consider using multiple ad networks via mediation
+3. Check if test mode is properly configured
+
+## See Also
+
+- [API Reference](../docs/API_REFERENCE.md#rewardedadmanager)
+- [Interstitial Ads](../docs/interstitial-ads.md)
+- [Ad Loading Strategies](../docs/AD_LOADING_STRATEGIES.md)
+- [Billing Integration](Billing-Integration.md)

package/content/wiki/Subscription-Upgrades.md

@@ -0,0 +1,278 @@
+# Subscription Upgrades & Downgrades
+
+AdManageKit v2.9.0 provides full support for subscription tier changes with configurable proration modes.
+
+## Quick Methods
+
+### Upgrade
+
+Upgrades use `CHARGE_PRORATED_PRICE` mode - user pays the price difference immediately.
+
+```kotlin
+// User is on "basic_monthly", upgrade to "premium_monthly"
+AppPurchase.getInstance().upgradeSubscription(activity, "premium_monthly")
+```
+
+### Downgrade
+
+Downgrades use `DEFERRED` mode - change takes effect at the next renewal date.
+
+```kotlin
+// User is on "premium_monthly", downgrade to "basic_monthly"
+AppPurchase.getInstance().downgradeSubscription(activity, "basic_monthly")
+```
+
+## Full Control Method
+
+For precise control over which subscription to replace and how:
+
+```kotlin
+AppPurchase.getInstance().changeSubscription(
+    activity,
+    "premium_monthly",                              // Current subscription ID
+    "premium_yearly",                               // New subscription ID
+    SubscriptionReplacementMode.CHARGE_PRORATED_PRICE  // Proration mode
+)
+```
+
+## Replacement Modes
+
+| Mode | Effect | Best For |
+|------|--------|----------|
+| `CHARGE_PRORATED_PRICE` | User pays price difference immediately | **Upgrades** |
+| `DEFERRED` | Change at next renewal, no immediate charge | **Downgrades** |
+| `WITH_TIME_PRORATION` | Immediate change, remaining value credited | Either |
+| `CHARGE_FULL_PRICE` | Immediate change, full price charged | Revenue maximization |
+| `WITHOUT_PRORATION` | Immediate change, billing date unchanged | Same-tier changes |
+
+### Mode Details
+
+#### CHARGE_PRORATED_PRICE (Recommended for Upgrades)
+
+```kotlin
+// User pays difference between old and new subscription
+// Example: Monthly $5 → Yearly $50
+// User pays: $50 - ($5 * remaining_days/30)
+```
+
+#### DEFERRED (Recommended for Downgrades)
+
+```kotlin
+// No immediate change - user keeps current subscription until renewal
+// At renewal, switches to new (lower) subscription
+// Good for user experience - they get what they paid for
+```
+
+#### WITH_TIME_PRORATION
+
+```kotlin
+// Immediate switch with time-based credit
+// Remaining value of old subscription credited toward new
+// Useful for same-price tier changes
+```
+
+#### CHARGE_FULL_PRICE
+
+```kotlin
+// Immediate switch, full price charged
+// Old subscription remaining value lost
+// Maximum immediate revenue
+```
+
+#### WITHOUT_PRORATION
+
+```kotlin
+// Immediate switch, no price adjustment
+// Billing cycle remains the same
+// Use for same-price tier switches
+```
+
+## Implementation Example
+
+### Subscription Tier Screen
+
+```kotlin
+class SubscriptionTiersActivity : AppCompatActivity() {
+
+    private val tiers = listOf(
+        Tier("basic_monthly", "Basic", "$4.99/mo"),
+        Tier("premium_monthly", "Premium", "$9.99/mo"),
+        Tier("premium_yearly", "Premium Annual", "$99.99/yr")
+    )
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_tiers)
+
+        val currentSub = AppPurchase.getInstance().getActiveSubscriptions().firstOrNull()
+        val currentTierId = currentSub?.getFirstProductId()
+
+        tiers.forEach { tier ->
+            val button = createTierButton(tier)
+
+            when {
+                tier.id == currentTierId -> {
+                    button.text = "Current Plan"
+                    button.isEnabled = false
+                }
+                isUpgrade(currentTierId, tier.id) -> {
+                    button.text = "Upgrade to ${tier.name}"
+                    button.setOnClickListener { upgradeTo(tier.id) }
+                }
+                isDowngrade(currentTierId, tier.id) -> {
+                    button.text = "Downgrade to ${tier.name}"
+                    button.setOnClickListener { downgradeTo(tier.id) }
+                }
+                else -> {
+                    button.text = "Subscribe to ${tier.name}"
+                    button.setOnClickListener { subscribeTo(tier.id) }
+                }
+            }
+        }
+    }
+
+    private fun upgradeTo(tierId: String) {
+        AppPurchase.getInstance().upgradeSubscription(this, tierId)
+    }
+
+    private fun downgradeTo(tierId: String) {
+        AppPurchase.getInstance().downgradeSubscription(this, tierId)
+    }
+
+    private fun subscribeTo(tierId: String) {
+        AppPurchase.getInstance().subscribe(this, tierId)
+    }
+
+    private fun isUpgrade(current: String?, new: String): Boolean {
+        val currentIndex = tiers.indexOfFirst { it.id == current }
+        val newIndex = tiers.indexOfFirst { it.id == new }
+        return currentIndex != -1 && newIndex > currentIndex
+    }
+
+    private fun isDowngrade(current: String?, new: String): Boolean {
+        val currentIndex = tiers.indexOfFirst { it.id == current }
+        val newIndex = tiers.indexOfFirst { it.id == new }
+        return currentIndex != -1 && newIndex < currentIndex
+    }
+}
+```
+
+### Handle Result
+
+The upgrade/downgrade uses the same purchase flow:
+
+```kotlin
+AppPurchase.getInstance().setPurchaseListener(object : PurchaseListener {
+    override fun onProductPurchased(orderId: String?, originalJson: String?) {
+        // Subscription changed successfully
+        Toast.makeText(this, "Subscription updated!", Toast.LENGTH_SHORT).show()
+        updateUI()
+    }
+
+    override fun displayErrorMessage(errorMessage: String?) {
+        Toast.makeText(this, errorMessage, Toast.LENGTH_SHORT).show()
+    }
+
+    override fun onUserCancelBilling() {
+        // User cancelled - no action needed
+    }
+})
+```
+
+## Low-Level API
+
+For direct access to the purchase token:
+
+```kotlin
+val subscription = AppPurchase.getInstance().getSubscription("premium_monthly")
+if (subscription != null) {
+    AppPurchase.getInstance().updateSubscription(
+        activity,
+        "premium_yearly",                              // New subscription ID
+        subscription.purchaseToken,                    // Current purchase token
+        SubscriptionReplacementMode.WITH_TIME_PRORATION
+    )
+}
+```
+
+## Common Scenarios
+
+### Monthly → Yearly (Same Tier)
+
+```kotlin
+// User wants annual billing for same features
+AppPurchase.getInstance().changeSubscription(
+    activity,
+    "premium_monthly",
+    "premium_yearly",
+    SubscriptionReplacementMode.CHARGE_PRORATED_PRICE  // Pay difference for remaining month
+)
+```
+
+### Yearly → Monthly (Same Tier)
+
+```kotlin
+// User wants monthly billing for same features
+AppPurchase.getInstance().changeSubscription(
+    activity,
+    "premium_yearly",
+    "premium_monthly",
+    SubscriptionReplacementMode.DEFERRED  // Change at renewal
+)
+```
+
+### Basic → Premium (Upgrade)
+
+```kotlin
+AppPurchase.getInstance().changeSubscription(
+    activity,
+    "basic_monthly",
+    "premium_monthly",
+    SubscriptionReplacementMode.CHARGE_PRORATED_PRICE
+)
+```
+
+### Premium → Basic (Downgrade)
+
+```kotlin
+AppPurchase.getInstance().changeSubscription(
+    activity,
+    "premium_monthly",
+    "basic_monthly",
+    SubscriptionReplacementMode.DEFERRED
+)
+```
+
+## Error Handling
+
+```kotlin
+val result = AppPurchase.getInstance().changeSubscription(
+    activity,
+    "current_sub",
+    "new_sub",
+    SubscriptionReplacementMode.CHARGE_PRORATED_PRICE
+)
+
+when {
+    result == "OK" -> {
+        // Billing flow started successfully
+    }
+    result.contains("not found") -> {
+        // Subscription ID invalid or not loaded
+        Log.e("Billing", "Invalid subscription ID")
+    }
+    result.contains("No active subscription") -> {
+        // User doesn't have the source subscription
+        // Fall back to regular subscribe
+        AppPurchase.getInstance().subscribe(activity, "new_sub")
+    }
+}
+```
+
+## Best Practices
+
+1. **Use DEFERRED for downgrades** - Users appreciate getting what they paid for
+2. **Use CHARGE_PRORATED_PRICE for upgrades** - Immediate access, fair pricing
+3. **Show clear pricing** - Display what user will pay before confirming
+4. **Handle multiple subscriptions** - User might have multiple active subscriptions
+5. **Test all scenarios** - Use Google Play Console's test tracks