nccgs 2.1.1 → 3.0.0-rc.2

package/unity-skills/levelplay-unity-integration/references/dependency-resolution.md

@@ -0,0 +1,94 @@
+# LevelPlay Native Dependency Resolution
+
+Detailed guidance for Step 4 of SKILL.md. LevelPlay requires native Android/iOS libraries that Unity's
+package manager alone doesn't handle; a dependency manager bridges this gap. Read this when resolving
+native dependencies, when the user does not yet have a dependency manager, or when diagnosing gradle
+(Android) / CocoaPods (iOS) build failures.
+
+## Contents
+- [Check for an Existing Dependency Manager](#check-for-an-existing-dependency-manager)
+- [If They Have a Dependency Manager](#if-they-have-a-dependency-manager)
+- [If They Don't Have a Dependency Manager](#if-they-dont-have-a-dependency-manager)
+- [Verification](#verification)
+- [Android Custom Main Gradle Template (Older Versions)](#android-custom-main-gradle-template-older-versions)
+- [Android API 33+ Requirement](#android-api-33-requirement)
+
+LevelPlay requires native Android/iOS libraries that Unity's package manager alone doesn't handle. A
+dependency manager bridges this gap. If this is a new project without a dependency manager already set
+up, the steps below cover installing one.
+
+## Check for an Existing Dependency Manager
+
+Ask: "Do you have a dependency manager like Mobile Dependency Resolver (MDR), Unity External Dependency
+Manager (UEDM), or External Dependency Manager for Unity (EDM4U) installed? Check your Assets folder for
+these tools."
+
+**If unsure**: Check Assets folder in Unity for folders named 'Mobile Dependency Resolver', 'External
+Dependency Manager', or 'EDM4U'. If you see any folder with these names, answer 'Yes'. If not, answer 'No'.
+
+## If They Have a Dependency Manager
+
+**For Android:**
+- With newer versions of Mobile Dependency Resolver (shipped with the Ads Mediation package): Dependencies auto-resolve on build (no manual action needed). If unsure, try building first — if it fails, manually resolve via the Android Resolver menu.
+- With older MDR or other managers: Go to Assets > [Your Dependency Manager] > Android Resolver > Resolve
+- Example paths:
+  - MDR: `Assets > Mobile Dependency Resolver > Android Resolver > Resolve`
+  - EDM4U: `Assets > External Dependency Manager > Android Resolver > Resolve`
+- Menu paths may vary depending on dependency manager version. Look for 'Android Resolver' under your dependency manager's menu.
+
+**For iOS:**
+- All dependency managers require manual CocoaPods installation:
+  - MDR: `Assets > Mobile Dependency Resolver > iOS Resolver > Install Cocoapods`
+  - EDM4U: `Assets > External Dependency Manager > iOS Resolver > Install Cocoapods`
+  - UEDM: Similar path under Unity External Dependency Manager
+
+Ask: "Have you run the dependency resolution for your target platform(s)?"
+
+**If targeting both Android and iOS**, complete dependency resolution for both platforms before proceeding.
+
+## If They Don't Have a Dependency Manager
+
+If the user didn't see the Mobile Dependency Resolver prompt during installation (see Step 3), restart
+Unity Editor — the prompt may appear after restart. If it still doesn't appear, they may already have a
+dependency manager installed.
+
+When prompted:
+1. Click **Import** on the prompt to install Mobile Dependency Resolver
+2. After installation:
+   - **Android**: Dependencies will auto-resolve on build (newer MDR versions)
+   - **iOS**: Go to Assets > Mobile Dependency Resolver > iOS Resolver > Install Cocoapods
+
+**Alternative**: Install another dependency manager like EDM4U if preferred (search for installation instructions in their documentation).
+
+**Note**: Unity is transitioning to Unity External Dependency Manager (UEDM). If available in your Unity version, prefer UEDM over MDR.
+
+## Verification
+
+After resolution, verify:
+- **Android**: Gradle dependencies in `Assets/Plugins/Android/`
+- **iOS**: Podfile references or CocoaPods installation confirmation in console
+
+**If dependency resolution fails**: Check the Unity console for specific error messages and share them for troubleshooting — or see `references/troubleshooting.md` for gradle and CocoaPods error guidance.
+
+## Android Custom Main Gradle Template (Older Versions)
+
+For older LevelPlay Unity package versions, manually enable the Custom Main Gradle Template:
+1. Go to Edit > Project Settings > Player
+2. Select Android tab
+3. Expand Publishing Settings
+4. Under Build, check Custom Main Gradle Template
+
+In newer LevelPlay Unity package versions (with newer Mobile Dependency Resolver), this is enabled
+automatically by default.
+
+## Android API 33+ Requirement
+
+If targeting Android API level 33 or higher, declare the AD_ID permission in AndroidManifest.xml:
+
+```xml
+<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
+```
+
+This permission is required for advertising ID access on Android 13+.
+
+**If you skip this step and target Android API 33+:** advertising ID access will fail on Android 13+ devices.

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/ilrd-api.md

@@ -43,7 +43,7 @@ On SDK 9.5.0+, the global `LevelPlay.OnImpressionDataReady` still exists but is
 
 ### SDK 9.5.0+ (current): Per-Instance Setup
 
-Subscribe to `OnAdImpressionDataReady` on each ad object right after you create it, before you load or show it, so no impression is missed — typically inside the ad manager classes from `rewarded-api.md` / `interstitial-api.md` / `banner-api.md`. There is no "before Init" ordering concern with the per-instance event; you subscribe when the ad is created.
+Subscribe to `OnAdImpressionDataReady` on each ad object right after you create it — typically inside the ad manager classes from `rewarded-api.md` / `interstitial-api.md` / `banner-api.md`. There is no "before Init" ordering concern with the per-instance event; you subscribe when the ad is created.
 
 ```csharp
 using UnityEngine;
@@ -239,7 +239,7 @@ private void ImpressionDataReadyEvent(LevelPlayImpressionData impressionData)
 
 ## Thread Safety
 
-**CRITICAL:** the ILRD callback (`OnAdImpressionDataReady` on 9.5.0+, or `OnImpressionDataReady` on 9.4.x and earlier) runs on a background thread. This means:
+**CRITICAL:** `OnImpressionDataReady` runs on a background thread. This means:
 
 **❌ DO NOT:**
 - Call Unity APIs directly (e.g., `GameObject.Find()`, `transform.position`)

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/initialization-api.md

@@ -2,6 +2,8 @@
 
 ## Contents
 - [Overview](#overview)
+- [Code Organization Options (Step 7)](#code-organization-options-step-7)
+- [Version-Aware ILRD Init Wiring (Step 7)](#version-aware-ilrd-init-wiring-step-7)
 - [Basic Initialization](#basic-initialization)
 - [Advanced Initialization](#advanced-initialization)
 - [API Reference](#api-reference)
@@ -15,6 +17,221 @@
 
 Proper SDK initialization is critical for LevelPlay to function correctly. This reference covers basic initialization, advanced options, and best practices.
 
+## Code Organization Options (Step 7)
+
+Step 7 of SKILL.md asks the user how they want to handle initialization and presents four options. Full
+implementation for each option follows. Present the four option labels exactly as written in SKILL.md;
+use the code here once the user has chosen.
+
+### Option 1: Creating a New Script
+
+**If you completed ATT in Step 6.5 (iOS):** Use the `LevelPlayInitializer.cs` from `references/ios-setup.md` (Part 3) instead of the template below — it already includes the `IEnumerator Start()` coroutine required for ATT and the `DontDestroyOnLoad` setup. Skip this code block and continue from the ILRD wiring below.
+
+If creating a new script (e.g., `LevelPlayInitializer.cs`), use this complete class:
+
+```csharp
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class LevelPlayInitializer : MonoBehaviour
+{
+    [SerializeField] private string appKey;
+
+    void Awake()
+    {
+        // Persist across scene loads so ads stay initialized
+        DontDestroyOnLoad(gameObject);
+    }
+
+    void Start()
+    {
+        // Register initialization callbacks
+        LevelPlay.OnInitSuccess += OnInitSuccess;
+        LevelPlay.OnInitFailed += OnInitFailed;
+
+        // Initialize the SDK with your App Key
+        LevelPlay.Init(appKey);
+    }
+
+    private void OnInitSuccess(LevelPlayConfiguration config)
+    {
+        Debug.Log("LevelPlay SDK initialized successfully");
+        // SDK is now ready to load ads
+    }
+
+    private void OnInitFailed(LevelPlayInitError error)
+    {
+        Debug.LogError($"LevelPlay initialization failed: {error.ErrorMessage}");
+    }
+
+    void OnDestroy()
+    {
+        LevelPlay.OnInitSuccess -= OnInitSuccess;
+        LevelPlay.OnInitFailed -= OnInitFailed;
+    }
+}
+```
+
+**File location**: Save as `Assets/Scripts/LevelPlayInitializer.cs` (or `Assets/Scripts/Ads/LevelPlayInitializer.cs` if you have an Ads subfolder)
+
+**After creating:**
+1. Attach script to a GameObject in your first scene
+2. In Unity Inspector, find the "App Key" field
+3. Paste your App Key from Step 5 into that field
+
+### Option 2: Adding to Existing Script
+
+If adding to an existing script (e.g., `GameManager.cs`):
+
+**1. Add namespace at top of file:**
+```csharp
+using Unity.Services.LevelPlay;
+```
+
+**2. In existing Start() or Awake() method, add initialization:**
+```csharp
+void Start()
+{
+    // Register initialization callbacks
+    LevelPlay.OnInitSuccess += OnInitSuccess;
+    LevelPlay.OnInitFailed += OnInitFailed;
+
+    // Initialize the SDK - REPLACE with your actual App Key from Step 5
+    LevelPlay.Init("YOUR_APP_KEY_HERE");
+
+    // ... your other existing Start() code
+}
+```
+
+**3. Add callback methods to class:**
+```csharp
+private void OnInitSuccess(LevelPlayConfiguration config)
+{
+    Debug.Log("LevelPlay SDK initialized successfully");
+    // SDK is ready - you can now create ad objects
+}
+
+private void OnInitFailed(LevelPlayInitError error)
+{
+    Debug.LogError($"LevelPlay initialization failed: {error.ErrorMessage}");
+}
+```
+
+**4. In existing OnDestroy() (or create if it doesn't exist), add:**
+```csharp
+void OnDestroy()
+{
+    // Unregister callbacks
+    LevelPlay.OnInitSuccess -= OnInitSuccess;
+    LevelPlay.OnInitFailed -= OnInitFailed;
+}
+```
+
+Replace `"YOUR_APP_KEY_HERE"` with your actual App Key from Step 5 (the alphanumeric string copied from the LevelPlay dashboard).
+
+**Note:** If your existing script doesn't already persist across scenes, add `DontDestroyOnLoad(gameObject);` to its `Awake()` method to prevent re-initialization when loading new scenes.
+
+Before testing, double-check that you've replaced the placeholder with your actual App Key. The App Key should be an alphanumeric string, NOT 'YOUR_APP_KEY_HERE'.
+
+### Option 3: Separate Script Referenced by Manager
+
+If you want to keep ads code in its own script that your existing manager references:
+
+**1. Create `LevelPlayInitializer.cs` using the complete class code from Option 1.**
+
+**2. Add the `LevelPlayInitializer` component to a GameObject in the Unity Editor** (at design time — not at runtime). Use a dedicated persistent GameObject (e.g. an "Ads" object in your first scene), and set its **App Key** field in the Inspector, exactly as in Option 1's "After creating" steps.
+
+**3. Reference it from your existing manager** via a serialized field, so `GameManager` can coordinate with the initializer without creating it at runtime:
+```csharp
+using UnityEngine;
+
+public class GameManager : MonoBehaviour
+{
+    // Assign the LevelPlayInitializer GameObject in the Inspector.
+    // Enter your App Key on the LevelPlayInitializer component itself (see step 2),
+    // NOT here — that keeps your ad credentials in one place where publishers expect them.
+    [SerializeField] private LevelPlayInitializer levelPlayInitializer;
+
+    void Awake()
+    {
+        // ... your other initialization code.
+        // LevelPlayInitializer initializes itself in its own Start();
+        // GameManager just holds a reference to it via the field above.
+    }
+}
+```
+
+This keeps ad code isolated in `LevelPlayInitializer.cs` while giving `GameManager` a reference to it.
+
+> **Why not `gameObject.AddComponent<LevelPlayInitializer>()` at runtime?** The initializer reads its App Key from a `[SerializeField]` Inspector field. A component added at runtime never receives that Inspector value, so the App Key would be empty and initialization would fail. Attaching the component in the Editor (step 2) is what makes the App Key field available to fill in.
+
+**Note:** `LevelPlayInitializer.Awake()` calls `DontDestroyOnLoad(gameObject)`, so the GameObject you attach it to persists across scenes. Put it on a dedicated Ads GameObject rather than on your `GameManager`, unless you intend `GameManager` to persist too.
+
+### Option 4: Just Show Me the Code
+
+Provide the complete initialization code from Option 1 as a standalone snippet, without instructions for attaching to a GameObject or setting up the Inspector. Include a note: "This is the full initialization class — save it as `LevelPlayInitializer.cs`, attach it to a persistent GameObject in your first scene, and set the App Key field in the Inspector."
+
+**Key points (all options):**
+- Always register `OnInitSuccess` and `OnInitFailed` callbacks before calling `Init()`
+- Call initialization early in app lifecycle (in `Awake()` or `Start()` of first scene)
+- Only initialize once. If initialization script is in first scene and you have multiple scenes, add `DontDestroyOnLoad(gameObject);` in `Awake()` to prevent re-initialization when loading new scenes
+- Wait for `OnInitSuccess` before creating ad objects
+
+If initialization fails repeatedly, see `references/troubleshooting.md`. Common causes include incorrect App Key, no internet connection, or missing package dependencies.
+
+## Version-Aware ILRD Init Wiring (Step 7)
+
+**If the user answered Yes or Not Sure to the ILRD question in Step 7**, wire up the impression-revenue
+callback. **The correct approach depends on the user's SDK version** (check in **Ads Mediation > Network
+Manager**):
+
+**SDK 9.5.0+ (current): do NOT add anything to the initializer here.** In 9.5.0+, ILRD is delivered per
+ad instance via the `OnAdImpressionDataReady` event on each ad object — it is wired when you create each
+ad in Step 9 (see `references/ilrd-api.md`). The global `LevelPlay.OnImpressionDataReady` event still
+exists but is **deprecated in 9.5.0+ and generates a compiler warning** — do not use it on 9.5.0+.
+
+**SDK 9.4.x and earlier:** subscribe to the global `LevelPlay.OnImpressionDataReady` event before
+`LevelPlay.Init()`. Add these lines inside `Start()` (before `LevelPlay.Init(appKey)`):
+
+```csharp
+// SDK 9.4.x and earlier only. MUST be registered BEFORE LevelPlay.Init() to avoid
+// losing early impressions. Callback fires on a BACKGROUND thread — see
+// references/ilrd-api.md for thread-safe forwarding patterns and a Firebase example.
+LevelPlay.OnImpressionDataReady += OnImpressionDataReady;
+```
+
+Add this stub method to the class:
+
+```csharp
+private void OnImpressionDataReady(LevelPlayImpressionData impressionData)
+{
+    // See references/ilrd-api.md for full implementation.
+    // For now, just log so you can verify it fires:
+    Debug.Log($"ILRD: {impressionData.AdNetwork} / {impressionData.AdFormat} / ${impressionData.Revenue}");
+}
+```
+
+And unsubscribe in `OnDestroy()`:
+
+```csharp
+LevelPlay.OnImpressionDataReady -= OnImpressionDataReady;
+```
+
+**iOS path (SDK 9.4.x and earlier only):** if you used the `LevelPlayInitializer.cs` from
+`references/ios-setup.md` Part 3, note that `Start()` is a coroutine with **no `LevelPlay.Init(appKey)`
+call inside it** — initialization happens in `InitializeLevelPlay()`. Place the
+`LevelPlay.OnImpressionDataReady += ...` line inside `InitializeLevelPlay()`, immediately **before**
+`LevelPlay.Init(appKey)`, so it registers before the first impression.
+
+For Option 2 (existing script) and Option 3 (separate script referenced by a manager), apply the same
+version-aware wiring: on 9.4.x and earlier add the global subscription/stub/unsubscribe shown above; on
+9.5.0+ add nothing here (ILRD is wired per ad instance in Step 9). For Option 3, the wiring goes in
+`LevelPlayInitializer.cs`, with no changes in `GameManager`.
+
+**Next:** Once you confirm the log fires after your first ad impression, read `references/ilrd-api.md` to
+wire it up to your actual analytics platform. Note: ILRD callbacks do not fire with mock ads in the
+Unity Editor — you'll need a device build to verify this log fires (see Step 10).
+
 ## Basic Initialization
 
 ### Minimum Required Setup
@@ -569,6 +786,8 @@ IEnumerator InitializeAfterOnboarding()
 
 ## Migration from IronSource.* APIs
 
+> **Full migration guide:** for SDK upgrade paths, per-format ad unit API migration, the migration completeness checklist, Unity Ads migration, and Maven Central build failures, see `references/migration-sdk-9.md`. The summary below covers initialization only.
+
 If you're migrating from deprecated IronSource APIs:
 
 **Old (Deprecated):**
@@ -593,6 +812,8 @@ LevelPlay.Init(appKey);
 
 When ad operations fail, `LevelPlayAdError` contains an `ErrorCode` property with one of these values:
 
+> **Note:** Code **508** is an initialization/mediation-level error, surfaced via `LevelPlayInitError` in the `OnInitFailed` callback — not via a per-ad `LevelPlayAdError` (hence "N/A" in the Ad Formats column). All other codes below are per-ad errors delivered through `LevelPlayAdError` in the ad load/show failure callbacks.
+
 | Code | Ad Formats | Description |
 |------|-----------|-------------|
 | **508** | N/A | Init failure of mediation/Network, Calling Demand Only API in non Demand Only mode, Calling non Demand Only API in Demand Only mode |

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/interstitial-api.md

@@ -38,6 +38,9 @@ public class InterstitialAdManager : MonoBehaviour
         // 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;
@@ -63,8 +66,9 @@ public class InterstitialAdManager : MonoBehaviour
             interstitialAd.OnAdClicked -= OnAdClicked;
             interstitialAd.OnAdClosed -= OnAdClosed;
             interstitialAd.OnAdInfoChanged -= OnAdInfoChanged;
+            // ILRD (9.5.0+): interstitialAd.OnAdImpressionDataReady -= OnImpressionDataReady;
 
-            // Destroy the ad to free its native resources
+            // Free the native ad and its resources when this manager is destroyed
             interstitialAd.DestroyAd();
         }
     }
@@ -88,6 +92,10 @@ public class InterstitialAdManager : MonoBehaviour
         }
     }
 
+    // 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)
     {
@@ -522,7 +530,7 @@ if (LevelPlayInterstitialAd.IsPlacementCapped("level_complete"))
 
 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 the ILRD impression callback (see `references/ilrd-api.md`), which runs on a background thread.
+**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.
@@ -635,7 +643,7 @@ interstitialAd.OnAdInfoChanged += (adInfo) =>
 
 **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 the ILRD impression callback 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.
+**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
 

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/ios-setup.md

@@ -290,42 +290,14 @@ LevelPlay SDK requires certain capabilities to function properly:
 
 ### App Transport Security (ATS) Configuration
 
-To ensure ads load correctly, configure App Transport Security in your Info.plist:
+**No ATS configuration is needed. Leave App Transport Security at its iOS default.** With ATS on, the LevelPlay SDK tells the auction to return secure ads only, so ads load without any `Info.plist` changes.
 
-**Option 1: Allow arbitrary loads (easiest, less secure)**
+**Do not add ATS exceptions for ads:**
+- **Never set `NSAllowsArbitraryLoads` to `true`.** It turns off transport security for every connection the app makes, including its own backend and login traffic, not just ads, and App Review commonly rejects it without a justification. If the user asks for it, explain this and leave ATS at the default.
+- **Don't set `NSAllowsArbitraryLoadsInWebContent` either.** On its own it makes the SDK request insecure ads, which iOS still blocks outside web views.
+- **Don't add `NSExceptionDomains` entries for ad networks.** The SDK doesn't read them.
 
-Add this to your Info.plist:
-```xml
-<key>NSAppTransportSecurity</key>
-<dict>
-    <key>NSAllowsArbitraryLoads</key>
-    <true/>
-</dict>
-```
-
-**Option 2: Allow specific domains (more secure)**
-
-If you prefer to only allow specific ad network domains:
-```xml
-<key>NSAppTransportSecurity</key>
-<dict>
-    <key>NSExceptionDomains</key>
-    <dict>
-        <key>ironsrc.com</key>
-        <dict>
-            <key>NSIncludesSubdomains</key>
-            <true/>
-            <key>NSExceptionAllowsInsecureHTTPLoads</key>
-            <true/>
-        </dict>
-        <!-- Add other ad network domains as needed -->
-    </dict>
-</dict>
-```
-
-**Note:** Most ad networks require HTTP access for legacy ad creatives. Without proper ATS configuration, some ads may fail to load.
-
-**When to configure:** Before building for iOS. This can be done in Unity's PostProcessBuild or manually in Xcode after export.
+**Expected validation warning:** LevelPlay's integration validation reports "App Transport Security settings MISSING" when these keys are absent. That warning is expected with the default configuration. Don't resolve it by adding `NSAllowsArbitraryLoads`.
 
 ### Recommended Xcode Build Settings
 

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/migration-sdk-9.md

@@ -609,7 +609,7 @@ Only after verifying all ads work correctly:
 
 1. **Window > Package Manager** → Packages: In Project → select **Advertisement Legacy** → **Remove**
 
-⚠️ Do not remove until all ad implementations are tested and working.
+⚠ Do not remove until all ad implementations are tested and working.
 
 ---
 

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/privacy-settings.md

@@ -7,7 +7,7 @@
 - [CCPA Compliance](#ccpa-compliance)
 - [COPPA Compliance](#coppa-compliance)
 - [Combined Compliance Example](#combined-compliance-example)
-- [Deprecated APIs (SDK 9.3.0 and Lower)](#deprecated-apis-sdk-930-and-lower)
+- [Deprecated / Legacy APIs](#deprecated--legacy-apis)
 - [Best Practices](#best-practices)
 - [Testing Privacy Settings](#testing-privacy-settings)
 - [Common Issues](#common-issues)
@@ -475,40 +475,25 @@ public class PrivacyComplianceManager : MonoBehaviour
 
 ---
 
-## Deprecated APIs (SDK 9.3.0 and Lower)
+## Deprecated / Legacy APIs
 
-**⚠ These APIs are deprecated. Use the current `LevelPlayPrivacySettings` APIs instead.**
+**⚠ The APIs below are superseded across all supported versions. Use the current `LevelPlayPrivacySettings` APIs shown in the sections above instead.**
 
-### Deprecated GDPR API — LevelPlay.SetConsent
+> **`SetGDPRConsents(Dictionary)` is NOT in this list.** It is the **current GDPR API on SDK 9.4.x** — not a legacy API. It only becomes `[Obsolete]` on SDK 9.5.0+, where `SetGDPRConsent(bool)` replaces it. See [GDPR Consent Management](#gdpr-consent-management) above for the version-appropriate call. Do not treat the per-network dictionary as deprecated if you are on 9.4.x.
 
-```csharp
-// DEPRECATED - Do not use
-LevelPlay.SetConsent(true); // Grants consent for all networks
-LevelPlay.SetConsent(false); // Denies consent for all networks
-```
-
-**Status:** Marked as `[Obsolete]` in SDK code.
-
-**Migration:** Use `LevelPlayPrivacySettings.SetGDPRConsents(Dictionary)` (SDK 9.4.x) or `LevelPlayPrivacySettings.SetGDPRConsent(bool)` (SDK 9.5.0+).
-
-### Deprecated GDPR API — SetGDPRConsents (per-network dictionary, SDK 9.5.0+)
+### Legacy GDPR API — LevelPlay.SetConsent (all versions)
 
 ```csharp
-// DEPRECATED as of SDK 9.5.0+ — generates compiler warning
-// NOTE: This is the CORRECT API for SDK 9.4.x. Only deprecated from 9.5.0 onwards.
-Dictionary<string, bool> consents = new Dictionary<string, bool>
-{
-    { "UnityAds", true },
-    { "AdMob", true }
-};
-LevelPlayPrivacySettings.SetGDPRConsents(consents);
+// DEPRECATED - Do not use. Marked [Obsolete] in the SDK.
+LevelPlay.SetConsent(true);  // Grants consent for all networks
+LevelPlay.SetConsent(false); // Denies consent for all networks
 ```
 
-**Note:** `SetGDPRConsents(Dictionary)` is the correct API for SDK 9.4.x. It becomes deprecated only in SDK 9.5.0+, where it is replaced by `SetGDPRConsent(bool)`. If you are on 9.5.0+, migrate to the boolean API.
+**Status:** Marked as `[Obsolete]` in SDK code (all supported versions).
 
-**Migration (9.5.0+ only):** Use `LevelPlayPrivacySettings.SetGDPRConsent(true/false)` instead.
+**Migration:** Use `LevelPlayPrivacySettings.SetGDPRConsents(Dictionary)` on SDK 9.4.x, or `LevelPlayPrivacySettings.SetGDPRConsent(bool)` on SDK 9.5.0+.
 
-### Deprecated CCPA API
+### Legacy CCPA API
 
 ```csharp
 // DEPRECATED - Do not use
@@ -518,7 +503,7 @@ LevelPlay.SetMetaData("do_not_sell", "false");
 
 **Migration:** Use `LevelPlayPrivacySettings.SetCCPA(true)` instead.
 
-### Deprecated COPPA API
+### Legacy COPPA API
 
 ```csharp
 // DEPRECATED - Do not use
@@ -593,9 +578,9 @@ private void OnInitSuccess(LevelPlayConfiguration config)
 
 ### Issue: Using deprecated APIs
 
-**Cause:** Following outdated documentation or examples using `LevelPlay.SetConsent()` or `SetGDPRConsents(Dictionary)`
+**Cause:** Following outdated documentation or examples using the legacy `LevelPlay.SetConsent()` or `LevelPlay.SetMetaData("do_not_sell"/"is_child_directed", ...)` privacy calls.
 
-**Solution:** Migrate to current APIs — use `LevelPlayPrivacySettings.SetGDPRConsent(bool)` for GDPR
+**Solution:** Use the `LevelPlayPrivacySettings` API appropriate to your SDK version — for GDPR, `SetGDPRConsents(Dictionary)` on SDK 9.4.x, or `SetGDPRConsent(bool)` on SDK 9.5.0+. (Note: `SetGDPRConsents(Dictionary)` is current on 9.4.x and only warns as obsolete on 9.5.0+ — it is not a legacy API on 9.4.x.)
 
 ---
 

package/{.claude/skills → unity-skills}/levelplay-unity-integration/references/rewarded-api.md

@@ -33,6 +33,10 @@ public class RewardedAdManager : MonoBehaviour
     private LevelPlayRewardedAd rewardedAd;
     private string adUnitId = "YOUR_REWARDED_AD_UNIT_ID";
 
+    // Optional: assign a handler to be notified when the user earns the reward.
+    // Callers (e.g. a HintSystem) set this before calling ShowAd().
+    public System.Action OnRewardGranted;
+
     void Start()
     {
         // Create the rewarded ad object and register event listeners.
@@ -41,6 +45,9 @@ public class RewardedAdManager : MonoBehaviour
         // should be available). See LoadAd() below.
         rewardedAd = new LevelPlayRewardedAd(adUnitId);
 
+        // ILRD (SDK 9.5.0+): if impression-revenue tracking is enabled, also subscribe here —
+        //   rewardedAd.OnAdImpressionDataReady += OnImpressionDataReady;   // see references/ilrd-api.md
+
         // Register event listeners
         rewardedAd.OnAdLoaded += OnAdLoaded;
         rewardedAd.OnAdLoadFailed += OnAdLoadFailed;
@@ -65,11 +72,14 @@ public class RewardedAdManager : MonoBehaviour
             rewardedAd.OnAdClosed -= OnAdClosed;
             rewardedAd.OnAdClicked -= OnAdClicked;
             rewardedAd.OnAdInfoChanged -= OnAdInfoChanged;
+            // ILRD (9.5.0+): rewardedAd.OnAdImpressionDataReady -= OnImpressionDataReady;
         }
     }
 
-    // Call LoadAd() from a publisher-controlled trigger (e.g. a button or scene entry).
-    // The SDK does not auto-load, so LoadAd() must be called explicitly.
+    // Call this from the trigger point in your game where you want the ad to be available —
+    // for example, from a UI button handler, on entering a scene, or at a natural moment
+    // in gameplay. Unlike the legacy IronSource rewarded video, the SDK does not load
+    // automatically; LoadAd() must always be called explicitly.
     public void LoadAd()
     {
         Debug.Log("Loading rewarded ad...");
@@ -89,6 +99,10 @@ public class RewardedAdManager : MonoBehaviour
         }
     }
 
+    // True once a rewarded ad has finished loading and can be shown.
+    // Use this to decide whether to offer the ad before calling ShowAd().
+    public bool IsAdReady() => rewardedAd != null && rewardedAd.IsAdReady();
+
     // Event Callbacks
     private void OnAdLoaded(LevelPlayAdInfo adInfo)
     {
@@ -119,6 +133,8 @@ public class RewardedAdManager : MonoBehaviour
         Debug.Log($"User earned reward: {reward.Amount} {reward.Name}");
         // Grant the reward to the user
         GrantReward(reward);
+        // Notify any external listener (e.g. HintSystem) that the reward was earned
+        OnRewardGranted?.Invoke();
     }
 
     private void OnAdClosed(LevelPlayAdInfo adInfo)
@@ -469,7 +485,7 @@ if (LevelPlayRewardedAd.IsPlacementCapped("extra_lives"))
 
 All events are properties of the `LevelPlayRewardedAd` 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 the ILRD impression callback (see `references/ilrd-api.md`), which runs on a background thread.
+**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 a rewarded ad is successfully loaded.
@@ -603,7 +619,7 @@ rewardedAd.OnAdInfoChanged += (adInfo) =>
 
 **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 the ILRD impression callback 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.
+**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