admanagekit-mcp-server 1.0.0

package/content/docs/release-notes/RELEASE_NOTES_v3.3.4.md

@@ -0,0 +1,142 @@
+# Release Notes - v3.3.4
+
+## Highlights
+
+- **Subscription Expiry Verification**: Server-side verification API to get accurate subscription expiry dates
+- **Expiry Time Methods**: New methods to check remaining days, formatted expiry dates, and expiration status
+
+---
+
+## New Features
+
+### Subscription Expiry Verification
+
+Google Play Billing Library does NOT provide subscription expiry dates client-side. This release adds a server-side verification API to get accurate expiry information.
+
+#### Setting Up Verification Callback
+
+```kotlin
+// In Application.onCreate()
+AppPurchase.getInstance().setSubscriptionVerificationCallback { packageName, subscriptionId, purchaseToken, listener ->
+    // Call your backend API
+    yourApi.verifySubscription(packageName, subscriptionId, purchaseToken,
+        onSuccess = { expiryTimeMillis ->
+            val details = SubscriptionVerificationCallback.SubscriptionDetails.Builder()
+                .setExpiryTimeMillis(expiryTimeMillis)
+                .setAutoRenewing(true)
+                .build()
+            listener.onVerified(details)
+        },
+        onError = { error ->
+            listener.onVerificationFailed(error)
+        }
+    )
+}
+```
+
+#### Verifying Subscriptions
+
+```kotlin
+// Verify single subscription
+AppPurchase.getInstance().verifySubscription("premium_monthly",
+    object : AppPurchase.SubscriptionVerificationListener {
+        override fun onVerified(subscription: PurchaseResult) {
+            val expiryDate = subscription.getExpiryTimeFormatted("dd MMM yyyy")
+            val daysLeft = subscription.getRemainingDays()
+            val isExpired = subscription.isExpired()
+        }
+        override fun onVerificationFailed(errorMessage: String?) { }
+    }
+)
+
+// Verify all active subscriptions
+AppPurchase.getInstance().verifyAllSubscriptions(listener)
+```
+
+#### Accessing Expiry Data
+
+After verification, expiry data is cached and accessible:
+
+```kotlin
+// Via AppPurchase
+val expiryMillis = AppPurchase.getInstance().getSubscriptionExpiryTime("premium_monthly")
+val expiryFormatted = AppPurchase.getInstance().getSubscriptionExpiryTimeFormatted("premium_monthly")
+val daysLeft = AppPurchase.getInstance().getSubscriptionRemainingDays("premium_monthly")
+val isExpired = AppPurchase.getInstance().isSubscriptionExpired("premium_monthly")
+
+// Via PurchaseResult
+val subscription = AppPurchase.getInstance().getSubscription("premium_monthly")
+if (subscription?.isExpiryVerified() == true) {
+    val expiryDate = subscription.getExpiryDate()           // Date object
+    val remainingTime = subscription.getRemainingTime()     // Milliseconds
+    val remainingDays = subscription.getRemainingDays()     // Days
+}
+```
+
+### New PurchaseResult Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `getExpiryTime()` | `Long` | Expiry time in milliseconds |
+| `getExpiryDate()` | `Date?` | Expiry as Date object |
+| `getExpiryTimeFormatted()` | `String` | Formatted expiry date |
+| `getExpiryTimeFormatted(pattern)` | `String` | Custom format pattern |
+| `isExpiryVerified()` | `Boolean` | Whether expiry has been verified |
+| `isExpired()` | `Boolean` | Whether subscription has expired |
+| `getRemainingTime()` | `Long` | Milliseconds until expiry |
+| `getRemainingDays()` | `Int` | Days until expiry |
+
+### New AppPurchase Methods
+
+| Method | Description |
+|--------|-------------|
+| `setSubscriptionVerificationCallback()` | Set callback for server verification |
+| `verifySubscription(id, listener)` | Verify single subscription |
+| `verifyAllSubscriptions(listener)` | Verify all active subscriptions |
+| `getSubscriptionExpiryTime(id)` | Get expiry time in milliseconds |
+| `getSubscriptionExpiryTimeFormatted(id)` | Get formatted expiry date |
+| `getSubscriptionRemainingDays(id)` | Get remaining days |
+| `isSubscriptionExpired(id)` | Check if subscription expired |
+
+---
+
+## Backend Implementation
+
+Your backend should call Google Play Developer API:
+
+```
+GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/subscriptionsv2/tokens/{purchaseToken}
+```
+
+Response includes:
+- `expiryTime` - RFC 3339 timestamp
+- `subscriptionState` - ACTIVE, CANCELED, IN_GRACE_PERIOD, ON_HOLD, PAUSED, EXPIRED
+- `linkedPurchaseToken` - For upgrade/downgrade tracking
+
+---
+
+## Migration Guide
+
+### From v3.3.3 to v3.3.4
+
+This is a **backward-compatible** release. No code changes required.
+
+**Optional**: To use subscription expiry verification:
+
+1. Implement `SubscriptionVerificationCallback` with your backend API
+2. Call `verifySubscription()` or `verifyAllSubscriptions()` after billing initialization
+3. Access expiry data via `PurchaseResult` or `AppPurchase` helper methods
+
+---
+
+## Full Changelog
+
+### New Features
+- Added `SubscriptionVerificationCallback` interface for server-side verification
+- Added expiry time fields and methods to `PurchaseResult`
+- Added `verifySubscription()` and `verifyAllSubscriptions()` to `AppPurchase`
+- Added expiry helper methods: `getSubscriptionExpiryTime()`, `getSubscriptionRemainingDays()`, etc.
+
+### Documentation
+- Updated wiki/Subscriptions.md with expiry verification guide
+- Updated docs/APP_PURCHASE_GUIDE.md with verification section

