nccgs 1.0.0

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

@@ -0,0 +1,337 @@
+# Impression Level Revenue (ILR) Integration
+
+## Contents
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Key Characteristics](#key-characteristics)
+- [Implementation](#implementation)
+- [API Reference](#api-reference)
+- [Thread Safety](#thread-safety)
+- [Integration with Third-Party Analytics](#integration-with-third-party-analytics)
+- [Best Practices](#best-practices)
+- [Common Issues](#common-issues)
+- [Testing Checklist](#testing-checklist)
+
+## Overview
+
+Use the Impression Level Revenue (ILR) solution to track ad revenue at both device and impression levels, integrating with third-party analytics tools for deeper insights.
+
+## Prerequisites
+
+- LevelPlay SDK 7.0.3+ correctly integrated
+- Refer to Unity Package integration guide
+
+For more information about the Impression Level Revenue (ILR) SDK feature and pre-requisites, refer to the Impression-level revenue server-side API documentation.
+
+## Key Characteristics
+
+- **Real-time data**: Fires postbacks to inform you about displayed ads
+- **Background thread**: Callback runs on a background thread, not the Unity main thread
+- **Optional listener**: Provides information about all ad units
+- **All ad formats**: Works with Rewarded, Interstitial, and Banner ads
+
+## Implementation
+
+ILRD is delivered differently depending on your SDK version. Check your version in **Ads Mediation > Network Manager**.
+
+| SDK version | ILRD delivery | Where you subscribe |
+|-------------|---------------|---------------------|
+| **9.5.0+ (current)** | Per ad instance — `OnAdImpressionDataReady` on each ad object (`LevelPlayRewardedAd`, `LevelPlayInterstitialAd`, `LevelPlayBannerAd`) | When you create each ad |
+| **9.4.x and earlier** | Single global event — `LevelPlay.OnImpressionDataReady` | Once, before `LevelPlay.Init()` |
+
+On SDK 9.5.0+, the global `LevelPlay.OnImpressionDataReady` still exists but is **deprecated and generates a compiler warning** — use the per-instance `OnAdImpressionDataReady` event instead.
+
+### 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.
+
+```csharp
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class RewardedAdManager : MonoBehaviour
+{
+    private LevelPlayRewardedAd rewardedAd;
+    private string adUnitId = "YOUR_REWARDED_AD_UNIT_ID";
+
+    void Start()
+    {
+        rewardedAd = new LevelPlayRewardedAd(adUnitId);
+
+        // ILRD (SDK 9.5.0+): subscribe per ad instance.
+        // Fires on a BACKGROUND thread — do not call Unity APIs directly here.
+        rewardedAd.OnAdImpressionDataReady += OnImpressionDataReady;
+
+        // ... register other event listeners and call LoadAd() as usual
+    }
+
+    void OnDestroy()
+    {
+        if (rewardedAd != null)
+        {
+            rewardedAd.OnAdImpressionDataReady -= OnImpressionDataReady;
+            // ... unsubscribe other events
+        }
+    }
+
+    private void OnImpressionDataReady(LevelPlayImpressionData impressionData)
+    {
+        // Runs on a background thread — see "Integration with Third-Party Analytics".
+        if (impressionData == null) return;
+        Debug.Log($"ILRD - {impressionData.AdNetwork} / {impressionData.AdFormat} / ${impressionData.Revenue}");
+    }
+}
+```
+
+Repeat the same `OnAdImpressionDataReady` subscription on your interstitial and banner ad objects. Every ad format reports its own impressions through its own instance event.
+
+### SDK 9.4.x and earlier (legacy): Global Event Setup
+
+On older SDKs, use the single global `LevelPlay.OnImpressionDataReady` event, registered **before** `LevelPlay.Init()`:
+
+```csharp
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class ImpressionRevenueManager : MonoBehaviour
+{
+    void Start()
+    {
+        // Register impression data callback BEFORE SDK initialization
+        // This event is triggered on a background thread, not the Unity main thread.
+        LevelPlay.OnImpressionDataReady += ImpressionDataReadyEvent;
+
+        // Register initialization callbacks
+        LevelPlay.OnInitSuccess += OnInitSuccess;
+        LevelPlay.OnInitFailed += OnInitFailed;
+
+        // Initialize SDK
+        LevelPlay.Init("YOUR_APP_KEY");
+    }
+
+    void OnDestroy()
+    {
+        // Unregister callbacks
+        LevelPlay.OnImpressionDataReady -= ImpressionDataReadyEvent;
+        LevelPlay.OnInitSuccess -= OnInitSuccess;
+        LevelPlay.OnInitFailed -= OnInitFailed;
+    }
+
+    private void ImpressionDataReadyEvent(LevelPlayImpressionData impressionData)
+    {
+        // IMPORTANT: This runs on a background thread, not the main thread
+        // Do not call Unity APIs directly from here
+        Debug.Log($"ILR - Ad Network: {impressionData.AdNetwork}");
+        Debug.Log($"ILR - Revenue: ${impressionData.Revenue}");
+    }
+
+    private void OnInitSuccess(LevelPlayConfiguration config)
+    {
+        Debug.Log("LevelPlay initialized");
+    }
+
+    private void OnInitFailed(LevelPlayInitError error)
+    {
+        Debug.LogError($"Init failed: {error.ErrorMessage}");
+    }
+}
+```
+
+**Key points (global event — SDK 9.4.x and earlier only):**
+- Declare the listener **BEFORE** initializing the LevelPlay SDK to avoid any loss of information
+- Callback runs on a **background thread**
+- Don't call Unity APIs directly in the callback
+- On SDK 9.5.0+ this global event is deprecated — use the per-instance `OnAdImpressionDataReady` shown above instead
+
+### Accessing Impression Data
+
+You can refer to each field separately or get all information by using the AllData property:
+
+```csharp
+private void ImpressionDataReadyEvent(LevelPlayImpressionData impressionData)
+{
+    string allData = impressionData.AllData;
+    string adNetwork = impressionData.AdNetwork;
+    double? revenue = impressionData.Revenue;
+}
+```
+
+**Important:** The returned data might include null values. To avoid potential crashes, ensure that you add protections before assigning the data.
+
+## API Reference
+
+### Events
+
+#### `adObject.OnAdImpressionDataReady` (SDK 9.5.0+ — current)
+
+Per-instance event on each ad object (`LevelPlayRewardedAd`, `LevelPlayInterstitialAd`, `LevelPlayBannerAd`). Fired when that ad reports an impression with revenue data.
+
+**Signature:** `event Action<LevelPlayImpressionData>`
+
+**Usage:**
+```csharp
+// Subscribe after creating the ad object. Fires on a background thread.
+rewardedAd.OnAdImpressionDataReady += ImpressionDataReadyEvent;
+```
+
+**Important:**
+- Subscribe when you create the ad object; unsubscribe in `OnDestroy()`
+- Callback runs on **background thread**
+- Each ad format reports through its own instance event
+
+#### `LevelPlay.OnImpressionDataReady` (SDK 9.4.x and earlier — deprecated in 9.5.0+)
+
+Single global event. Fired when any impression occurs and revenue data is available.
+
+**Signature:** `static event Action<LevelPlayImpressionData>`
+
+**Usage:**
+```csharp
+// This event is triggered on a background thread, not the Unity main thread.
+LevelPlay.OnImpressionDataReady += ImpressionDataReadyEvent;
+```
+
+**Important:**
+- Register **BEFORE** `LevelPlay.Init()`
+- Callback runs on **background thread**
+- Fires for all ad formats (Rewarded, Interstitial, Banner)
+- **Deprecated in SDK 9.5.0+** (generates a compiler warning) — use the per-instance event above instead
+
+### Data Type
+
+#### `LevelPlayImpressionData`
+
+Contains detailed information about an ad impression.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `AllData` | string/dictionary | All impression data as a structured object |
+| `AuctionId` | string | Unique auction identifier |
+| `MediationAdUnitName` | string | Mediation ad unit name |
+| `MediationAdUnitId` | string | Mediation ad unit identifier |
+| `AdFormat` | string | Ad format (e.g., "REWARDED", "INTERSTITIAL", "BANNER") |
+| `AdNetwork` | string | Ad network that served the ad |
+| `InstanceName` | string | Ad network instance name |
+| `InstanceId` | string | Ad network instance identifier |
+| `Country` | string | User's country code |
+| `Placement` | string | Placement name where ad was shown |
+| `Revenue` | double? | Estimated revenue in USD (nullable - check for null) |
+| `Precision` | string | Revenue precision level |
+| `Ab` | string | A/B test segment identifier |
+| `SegmentName` | string | User segment name |
+| `EncryptedCpm` | string | Encrypted CPM value |
+| `ConversionValue` | number? | iOS SKAdNetwork conversion value (iOS only) |
+| `CreativeId` | string | Creative identifier |
+
+**Example:**
+```csharp
+private void ImpressionDataReadyEvent(LevelPlayImpressionData impressionData)
+{
+    string allData = impressionData.AllData;
+    string adNetwork = impressionData.AdNetwork;
+    double? revenue = impressionData.Revenue;
+}
+```
+
+**Note:** For the full list of available ILR data, including field description and types, refer to Impression-level revenue server-side API documentation.
+
+## 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:
+
+**❌ DO NOT:**
+- Call Unity APIs directly (e.g., `GameObject.Find()`, `transform.position`)
+- Access Unity components or game objects
+- Update UI elements directly
+- Call coroutines
+
+**✅ DO:**
+- Queue data for processing on main thread
+- Use thread-safe operations
+- Check for null values before using data
+
+## Integration with Third-Party Analytics
+
+### Firebase Analytics Example
+
+The following example details how to integrate the Impression Level Revenue SDK API data with Google Analytics for Firebase. You can use it as-is or make any required changes to integrate with third-party reporting tools or your own proprietary optimization tools and databases.
+
+**Important:** Ensure that the inside parameters aren't null.
+
+```csharp
+private void ImpressionDataReadyEvent(LevelPlayImpressionData impressionData)
+{
+    Debug.Log("unity-script: ImpressionDataReadyEvent impressionData = " + impressionData);
+
+    if (impressionData != null)
+    {
+        Firebase.Analytics.Parameter[] AdParameters = {
+            new Firebase.Analytics.Parameter("ad_platform", "LevelPlay"),
+            new Firebase.Analytics.Parameter("ad_source", impressionData.AdNetwork),
+            new Firebase.Analytics.Parameter("ad_format", impressionData.AdFormat),
+            new Firebase.Analytics.Parameter("ad_unit_name", impressionData.InstanceName),
+            new Firebase.Analytics.Parameter("currency", "USD"),
+            new Firebase.Analytics.Parameter("value", impressionData.Revenue ?? 0) // Add protection for null values
+        };
+
+        Firebase.Analytics.FirebaseAnalytics.LogEvent("custom_ad_impression", AdParameters);
+    }
+}
+```
+
+### Integration with Other Tools
+
+After you implement the ImpressionDataListener, you can send the impression data to:
+- Your own proprietary BI tools and data warehouses
+- Third-party analytics platforms
+- Attribution providers
+- Custom backend services
+
+## Best Practices
+
+1. **Subscribe correctly for your SDK version**: On SDK 9.5.0+, subscribe to each ad's `OnAdImpressionDataReady` when you create the ad. On SDK 9.4.x and earlier, register the global `LevelPlay.OnImpressionDataReady` before calling `LevelPlay.Init()`
+2. **Handle background thread**: Don't call Unity APIs directly in the callback
+3. **Check for null values**: Revenue and other properties may be null - always check before using
+4. **Protect against crashes**: Add null checks to avoid potential crashes
+5. **Unregister on destroy**: Prevent memory leaks by unregistering in `OnDestroy()`
+
+## Common Issues
+
+### Issue: Callback never fires
+
+**Possible causes:**
+- **SDK 9.5.0+:** not subscribed to the ad instance's `OnAdImpressionDataReady`, or subscribed to a different ad object than the one shown
+- **SDK 9.4.x and earlier:** global `LevelPlay.OnImpressionDataReady` not registered before `LevelPlay.Init()`
+- SDK not initialized successfully
+- No ads shown yet
+
+**Solutions:**
+- On 9.5.0+, subscribe to `OnAdImpressionDataReady` on the same ad object you load/show
+- On 9.4.x and earlier, register the global callback before calling `Init()`
+- Verify `OnInitSuccess` fires
+- Show an ad and check if callback fires
+
+### Issue: Unity APIs crash in callback
+
+**Cause:** Calling Unity APIs from background thread
+
+**Solution:** Don't call Unity APIs directly in the callback. Queue data for main thread processing if needed.
+
+### Issue: Revenue is null
+
+**Cause:** Some ad networks don't provide revenue data
+
+**Solution:** Always check `impressionData.Revenue.HasValue` or use `impressionData.Revenue ?? 0` to provide a default value
+
+## Testing Checklist
+
+- [ ] Subscribed correctly for your SDK version (9.5.0+: per-instance `OnAdImpressionDataReady`; 9.4.x and earlier: global `OnImpressionDataReady` before `Init()`)
+- [ ] Callback fires when ads are shown
+- [ ] Revenue data is received (check for null)
+- [ ] Null checks added to prevent crashes
+- [ ] Analytics/backend integration works correctly
+- [ ] No crashes from Unity API calls in callback
+- [ ] Callback unregistered in `OnDestroy()`
+- [ ] Tested with all ad formats (Rewarded, Interstitial, Banner)