@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/levelplay-unity-integration/references/interstitial-api.md

@@ -0,0 +1,907 @@
+# Interstitial Ads API Reference
+
+## Contents
+- [Overview](#overview)
+- [Key Characteristics](#key-characteristics)
+- [Implementation Pattern](#implementation-pattern)
+- [API Reference](#api-reference)
+- [Data Types](#data-types)
+- [Best Practices](#best-practices)
+- [Common Issues](#common-issues)
+- [Testing Checklist](#testing-checklist)
+
+## Overview
+
+Interstitial ads are full-screen video or static ads shown at natural transition points in your app. They provide good revenue while maintaining acceptable user experience when placed thoughtfully.
+
+## Key Characteristics
+
+- **Full-screen**: Takes over the entire screen
+- **Skippable**: User can close after viewing
+- **Best for**: Level transitions, game over, menu navigation, session breaks
+
+## Implementation Pattern
+
+### Basic Interstitial Implementation
+
+```csharp
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class InterstitialAdManager : MonoBehaviour
+{
+    private LevelPlayInterstitialAd interstitialAd;
+    private string adUnitId = "YOUR_INTERSTITIAL_AD_UNIT_ID";
+
+    void Start()
+    {
+        // Create the interstitial ad object using constructor
+        interstitialAd = new LevelPlayInterstitialAd(adUnitId);
+
+        // ILRD (SDK 9.5.0+): if impression-revenue tracking is enabled, also subscribe here —
+        //   interstitialAd.OnAdImpressionDataReady += OnImpressionDataReady;   // see references/ilrd-api.md
+
+        // Register event listeners
+        interstitialAd.OnAdLoaded += OnAdLoaded;
+        interstitialAd.OnAdLoadFailed += OnAdLoadFailed;
+        interstitialAd.OnAdDisplayed += OnAdDisplayed;
+        interstitialAd.OnAdDisplayFailed += OnAdDisplayFailed;
+        interstitialAd.OnAdClicked += OnAdClicked;
+        interstitialAd.OnAdClosed += OnAdClosed;
+        interstitialAd.OnAdInfoChanged += OnAdInfoChanged;   // Fires when the loaded ad updates after a new auction result
+
+        // Load the ad
+        LoadAd();
+    }
+
+    void OnDestroy()
+    {
+        // Unregister event listeners
+        if (interstitialAd != null)
+        {
+            interstitialAd.OnAdLoaded -= OnAdLoaded;
+            interstitialAd.OnAdLoadFailed -= OnAdLoadFailed;
+            interstitialAd.OnAdDisplayed -= OnAdDisplayed;
+            interstitialAd.OnAdDisplayFailed -= OnAdDisplayFailed;
+            interstitialAd.OnAdClicked -= OnAdClicked;
+            interstitialAd.OnAdClosed -= OnAdClosed;
+            interstitialAd.OnAdInfoChanged -= OnAdInfoChanged;
+            // ILRD (9.5.0+): interstitialAd.OnAdImpressionDataReady -= OnImpressionDataReady;
+
+            // Free the native ad and its resources when this manager is destroyed
+            interstitialAd.DestroyAd();
+        }
+    }
+
+    public void LoadAd()
+    {
+        Debug.Log("Loading interstitial ad...");
+        interstitialAd.LoadAd();
+    }
+
+    public void ShowAd()
+    {
+        if (interstitialAd.IsAdReady())
+        {
+            Debug.Log("Showing interstitial ad");
+            interstitialAd.ShowAd();
+        }
+        else
+        {
+            Debug.LogWarning("Interstitial ad is not ready yet");
+        }
+    }
+
+    // True once an interstitial ad has finished loading and can be shown.
+    // Use this to decide whether to show opportunistically before calling ShowAd().
+    public bool IsAdReady() => interstitialAd != null && interstitialAd.IsAdReady();
+
+    // Event Callbacks
+    private void OnAdLoaded(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial ad loaded successfully");
+    }
+
+    private void OnAdLoadFailed(LevelPlayAdError error)
+    {
+        Debug.LogWarning($"Interstitial ad failed to load: {error.ErrorMessage}");
+        // Retry loading after a delay
+        Invoke(nameof(LoadAd), 30f);
+    }
+
+    private void OnAdDisplayed(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial ad displayed");
+    }
+
+    private void OnAdDisplayFailed(LevelPlayAdInfo adInfo, LevelPlayAdError error)
+    {
+        Debug.LogError($"Interstitial ad failed to display: {error.ErrorMessage}");
+        // Load a new ad
+        LoadAd();
+    }
+
+    private void OnAdClicked(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial ad clicked");
+    }
+
+    private void OnAdClosed(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial ad closed");
+        // Load the next ad
+        LoadAd();
+    }
+
+    private void OnAdInfoChanged(LevelPlayAdInfo adInfo)
+    {
+        // Optional: log or update analytics with the latest revenue estimate
+        Debug.Log($"Interstitial ad info changed - network: {adInfo.AdNetwork}, revenue: ${adInfo.Revenue}");
+    }
+}
+```
+
+### Advanced: Frequency Capping
+
+Implement time-based frequency capping to avoid showing ads too frequently:
+
+```csharp
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class FrequencyCappedInterstitialManager : MonoBehaviour
+{
+    private LevelPlayInterstitialAd interstitialAd;
+    private string adUnitId = "YOUR_INTERSTITIAL_AD_UNIT_ID";
+
+    // Frequency capping settings
+    private float minTimeBetweenAds = 300f; // 5 minutes in seconds
+    private float lastAdShownTime = -999f; // Time when last ad was shown
+
+    void Start()
+    {
+        // Create interstitial ad object
+        interstitialAd = new LevelPlayInterstitialAd(adUnitId);
+
+        // Register callbacks
+        interstitialAd.OnAdLoaded += OnAdLoaded;
+        interstitialAd.OnAdLoadFailed += OnAdLoadFailed;
+        interstitialAd.OnAdDisplayed += OnAdDisplayed;
+        interstitialAd.OnAdClosed += OnAdClosed;
+        interstitialAd.OnAdDisplayFailed += OnAdDisplayFailed;
+
+        // Load first ad
+        interstitialAd.LoadAd();
+    }
+
+    void OnDestroy()
+    {
+        if (interstitialAd != null)
+        {
+            interstitialAd.OnAdLoaded -= OnAdLoaded;
+            interstitialAd.OnAdLoadFailed -= OnAdLoadFailed;
+            interstitialAd.OnAdDisplayed -= OnAdDisplayed;
+            interstitialAd.OnAdClosed -= OnAdClosed;
+            interstitialAd.OnAdDisplayFailed -= OnAdDisplayFailed;
+
+            // Destroy the ad to free its native resources
+            interstitialAd.DestroyAd();
+        }
+    }
+
+    public void TryShowInterstitial()
+    {
+        // Check if enough time has passed since last ad
+        float timeSinceLastAd = Time.time - lastAdShownTime;
+
+        if (timeSinceLastAd < minTimeBetweenAds)
+        {
+            Debug.Log($"Frequency cap: {minTimeBetweenAds - timeSinceLastAd:F0}s until next ad");
+            return;
+        }
+
+        // Check if ad is ready
+        if (interstitialAd.IsAdReady())
+        {
+            interstitialAd.ShowAd();
+        }
+        else
+        {
+            Debug.LogWarning("Interstitial not ready, loading...");
+            interstitialAd.LoadAd();
+        }
+    }
+
+    private void OnAdLoaded(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial loaded");
+    }
+
+    private void OnAdLoadFailed(LevelPlayAdError error)
+    {
+        Debug.LogWarning($"Interstitial load failed: {error.ErrorMessage}");
+        Invoke(nameof(LoadAd), 30f);
+    }
+
+    private void OnAdDisplayed(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial displayed");
+        lastAdShownTime = Time.time; // Record when ad was shown
+    }
+
+    private void OnAdClosed(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial closed");
+        // Load next ad
+        interstitialAd.LoadAd();
+    }
+
+    private void OnAdDisplayFailed(LevelPlayAdInfo adInfo, LevelPlayAdError error)
+    {
+        Debug.LogError($"Interstitial display failed: {error.ErrorMessage}");
+        interstitialAd.LoadAd();
+    }
+
+    private void LoadAd()
+    {
+        if (interstitialAd != null)
+        {
+            interstitialAd.LoadAd();
+        }
+    }
+}
+```
+
+### Advanced: Multiple Placements
+
+Track different interstitial placements for analytics:
+
+```csharp
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class MultiPlacementInterstitialManager : MonoBehaviour
+{
+    private LevelPlayInterstitialAd interstitialAd;
+    private string adUnitId = "YOUR_INTERSTITIAL_AD_UNIT_ID";
+
+    // Placement names
+    private const string PLACEMENT_LEVEL_COMPLETE = "level_complete";
+    private const string PLACEMENT_GAME_OVER = "game_over";
+    private const string PLACEMENT_MAIN_MENU = "main_menu";
+
+    // Frequency capping per placement
+    private float minTimeBetweenAds = 300f;
+    private float lastAdTime = -999f;
+
+    void Start()
+    {
+        interstitialAd = new LevelPlayInterstitialAd(adUnitId);
+
+        interstitialAd.OnAdLoaded += OnAdLoaded;
+        interstitialAd.OnAdLoadFailed += OnAdLoadFailed;
+        interstitialAd.OnAdDisplayed += OnAdDisplayed;
+        interstitialAd.OnAdClosed += OnAdClosed;
+        interstitialAd.OnAdDisplayFailed += OnAdDisplayFailed;
+
+        interstitialAd.LoadAd();
+    }
+
+    void OnDestroy()
+    {
+        if (interstitialAd != null)
+        {
+            interstitialAd.OnAdLoaded -= OnAdLoaded;
+            interstitialAd.OnAdLoadFailed -= OnAdLoadFailed;
+            interstitialAd.OnAdDisplayed -= OnAdDisplayed;
+            interstitialAd.OnAdClosed -= OnAdClosed;
+            interstitialAd.OnAdDisplayFailed -= OnAdDisplayFailed;
+
+            // Destroy the ad to free its native resources
+            interstitialAd.DestroyAd();
+        }
+    }
+
+    // Public methods for different placements
+    public void ShowOnLevelComplete()
+    {
+        TryShowWithPlacement(PLACEMENT_LEVEL_COMPLETE);
+    }
+
+    public void ShowOnGameOver()
+    {
+        TryShowWithPlacement(PLACEMENT_GAME_OVER);
+    }
+
+    public void ShowOnMainMenu()
+    {
+        TryShowWithPlacement(PLACEMENT_MAIN_MENU);
+    }
+
+    private void TryShowWithPlacement(string placementName)
+    {
+        // Check frequency cap
+        if (Time.time - lastAdTime < minTimeBetweenAds)
+        {
+            Debug.Log($"Frequency cap active for {placementName}");
+            return;
+        }
+
+        // Check placement capping
+        if (LevelPlayInterstitialAd.IsPlacementCapped(placementName))
+        {
+            Debug.Log($"Placement {placementName} is capped");
+            return;
+        }
+
+        // Check if ad ready
+        if (interstitialAd.IsAdReady())
+        {
+            Debug.Log($"Showing interstitial with placement: {placementName}");
+            interstitialAd.ShowAd(placementName: placementName);
+        }
+        else
+        {
+            Debug.LogWarning("Interstitial not ready");
+        }
+    }
+
+    private void OnAdLoaded(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial loaded");
+    }
+
+    private void OnAdLoadFailed(LevelPlayAdError error)
+    {
+        Debug.LogWarning($"Interstitial load failed: {error.ErrorMessage}");
+        Invoke(nameof(LoadAd), 30f);
+    }
+
+    private void OnAdDisplayed(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial displayed");
+        lastAdTime = Time.time;
+    }
+
+    private void OnAdClosed(LevelPlayAdInfo adInfo)
+    {
+        Debug.Log("Interstitial closed");
+        interstitialAd.LoadAd();
+    }
+
+    private void OnAdDisplayFailed(LevelPlayAdInfo adInfo, LevelPlayAdError error)
+    {
+        Debug.LogError($"Interstitial display failed: {error.ErrorMessage}");
+        interstitialAd.LoadAd();
+    }
+
+    private void LoadAd()
+    {
+        if (interstitialAd != null)
+        {
+            interstitialAd.LoadAd();
+        }
+    }
+}
+```
+
+## API Reference
+
+### Constructor
+
+#### `new LevelPlayInterstitialAd(string adUnitId)`
+Create an interstitial ad object.
+
+**Parameters:**
+- `adUnitId`: The ad unit identifier from your LevelPlay dashboard
+
+**Returns:** `LevelPlayInterstitialAd` object
+
+**Usage:**
+```csharp
+LevelPlayInterstitialAd interstitialAd = new LevelPlayInterstitialAd("your_ad_unit_id");
+```
+
+**Important:** Call this only after `LevelPlay.Init()` has completed successfully (in the `OnInitSuccess` callback).
+
+#### `new LevelPlayInterstitialAd(string adUnitId, Config config)`
+Create an interstitial ad object with custom configuration.
+
+**Parameters:**
+- `adUnitId`: The ad unit identifier
+- `config`: Optional configuration object
+
+**Usage:**
+```csharp
+var configBuilder = new LevelPlayInterstitialAd.Config.Builder();
+configBuilder.SetBidFloor(1.0); // Minimum bid price in USD
+var config = configBuilder.Build();
+LevelPlayInterstitialAd interstitialAd = new LevelPlayInterstitialAd("your_ad_unit_id", config);
+```
+
+### Configuration Builder
+
+#### `LevelPlayInterstitialAd.Config.Builder()`
+Create a configuration builder for interstitial ads.
+
+**Returns:** `LevelPlayInterstitialAd.Config.Builder` object
+
+**Usage:**
+```csharp
+var configBuilder = new LevelPlayInterstitialAd.Config.Builder();
+```
+
+**Set minimum bid price:**
+```csharp
+configBuilder.SetBidFloor(1.0); // Minimum bid price in USD ($1.00 CPM)
+```
+
+**When to use:** Set a minimum bid price in USD for ad requests.
+
+#### `Build()`
+Build the configuration object.
+
+**Returns:** `LevelPlayInterstitialAd.Config` object
+
+**Usage:**
+```csharp
+var config = configBuilder.Build();
+```
+
+### Core Methods
+
+#### `LoadAd()`
+Load an interstitial ad.
+
+**Usage:**
+```csharp
+interstitialAd.LoadAd();
+```
+
+**When to call:**
+- After SDK initialization completes
+- After showing an ad (to load the next one)
+- After a load or display failure
+
+#### `ShowAd()`
+Show the interstitial ad without a placement name.
+
+**Usage:**
+```csharp
+if (interstitialAd.IsAdReady())
+{
+    interstitialAd.ShowAd();
+}
+```
+
+**Important:** Always check `IsAdReady()` before calling `ShowAd()`.
+
+#### `ShowAd(placementName: string)`
+Show the interstitial ad with a named placement for analytics tracking.
+
+**Parameters:**
+- `placementName`: Placement name configured in LevelPlay dashboard
+
+**Usage:**
+```csharp
+interstitialAd.ShowAd(placementName: "level_complete");
+```
+
+**When to use:** When tracking multiple placements within the same ad unit for analytics.
+
+#### `IsAdReady()`
+Check if an interstitial ad is loaded and ready to show.
+
+**Returns:** `bool` - true if ready, false otherwise
+
+**Usage:**
+```csharp
+if (interstitialAd.IsAdReady())
+{
+    // Ad is ready to show
+    interstitialAd.ShowAd();
+}
+else
+{
+    // Ad not ready, load it
+    interstitialAd.LoadAd();
+}
+```
+
+#### `LevelPlayInterstitialAd.IsPlacementCapped(string placementName)` (Static)
+Check if a placement has reached its capping limit.
+
+**Parameters:**
+- `placementName`: The placement name to check
+
+**Returns:** `bool` - true if capped, false otherwise
+
+**Usage:**
+```csharp
+if (LevelPlayInterstitialAd.IsPlacementCapped("level_complete"))
+{
+    Debug.Log("Level complete placement is capped");
+}
+```
+
+**When to use:** Before showing an ad to check if the placement frequency cap is reached.
+
+### Events
+
+All events are properties of the `LevelPlayInterstitialAd` object.
+
+**Threading:** All ad callbacks run on the Unity main thread, so you can safely call Unity APIs (update UI, access GameObjects, etc.) directly in these callbacks. This is different from `LevelPlay.OnImpressionDataReady` which runs on a background thread.
+
+#### `OnAdLoaded`
+Fired when an interstitial ad is successfully loaded.
+
+**Signature:** `event Action<LevelPlayAdInfo>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdLoaded += (adInfo) =>
+{
+    Debug.Log("Interstitial ad loaded");
+};
+```
+
+#### `OnAdLoadFailed`
+Fired when an interstitial ad fails to load.
+
+**Signature:** `event Action<LevelPlayAdError>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdLoadFailed += (error) =>
+{
+    Debug.LogWarning($"Load failed: {error.ErrorMessage}");
+};
+```
+
+**Best practice:** Implement retry logic with exponential backoff.
+
+#### `OnAdDisplayed`
+Fired when an interstitial ad is displayed on screen.
+
+**Signature:** `event Action<LevelPlayAdInfo>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdDisplayed += (adInfo) =>
+{
+    Debug.Log("Interstitial ad displayed");
+    // Optional: Track analytics
+};
+```
+
+#### `OnAdDisplayFailed`
+Fired when an interstitial ad fails to display.
+
+**Signature:** `event Action<LevelPlayAdInfo, LevelPlayAdError>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdDisplayFailed += (adInfo, error) =>
+{
+    Debug.LogError($"Display failed: {error.ErrorMessage}");
+    // Load a new ad
+    interstitialAd.LoadAd();
+};
+```
+
+#### `OnAdClicked`
+Fired when the user clicks on the interstitial ad.
+
+**Signature:** `event Action<LevelPlayAdInfo>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdClicked += (adInfo) =>
+{
+    Debug.Log("Interstitial ad clicked");
+    // Optional analytics tracking
+};
+```
+
+#### `OnAdClosed`
+Fired when the interstitial ad is closed.
+
+**Signature:** `event Action<LevelPlayAdInfo>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdClosed += (adInfo) =>
+{
+    Debug.Log("Interstitial ad closed");
+    // Resume game, load next ad
+    interstitialAd.LoadAd();
+};
+```
+
+**Best practice:** Load the next ad immediately in this callback.
+
+#### `OnAdInfoChanged`
+Fired when ad information changes, such as when a new winning ad becomes available after auction.
+
+**Signature:** `event Action<LevelPlayAdInfo>`
+
+**Usage:**
+```csharp
+interstitialAd.OnAdInfoChanged += (adInfo) =>
+{
+    Debug.Log($"Ad info changed - New ad from: {adInfo.AdNetwork}");
+    Debug.Log($"Estimated revenue: ${adInfo.Revenue}");
+};
+```
+
+**Important:** This event indicates that a new ad with potentially different revenue has become available. The SDK automatically selects the winning ad from the auction when you call `ShowAd()`, but this event lets you know when the ad info has been updated. This is particularly important for revenue optimization as it signals when a new auction winner has loaded.
+
+**When it fires:**
+- After a new ad loads with different properties than the previous one
+- When the waterfall selects a different ad network
+- When ad auction results change
+
+**Why it matters:** The updated `LevelPlayAdInfo` contains the latest revenue estimates and network information, which directly impacts your monetization. Always use the most recent `adInfo` when logging or analyzing ad performance.
+
+**If you're using ILRD** (`references/ilrd-api.md`): the `LevelPlayImpressionData` you receive in `OnImpressionDataReady` already contains the final revenue value, so `OnAdInfoChanged` is mostly useful for in-Editor debugging of the waterfall. Most publishers can leave it as a logging hook.
+
+## Data Types
+
+### LevelPlayAdInfo
+
+Contains information about the ad.
+
+**Properties:**
+- `AdId` (string): Unique identifier for this specific ad instance
+- `AdUnitId` (string): The ad unit identifier
+- `AdUnitName` (string): The ad unit name
+- `AdSize` (LevelPlayAdSize): The ad size (may be null; banner-relevant)
+- `AdFormat` (string): The ad format (e.g., "INTERSTITIAL")
+- `PlacementName` (string): Placement name where ad was shown
+- `AuctionId` (string): Unique auction identifier
+- `CreativeId` (string): Creative identifier
+- `Country` (string): User's country code (ISO 3166-1)
+- `Ab` (string): A/B test segment identifier
+- `SegmentName` (string): User segment name
+- `AdNetwork` (string): Ad network that served the ad
+- `InstanceName` (string): Ad network instance name
+- `InstanceId` (string): Ad network instance identifier
+- `Revenue` (double?): Estimated revenue in USD (nullable - check for null)
+- `Precision` (string): Revenue precision level
+- `EncryptedCPM` (string): Encrypted CPM value
+
+### LevelPlayAdError
+
+Contains error information when ad operations fail.
+
+**Properties:**
+- `ErrorCode` (int): Numeric error code
+- `ErrorMessage` (string): Human-readable error description
+- `AdUnitId` (string): The ad unit identifier where the error occurred
+- `AdId` (string): Unique identifier for the specific ad instance
+
+## Best Practices
+
+### Loading Strategy
+
+**Keep an interstitial ready for opportunistic moments:**
+```csharp
+// Load after init
+void OnInitSuccess(LevelPlayConfiguration config)
+{
+    interstitialAd = new LevelPlayInterstitialAd(adUnitId);
+    interstitialAd.OnAdLoaded += OnAdLoaded;
+    interstitialAd.OnAdClosed += OnAdClosed;
+    interstitialAd.LoadAd();
+}
+
+// Reload after showing
+void OnAdClosed(LevelPlayAdInfo adInfo)
+{
+    interstitialAd.LoadAd();
+}
+```
+
+### Placement Strategy
+
+**Show at natural transition points:**
+- ✅ Level complete screen
+- ✅ Game over screen
+- ✅ Returning to main menu
+- ✅ Between sessions
+- ❌ During active gameplay
+- ❌ Mid-level or mid-action
+
+### Frequency Capping
+
+**Implement time-based capping to avoid annoying users:**
+```csharp
+private float minTimeBetweenAds = 300f; // 5 minutes
+private float lastAdTime = -999f;
+
+public void TryShowInterstitial()
+{
+    if (Time.time - lastAdTime < minTimeBetweenAds)
+    {
+        Debug.Log("Too soon to show another ad");
+        return;
+    }
+
+    if (interstitialAd.IsAdReady())
+    {
+        interstitialAd.ShowAd();
+    }
+}
+
+private void OnAdDisplayed(LevelPlayAdInfo adInfo)
+{
+    lastAdTime = Time.time;
+}
+```
+
+**Recommended frequencies:**
+- **Revenue-focused**: 3-5 minutes
+- **Balanced**: 5-7 minutes
+- **UX-focused**: 7-10 minutes or never
+
+### User Flow
+
+**Never block user progress waiting for ads:**
+```csharp
+// ✅ CORRECT - Don't block flow
+public void OnLevelComplete()
+{
+    // Continue to next level regardless of ad
+    LoadNextLevel();
+
+    // Try to show ad, but don't wait for it
+    TryShowInterstitial();
+}
+
+// ❌ WRONG - Blocking user
+public void OnLevelComplete()
+{
+    if (interstitialAd.IsAdReady())
+    {
+        interstitialAd.ShowAd();
+        // Don't wait here to load next level!
+    }
+}
+```
+
+### Error Handling
+
+**Handle ad load failures:**
+```csharp
+private void OnAdLoadFailed(LevelPlayAdError error)
+{
+    Debug.LogWarning($"Ad load failed: {error.ErrorMessage}");
+
+    // Retry loading after a delay
+    Invoke(nameof(RetryLoad), 30f);
+}
+
+private void RetryLoad()
+{
+    interstitialAd.LoadAd();
+}
+```
+
+### Memory Management
+
+**Always unsubscribe from events:**
+```csharp
+void OnDestroy()
+{
+    if (interstitialAd != null)
+    {
+        interstitialAd.OnAdLoaded -= OnAdLoaded;
+        interstitialAd.OnAdLoadFailed -= OnAdLoadFailed;
+        interstitialAd.OnAdDisplayed -= OnAdDisplayed;
+        interstitialAd.OnAdDisplayFailed -= OnAdDisplayFailed;
+        interstitialAd.OnAdClicked -= OnAdClicked;
+        interstitialAd.OnAdClosed -= OnAdClosed;
+        interstitialAd.OnAdInfoChanged -= OnAdInfoChanged;
+
+        // Destroy the ad to free its native resources
+        interstitialAd.DestroyAd();
+    }
+}
+```
+
+## Common Issues
+
+### Issue: Error 1037 (Load during load)
+
+**Cause:** Calling `LoadAd()` repeatedly in `Update()` or other high-frequency loops before the previous load completes.
+
+**Common mistake:**
+```csharp
+void Update()
+{
+    // WRONG - This will cause error 1037!
+    if (!interstitialAd.IsAdReady())
+    {
+        interstitialAd.LoadAd();
+    }
+}
+```
+
+**Why this fails:** If the ad is still loading, calling `LoadAd()` again triggers error 1037: "Cannot load an interstitial while another interstitial is loading."
+
+**Solution:** Track load state manually and only call `LoadAd()` once:
+```csharp
+private bool isLoadingAd = false;
+
+void Start()
+{
+    LoadInterstitialAd();
+}
+
+void LoadInterstitialAd()
+{
+    if (isLoadingAd) return; // Prevent duplicate loads
+    
+    isLoadingAd = true;
+    interstitialAd.LoadAd();
+}
+
+void OnAdLoaded(LevelPlayAdInfo adInfo)
+{
+    isLoadingAd = false;
+}
+
+void OnAdLoadFailed(LevelPlayAdError error)
+{
+    isLoadingAd = false;
+    // Optionally retry after delay
+}
+```
+
+### Issue: Interstitial showing too frequently
+
+**Solution:** Implement frequency capping based on time or session count. Track when the last ad was shown and enforce a minimum interval.
+
+### Issue: User flow blocked by ad loading
+
+**Solution:** Never wait for ads to load or show before progressing the user. Load ads proactively and show them opportunistically.
+
+### Issue: Ad not loading
+
+**Possible causes:**
+- SDK not initialized before creating ad object
+- No internet connection
+- Ad inventory not available
+- Incorrect ad unit ID
+
+**Solutions:**
+- Create ad object only after `OnInitSuccess` callback
+- Check network connectivity
+- Verify ad unit ID in LevelPlay dashboard
+- Test on real device with good connection
+
+### Issue: Ad loading but not showing
+
+**Possible causes:**
+- Not checking `IsAdReady()` before calling `ShowAd()`
+- Ad expired (loaded too long ago)
+
+**Solutions:**
+- Always check `IsAdReady()` before showing
+- Load ads close to when they'll be shown (within a few minutes)
+
+## Testing Checklist
+
+- [ ] Ad loads successfully after SDK initialization
+- [ ] `IsAdReady()` returns true when ad is loaded
+- [ ] Ad displays correctly when `ShowAd()` is called
+- [ ] Ad shows at appropriate transition points only
+- [ ] Frequency capping works as expected
+- [ ] User can progress regardless of ad status
+- [ ] Ad reloads automatically after being shown
+- [ ] Retry logic works when ad fails to load
+- [ ] Multiple placements track correctly (if using)
+- [ ] Placement capping works (if configured)
+- [ ] Memory leaks prevented (events unsubscribed)
+- [ ] Tested on multiple devices and network conditions
+- [ ] Ad doesn't interrupt active gameplay