package/content/docs/release-notes/RELEASE_NOTES_v3.3.5.md

@@ -0,0 +1,94 @@
+# Release Notes - v3.3.5
+
+**Release Date**: January 2025
+
+## App Open Loading Strategies
+
+This release brings full loading strategy support to AppOpenManager, aligning it with the existing interstitial and native ad loading patterns.
+
+### New Features
+
+#### Loading Strategy Support
+AppOpenManager now properly uses `AdManageKitConfig.appOpenLoadingStrategy`:
+
+- **ON_DEMAND**: Fetches fresh ad with welcome dialog. Uses cached ad if still fresh (within `appOpenAdFreshnessThreshold`).
+- **ONLY_CACHE**: Only shows cached ads instantly. Silently loads new ad in background if unavailable.
+- **HYBRID**: Shows cached if available, fetches with welcome dialog otherwise (recommended).
+
+```kotlin
+AdManageKitConfig.apply {
+    appOpenLoadingStrategy = AdLoadingStrategy.HYBRID  // default
+}
+```
+
+#### Ad Freshness Tracking
+Cached ads now track when they were loaded to prevent showing stale content:
+
+```kotlin
+// Configure freshness threshold (default: 4 hours per Google recommendation)
+AdManageKitConfig.appOpenAdFreshnessThreshold = 4.hours
+
+// Check cached ad age
+val ageMs = appOpenManager.getCachedAdAgeMs()
+```
+
+#### Auto-Reload Configuration
+Control whether ads automatically reload after being dismissed:
+
+```kotlin
+AdManageKitConfig.appOpenAutoReload = true  // default: true
+```
+
+### Bug Fixes
+
+- **Fixed auto-reload after ad dismissal**: Previously, `fetchAd()` was not being called after ad dismissal. Now properly reloads based on `appOpenAutoReload` setting.
+- **Fixed wasted ads**: ON_DEMAND strategy now checks if cached ad is still fresh before discarding it and fetching a new one.
+
+### Deprecations
+
+- **`appOpenFetchFreshAd`**: Deprecated in favor of `appOpenLoadingStrategy`
+  - `appOpenFetchFreshAd = true` → `appOpenLoadingStrategy = AdLoadingStrategy.ON_DEMAND`
+  - `appOpenFetchFreshAd = false` → `appOpenLoadingStrategy = AdLoadingStrategy.HYBRID`
+
+### Migration
+
+If you were using `appOpenFetchFreshAd`:
+
+```kotlin
+// Before (deprecated)
+AdManageKitConfig.appOpenFetchFreshAd = true
+
+// After
+AdManageKitConfig.appOpenLoadingStrategy = AdLoadingStrategy.ON_DEMAND
+```
+
+### API Changes
+
+#### New Methods in AppOpenManager
+- `getCachedAdAgeMs(): Long` - Returns age of cached ad in milliseconds
+
+#### New Config Options in AdManageKitConfig
+- `appOpenAdFreshnessThreshold: Duration` - Max age for "fresh" cached ad (default: 4 hours)
+- `appOpenAutoReload: Boolean` - Auto-reload after dismissal (default: true)
+
+---
+
+## Installation
+
+```groovy
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v3.3.5'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v3.3.5'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v3.3.5'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v3.3.5'
+```
+
+## Full Changelog
+
+- Full `AdLoadingStrategy` support for AppOpenManager
+- Ad freshness tracking with `adLoadTime` and `appOpenAdFreshnessThreshold`
+- Auto-reload configuration with `appOpenAutoReload`
+- Deprecated `appOpenFetchFreshAd` in favor of `appOpenLoadingStrategy`
+- Fixed auto-reload after ad dismissal
+- Fixed wasted ads when using ON_DEMAND strategy
+- Added `getCachedAdAgeMs()` method
+- Updated documentation for app open ads