@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/levelplay-unity-integration/references/best-practices.md

@@ -0,0 +1,604 @@
+# LevelPlay Ad Unit Implementation Best Practices
+
+## Contents
+- [Overview](#overview)
+- [Strategic Framework: Revenue vs UX Optimization](#strategic-framework-revenue-vs-ux-optimization)
+- [Ad Format Strategy by Goal](#ad-format-strategy-by-goal)
+- [Placement Strategy](#placement-strategy)
+- [Implementation Patterns](#implementation-patterns)
+- [Frequency Management](#frequency-management)
+- [Error Handling and Graceful Degradation](#error-handling-and-graceful-degradation)
+- [A/B Testing Considerations](#ab-testing-considerations)
+- [Common Mistakes to Avoid](#common-mistakes-to-avoid)
+- [Platform-Specific Considerations](#platform-specific-considerations)
+- [Success Metrics by Strategy](#success-metrics-by-strategy)
+- [Final Recommendations](#final-recommendations)
+- [Code Generation Guidelines (Step 9)](#code-generation-guidelines-step-9)
+
+## Overview
+
+This reference compiles best practices from the LevelPlay enablement playbook, covering strategy selection, placement optimization, and common implementation patterns that drive both revenue and user satisfaction.
+
+## Strategic Framework: Revenue vs UX Optimization
+
+### Understanding the Trade-off
+
+Every ad implementation involves a fundamental trade-off between revenue generation and user experience. Your optimization goal should guide every decision.
+
+| Optimization Goal | Philosophy | Typical Outcome |
+|-------------------|------------|-----------------|
+| **Revenue-Focused** | Maximize impression opportunities | Higher revenue, potential UX impact |
+| **UX-Focused** | Protect user experience at all costs | Better retention, lower short-term revenue |
+| **Balanced** | Optimize for sustainable long-term value | Moderate revenue with good UX |
+
+### Choosing Your Optimization Goal
+
+**Ask yourself:**
+1. What stage is your app in? (Early = UX focus, Mature = revenue optimization)
+2. What's your business model? (Ads-only = revenue, Hybrid = balanced)
+3. What's your competitive landscape? (High competition = UX focus)
+4. What are your user expectations? (Casual games = more ads tolerated)
+
+## Ad Format Strategy by Goal
+
+### Revenue-Focused Implementation
+
+**Goal**: Maximize ad revenue and impression opportunities
+
+**Rewarded Ads** (Primary):
+- Implement 3-5 placements across high-value moments
+- Examples: Hints, extra lives, power-ups, bonus currency, skip levels
+- Always keep a rewarded ad loaded and ready
+- Reload immediately after showing
+
+**Interstitial Ads** (Secondary):
+- Show at every natural transition point
+- Frequency cap: Every 3-5 minutes of active gameplay
+- Placements: Level complete, game over, returning to menu
+- Load proactively before transitions
+
+**Banner Ads** (Tertiary):
+- Show persistently during gameplay
+- Position: Bottom (less intrusive than top)
+- Keep loaded throughout session for continuous impressions
+- Accept some visual clutter for revenue
+
+**Expected Outcomes:** *(Industry benchmarks, not LevelPlay-specific)*
+- ✅ 30-50% higher ad revenue
+- ⚠ 5-15% increase in early abandonment
+- ⚠ Lower user satisfaction scores
+- ✅ Strong monetization from engaged users
+
+### UX-Focused Implementation
+
+**Goal**: Maintain excellent user experience while monetizing thoughtfully
+
+**Rewarded Ads** (Only or Primary):
+- Single placement or 2 maximum
+- User-initiated only (player chooses to watch)
+- High-value rewards that feel generous
+- Never force ads
+
+**Interstitial Ads** (Optional, Rare):
+- Only at major session boundaries (returning to menu, closing app)
+- Frequency cap: 10+ minutes or once per session
+- Skip during active gameplay entirely
+
+**Banner Ads** (Avoid or Minimize):
+- Show only in menus, never during gameplay
+- If used, small sizes (standard 320x50, not rectangles)
+- Hide during any active user engagement
+
+**Expected Outcomes:** *(Industry benchmarks, not LevelPlay-specific)*
+- ⚠ 40-60% lower ad revenue vs revenue-focused
+- ✅ Better user retention and satisfaction
+- ✅ Higher organic growth and word-of-mouth
+- ✅ Premium brand perception
+
+### Balanced Implementation (Recommended for Most Apps)
+
+**Goal**: Sustainable monetization with good user experience
+
+**Rewarded Ads** (Primary):
+- 2-3 well-chosen placements
+- Focus on moments of high user engagement
+- Make rewards feel valuable but not exploitative
+- Examples: Extra attempts, time skips, premium currency
+
+**Interstitial Ads** (Moderate):
+- Natural transition points only (level complete, game over)
+- Frequency cap: Every 5-7 minutes
+- Never interrupt active gameplay
+- Respect user flow
+
+**Banner Ads** (Selective):
+- Show in menus and low-attention moments
+- Hide during intense or immersive gameplay
+- Position at bottom with proper UI offset
+- Rotation: Show/hide based on context
+
+**Expected Outcomes:** *(Industry benchmarks, not LevelPlay-specific)*
+- ✅ Strong ad revenue (70-85% of revenue-focused approach)
+- ✅ Good user retention
+- ✅ Sustainable long-term monetization
+- ✅ Positive user sentiment
+
+## Placement Strategy
+
+### Identifying Strong Placement Moments
+
+**High-value moments** (Best for rewarded ads):
+- Post-victory celebrations
+- Level progression milestones
+- Unlock opportunities
+- User feels positive emotion
+
+**Natural transitions** (Good for interstitials):
+- Level complete
+- Game over
+- Returning to main menu
+- Session boundaries
+
+**Low-attention periods** (Acceptable for banners):
+- Waiting screens
+- Loading periods
+- Menu browsing
+- Non-interactive moments
+
+### Placement Anti-Patterns (Avoid These)
+
+❌ **Mid-gameplay interruptions**: Never show interstitials during active play
+❌ **Bait-and-switch**: Don't offer rewards then show unrewarded interstitials
+❌ **Excessive frequency**: Showing ads every 1-2 minutes frustrates users
+❌ **Punitive ads**: Using ads as punishment for failure feels manipulative
+❌ **Blocking progression**: Making ads mandatory to continue playing
+❌ **Poor timing**: Showing ads right before key moments or cliffhangers
+
+## Implementation Patterns
+
+> **Note:** These patterns build on the manager classes defined in `rewarded-api.md` and `interstitial-api.md` (`RewardedAdManager`, `InterstitialAdManager`). They use only those managers' public members — `LoadAd()`, `ShowAd()`, `IsAdReady()`, and (for rewarded) the `OnRewardGranted` hook. Generate the manager classes from those references first so these examples compile.
+
+### Pattern 1: Rewarded Hints System
+
+**Use case**: Puzzle or strategy games where hints add value
+
+```csharp
+public class HintSystem : MonoBehaviour
+{
+    [SerializeField] private RewardedAdManager adManager;
+    [SerializeField] private int hintsAvailable = 3;
+
+    public void RequestHint()
+    {
+        if (hintsAvailable > 0)
+        {
+            // User has free hints remaining
+            UseHint();
+            hintsAvailable--;
+        }
+        else
+        {
+            // Offer ad-based hint
+            if (adManager.IsAdReady())
+            {
+                ShowHintAdOffer();
+            }
+            else
+            {
+                ShowHintNotAvailableMessage();
+            }
+        }
+    }
+
+    private void ShowHintAdOffer()
+    {
+        // Show dialog: "Watch an ad to get a hint?"
+        // If user accepts, subscribe to the reward hook and show the ad.
+        adManager.OnRewardGranted = OnHintAdRewardEarned;
+        adManager.ShowAd();
+    }
+
+    private void OnHintAdRewardEarned()
+    {
+        // RewardedAdManager invokes this only after the user earns the reward
+        UseHint();
+    }
+
+    private void UseHint()
+    {
+        // Show hint to player
+        Debug.Log("Showing hint");
+    }
+
+    private void ShowHintNotAvailableMessage()
+    {
+        // Inform user that hints aren't available right now
+        Debug.Log("Hints not available at the moment");
+    }
+}
+```
+
+**Why this works:**
+- User has free hints first (generous)
+- Ad is optional, not forced
+- Clear value exchange (ad for hint)
+- Graceful handling when ads unavailable
+
+### Pattern 2: Level Transition Interstitial (Frequency Capped)
+
+**Use case**: Showing interstitials between levels without annoying users
+
+```csharp
+public class LevelTransitionAds : MonoBehaviour
+{
+    [SerializeField] private InterstitialAdManager adManager;
+    private int levelsCompletedSinceAd = 0;
+    private int levelsRequiredBetweenAds = 3; // Show ad every 3 levels
+
+    public void OnLevelComplete()
+    {
+        levelsCompletedSinceAd++;
+
+        if (levelsCompletedSinceAd >= levelsRequiredBetweenAds)
+        {
+            ShowInterstitialOpportunistically();
+            levelsCompletedSinceAd = 0;
+        }
+
+        ProceedToNextLevel();
+    }
+
+    private void ShowInterstitialOpportunistically()
+    {
+        // Try to show, but don't wait if not ready
+        if (adManager.IsAdReady())
+        {
+            adManager.ShowAd();
+        }
+    }
+
+    private void ProceedToNextLevel()
+    {
+        // Load next level regardless of ad status
+        // Never block user flow waiting for ads
+    }
+}
+```
+
+**Why this works:**
+- Frequency capping prevents ad fatigue
+- Opportunistic showing (doesn't block if not ready)
+- User flow never interrupted
+- Predictable pattern users can adapt to
+
+### Pattern 3: Context-Aware Banner Management
+
+**Use case**: Showing banners in menus but hiding during gameplay
+
+```csharp
+public class ContextAwareBanners : MonoBehaviour
+{
+    [SerializeField] private BannerAdManager bannerManager;
+
+    public enum AppContext
+    {
+        MainMenu,
+        Playing,
+        Paused,
+        GameOver
+    }
+
+    private AppContext currentContext;
+
+    public void SetContext(AppContext newContext)
+    {
+        currentContext = newContext;
+        UpdateBannerVisibility();
+    }
+
+    private void UpdateBannerVisibility()
+    {
+        switch (currentContext)
+        {
+            case AppContext.MainMenu:
+            case AppContext.GameOver:
+                // Show banners in menu contexts
+                bannerManager.ShowBanner();
+                break;
+
+            case AppContext.Playing:
+                // Hide during active gameplay
+                bannerManager.HideBanner();
+                break;
+
+            case AppContext.Paused:
+                // Optional: Show or hide based on your preference
+                // For UX-focused: Hide
+                // For revenue-focused: Show
+                bannerManager.ShowBanner();
+                break;
+        }
+    }
+}
+```
+
+**Why this works:**
+- Banners shown only in appropriate contexts
+- Gameplay experience uninterrupted
+- Easy to adjust strategy by changing visibility logic
+- Clean separation of concerns
+
+## Frequency Management
+
+### Time-Based Frequency Capping
+
+Implement minimum time intervals between ads:
+
+```csharp
+public class FrequencyManager : MonoBehaviour
+{
+    private float minSecondsBetweenInterstitials = 300f; // 5 minutes
+    private float lastInterstitialTime = -300f; // Allow first ad immediately
+
+    public bool CanShowInterstitial()
+    {
+        float timeSinceLast = Time.realtimeSinceStartup - lastInterstitialTime;
+        return timeSinceLast >= minSecondsBetweenInterstitials;
+    }
+
+    public void RecordInterstitialShown()
+    {
+        lastInterstitialTime = Time.realtimeSinceStartup;
+    }
+}
+```
+
+**Recommended intervals:**
+- Revenue-focused: 3-5 minutes
+- Balanced: 5-7 minutes
+- UX-focused: 10+ minutes
+
+### Count-Based Frequency Capping
+
+Implement minimum actions between ads:
+
+```csharp
+private int actionsRequiredBetweenAds = 3;
+private int actionsSinceLastAd = 0;
+
+public void OnUserAction()
+{
+    actionsSinceLastAd++;
+
+    if (actionsSinceLastAd >= actionsRequiredBetweenAds)
+    {
+        // Eligible to show ad
+        TryShowAd();
+        actionsSinceLastAd = 0;
+    }
+}
+```
+
+**Examples of "actions":**
+- Levels completed
+- Games played
+- Sessions started
+- Feature uses
+
+## Error Handling and Graceful Degradation
+
+### Always Have a Fallback
+
+Never let ad failures block user flow:
+
+```csharp
+public void OnAdLoadFailed()
+{
+    // Log for debugging
+    Debug.LogWarning("Ad failed to load");
+
+    // Continue with user flow
+    ProceedWithoutAd();
+
+    // Schedule retry
+    Invoke(nameof(RetryLoadAd), 30f);
+}
+
+private void ProceedWithoutAd()
+{
+    // Your app continues normally
+    // Never block users because ads aren't available
+}
+```
+
+### Reward Users Even When Ads Fail
+
+For rewarded ads, consider granting rewards even if ad fails:
+
+```csharp
+public void OnRewardedAdShowFailed()
+{
+    // User intended to watch ad, but it failed
+    // Consider granting reward anyway (generous approach)
+    if (shouldBeGenerousOnFailure)
+    {
+        GrantReward();
+        ShowMessage("Reward granted! (Ad unavailable)");
+    }
+    else
+    {
+        ShowMessage("Ad unavailable, please try again later");
+    }
+}
+```
+
+**When to be generous:**
+- UX-focused strategy
+- High-value users
+- Failure is on your end (not user's fault)
+
+## A/B Testing Considerations
+
+### What to Test
+
+**High-impact variables:**
+1. **Frequency caps**: 3min vs 5min vs 7min between interstitials
+2. **Placement timing**: Immediate vs delayed interstitials
+3. **Reward generosity**: 1x vs 2x multiplier for rewarded ads
+4. **Banner visibility**: Always vs context-aware vs never during gameplay
+5. **Interstitial presence**: With vs without interstitials
+
+**How to test:**
+- Split users into cohorts
+- Track both revenue AND retention
+- Run tests for 7-14 days minimum
+- Focus on long-term value (LTV), not just day-1 revenue
+
+### Metrics to Track
+
+**Revenue metrics:**
+- ARPDAU (Average Revenue Per Daily Active User)
+- Impression per DAU
+- eCPM (effective Cost Per Mille)
+
+**UX metrics:**
+- D1, D7, D30 retention
+- Session length
+- Session frequency
+- Organic virality (shares, referrals)
+
+**Balance metrics:**
+- LTV (Lifetime Value)
+- ARPU / Retention ratio
+- User satisfaction scores
+
+## Common Mistakes to Avoid
+
+1. **Over-monetizing early**: Don't show tons of ads before users are engaged
+2. **Ignoring retention**: High revenue means nothing if users quit
+3. **Blocking without ads**: Never require watching ads to progress
+4. **Poor frequency capping**: Ads every minute frustrate users
+5. **Forcing rewarded ads**: Rewarded ads should always be optional
+6. **Ignoring load failures**: Always handle ad failures gracefully
+7. **One-size-fits-all**: Different user segments may need different strategies
+8. **Neglecting testing**: Always A/B test major monetization changes
+
+## Platform-Specific Considerations
+
+### iOS
+- Lower opt-in rates post-ATT (iOS 14.5+)
+- Users who deny tracking see lower-value ads
+- More privacy-conscious user base
+- Consider more UX-focused approach
+
+### Android
+- Higher ad fill rates
+- More permissive user expectations
+- Diverse hardware requires testing
+- Can push frequency slightly higher
+
+## Success Metrics by Strategy
+
+*(Example benchmarks from industry typical ranges, not LevelPlay-specific targets)*
+
+### Revenue-Focused Success
+- ARPDAU > $0.15
+- Impression/DAU > 8
+- D7 retention > 20%
+
+### UX-Focused Success
+- D7 retention > 35%
+- Session length > 15 minutes
+- Low uninstall rate (<5% weekly)
+- ARPDAU > $0.05
+
+### Balanced Success
+- ARPDAU > $0.10
+- D7 retention > 28%
+- Impression/DAU > 5
+- High user satisfaction
+
+## Final Recommendations
+
+1. **Start UX-focused**: Better to under-monetize early than drive users away
+2. **Increase gradually**: Add monetization as users become engaged
+3. **Always test**: Data beats assumptions
+4. **Watch retention closely**: It's easier to add ads than win back users
+5. **Be transparent**: Users appreciate honesty about ad-supported models
+6. **Reward patience**: Give users free options before pushing ads
+7. **Optimize continuously**: Ad strategy should evolve with your product
+
+## Code Generation Guidelines (Step 9)
+
+Read this before generating ad implementation code in Step 9. It contains the general ad lifecycle,
+per-organization-approach guidance, the always-include requirements, and bid-floor wiring.
+
+### General Implementation Pattern
+
+All ad formats follow a similar lifecycle:
+
+1. **Load**: Request an ad from LevelPlay
+2. **Listen**: Register callbacks for ad events (loaded, failed, shown, clicked, closed)
+3. **Check readiness**: Verify ad is ready before showing
+4. **Show**: Display the ad to the user
+5. **Handle callbacks**: Respond to user interactions and ad lifecycle events
+
+### Adapt Output to the Chosen Organization Approach
+
+**If the user mentions they have existing code**, ask to see it before providing implementation
+guidance. This allows you to provide targeted fixes rather than generating new code from scratch.
+
+**Option 1: Separate manager scripts**
+- Create complete, production-ready `.cs` files for each ad format
+- Name them clearly: `RewardedAdManager.cs`, `InterstitialAdManager.cs`, `BannerAdManager.cs`
+- Include full class structure with proper namespaces
+- Each manager handles one ad format completely
+
+**Option 2: Unified AdManager**
+- Create a single `AdManager.cs` file
+- Include methods and callbacks for all requested ad formats in one class
+- Use clear method naming to distinguish between formats (e.g., `LoadRewardedAd()`, `LoadInterstitial()`)
+- Keep code organized with regions or comments separating each ad format
+
+**Option 3: Code snippets only**
+- Provide focused code blocks without full class wrappers
+- Clearly label each snippet (e.g., "Rewarded Ad Initialization", "Interstitial Event Callbacks")
+- Explain where/how to integrate each snippet
+- Note any dependencies between snippets
+
+### Regardless of Chosen Approach, Always Include
+- All manager classes must inherit from `MonoBehaviour` — required for Unity lifecycle methods (`Start()`, `OnDestroy()`) and to attach the script to a GameObject
+- After generating any manager script, instruct the user to attach it to a persistent GameObject in their scene (the same one as the initializer, with `DontDestroyOnLoad`)
+- For banner and interstitial managers, call `DestroyAd()` in `OnDestroy()` so ads are destroyed and memory is freed when the manager is destroyed
+- Rewarded and interstitial show paths check `IsAdReady()` before `ShowAd()`. If the game uses dashboard placements, also check the static `IsPlacementCapped(placementName)` — capping is configured per placement in the LevelPlay dashboard, and showing a capped placement fails (error codes 524/526)
+- Proper event subscription and unsubscription (to avoid memory leaks)
+- Null checks and defensive programming
+- Debug logs for troubleshooting
+- Clear variable names that match LevelPlay conventions
+- Error handling and graceful degradation
+
+### Bid Floor Handling (per-format)
+- If the user provided a bid floor value for a format, wrap construction in `Config.Builder().SetBidFloor(value).Build()` and pass the config to the constructor.
+- If the user said 'skip' for that format, use the basic constructor (`new LevelPlayRewardedAd(adUnitId)`).
+- Apply per-format: a publisher may set a floor on rewarded but skip banner.
+
+Example (with bid floor):
+```csharp
+var config = new LevelPlayRewardedAd.Config.Builder()
+    .SetBidFloor(0.80)
+    .Build();
+rewardedAd = new LevelPlayRewardedAd(adUnitId, config);
+```
+
+Example (skipped):
+```csharp
+rewardedAd = new LevelPlayRewardedAd(adUnitId);
+```
+
+## Additional Resources
+
+For detailed API implementation, see:
+- `rewarded-api.md`: Rewarded ad implementation
+- `interstitial-api.md`: Interstitial ad implementation
+- `banner-api.md`: Banner ad implementation
+- `initialization-api.md`: SDK setup and configuration

package/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/skills/levelplay-unity-integration/references/examples.md

@@ -0,0 +1,10 @@
+# Examples
+
+**Note**: Examples show abbreviated workflows for illustration. In practice, follow all steps 1–10 in order.
+
+**Revenue-focused game** ("maximize ad revenue in my casual puzzle game"): Steps 1–7 to verify environment/goal/install/deps/App Key/AdMob/init → Step 8 recommend Revenue strategy → Step 9 ask code organization and generate the chosen structure → Step 10 testing.
+
+**UX-focused game** ("optional rewarded ads for extra lives without annoying players"): same spine, but Step 8 recommends UX strategy (rewarded only, user-initiated) and Step 9 implements rewarded with proper patterns.
+
+**Existing project** ("existing GameManager, add interstitials between levels"): same spine, Step 8 Balanced, Step 9 ask to see `GameManager.cs` then provide Option-2 snippets.
+