Ads System

Overview

BlocKIT includes a flexible ad system that works with any ad network. It's set up so you can easily plug in AdMob, Unity Ads, or any other provider.

Architecture

AdsManager (singleton)
    ↓
Uses: IAdsProvider (interface)
    ↓
Your implementation:
- AdMobProvider
- UnityAdsProvider
- IronSourceProvider
- etc.

Components

AdsManager

Main controller for all ads.

public class AdsManager : MonoBehaviour
{
    public static AdsManager Instance { get; }

    public void ShowRewarded(Action onRewardGranted);
    public void ShowInterstitial();
    public bool CanShowRewarded();
    public bool CanShowInterstitial();
}

Location: Persistent across scenes (DontDestroyOnLoad)

IAdsProvider

Interface your ad provider must implement:

public interface IAdsProvider
{
    bool IsRewardedAvailable();
    bool IsInterstitialAvailable();
    void ShowRewarded(Action onRewardGranted);
    void ShowInterstitial();
}

DummyAdsProvider

Default provider (does nothing):

public class DummyAdsProvider : IAdsProvider
{
    // All methods return false / do nothing
    // Used when no real provider set
}

How to Use

Basic Setup

1. Create your ad provider:

// Example: AdMob provider
public class AdMobProvider : IAdsProvider
{
    private RewardedAd rewardedAd;
    private InterstitialAd interstitialAd;

    public AdMobProvider()
    {
        // Initialize AdMob
        MobileAds.Initialize(status => {});
        LoadAds();
    }

    public bool IsRewardedAvailable()
    {
        return rewardedAd != null && rewardedAd.IsLoaded();
    }

    public void ShowRewarded(Action onRewardGranted)
    {
        if (IsRewardedAvailable())
        {
            rewardedAd.Show();
            rewardedAd.OnUserEarnedReward += (sender, args) => {
                onRewardGranted?.Invoke();
            };
        }
    }

    // Implement other methods...
}

1. Set provider at game start:

// In your game initialization script:
void Start()
{
    var provider = new AdMobProvider();
    AdsManager.Instance.SetProvider(provider);
}

1. Use ads anywhere:

// Rewarded ad (player gets reward)
if (AdsManager.Instance.CanShowRewarded())
{
    AdsManager.Instance.ShowRewarded(() => {
        // Give player reward
        GiveExtraLives();
    });
}

// Interstitial ad (no reward)
if (AdsManager.Instance.CanShowInterstitial())
{
    AdsManager.Instance.ShowInterstitial();
}

When to Show Ads

Interstitial Ads

Good times to show: - ✅ After game over - ✅ Every N games (e.g., every 3rd) - ✅ When returning to menu - ✅ Level transitions

Example:

int gamesPlayed = 0;

void OnGameOver()
{
    gamesPlayed++;

    if (gamesPlayed % 3 == 0)  // Every 3 games
    {
        if (AdsManager.Instance.CanShowInterstitial())
        {
            AdsManager.Instance.ShowInterstitial();
        }
    }
}

Rewarded Ads

Offer rewards for watching: - 🎁 Extra lives/continues - 💰 Bonus points - 🔄 Undo last move - 💎 In-game currency

Example:

public void OnContinueButtonPressed()
{
    if (AdsManager.Instance.CanShowRewarded())
    {
        AdsManager.Instance.ShowRewarded(() => {
            // Reward granted!
            ContinueGame();
            ShowMessage("Continue granted!");
        });
    }
    else
    {
        ShowMessage("Ad not available");
    }
}

Common Implementations

AdMob Integration

public class AdMobProvider : IAdsProvider
{
    private string rewardedId = "ca-app-pub-xxx/xxx";
    private string interstitialId = "ca-app-pub-xxx/xxx";

    private RewardedAd rewarded;
    private InterstitialAd interstitial;

    public AdMobProvider()
    {
        MobileAds.Initialize(status => {
            LoadRewardedAd();
            LoadInterstitialAd();
        });
    }

    private void LoadRewardedAd()
    {
        rewarded = new RewardedAd(rewardedId);
        AdRequest request = new AdRequest.Builder().Build();
        rewarded.LoadAd(request);
    }

    private void LoadInterstitialAd()
    {
        interstitial = new InterstitialAd(interstitialId);
        AdRequest request = new AdRequest.Builder().Build();
        interstitial.LoadAd(request);
    }

    public bool IsRewardedAvailable() 
        => rewarded != null && rewarded.IsLoaded();

    public bool IsInterstitialAvailable() 
        => interstitial != null && interstitial.IsLoaded();

    public void ShowRewarded(Action onRewardGranted)
    {
        if (IsRewardedAvailable())
        {
            rewarded.OnUserEarnedReward += (s, e) => {
                onRewardGranted?.Invoke();
                LoadRewardedAd();  // Load next
            };
            rewarded.Show();
        }
    }

    public void ShowInterstitial()
    {
        if (IsInterstitialAvailable())
        {
            interstitial.OnAdClosed += (s, e) => {
                LoadInterstitialAd();  // Load next
            };
            interstitial.Show();
        }
    }
}

Unity Ads Integration

public class UnityAdsProvider : IAdsProvider, IUnityAdsListener
{
    private string gameId = "1234567";
    private string rewardedPlacement = "rewardedVideo";
    private string interstitialPlacement = "video";

    private Action rewardCallback;

    public UnityAdsProvider()
    {
        Advertisement.AddListener(this);
        Advertisement.Initialize(gameId, testMode: false);
    }

    public bool IsRewardedAvailable()
        => Advertisement.IsReady(rewardedPlacement);

    public bool IsInterstitialAvailable()
        => Advertisement.IsReady(interstitialPlacement);

    public void ShowRewarded(Action onRewardGranted)
    {
        rewardCallback = onRewardGranted;
        Advertisement.Show(rewardedPlacement);
    }

    public void ShowInterstitial()
    {
        Advertisement.Show(interstitialPlacement);
    }

    public void OnUnityAdsDidFinish(string placementId, ShowResult result)
    {
        if (placementId == rewardedPlacement && 
            result == ShowResult.Finished)
        {
            rewardCallback?.Invoke();
        }
    }

    // Implement other IUnityAdsListener methods...
}

Best Practices

DO:

✅ Check availability before showing ✅ Load next ad after showing current ✅ Give clear reward descriptions ✅ Respect player choice (optional ads) ✅ Test with test mode IDs first

DON'T:

❌ Show ads too frequently ❌ Force ads for basic features ❌ Show ads during gameplay ❌ Forget to handle failures ❌ Use production IDs in development

Ad Frequency Control

public class AdFrequencyManager
{
    private float lastAdTime;
    private const float MIN_TIME_BETWEEN = 180f;  // 3 minutes

    public bool CanShowAd()
    {
        float timeSince = Time.time - lastAdTime;
        return timeSince >= MIN_TIME_BETWEEN;
    }

    public void OnAdShown()
    {
        lastAdTime = Time.time;
    }
}

// Usage:
if (frequencyManager.CanShowAd() && 
    AdsManager.Instance.CanShowInterstitial())
{
    AdsManager.Instance.ShowInterstitial();
    frequencyManager.OnAdShown();
}

Reward System Example

public class RewardManager : MonoBehaviour
{
    public void OfferExtraLife()
    {
        if (AdsManager.Instance.CanShowRewarded())
        {
            ShowPrompt("Watch ad for extra life?", () => {
                AdsManager.Instance.ShowRewarded(GrantExtraLife);
            });
        }
        else
        {
            ShowMessage("Ad not available, try again later");
        }
    }

    private void GrantExtraLife()
    {
        PlayerData.Lives++;
        NewManager.Instance.ContinueGame();
        ShowMessage("Life granted! Game continues!");
    }
}

Testing

Test Mode IDs

Most ad networks provide test IDs:

#if UNITY_EDITOR || DEVELOPMENT_BUILD
    string adId = "test-rewarded-id";
#else
    string adId = "production-rewarded-id";
#endif

Debug Logging

public void ShowRewarded(Action onRewardGranted)
{
    Debug.Log("[Ads] Attempting to show rewarded ad");

    if (!IsRewardedAvailable())
    {
        Debug.LogWarning("[Ads] Rewarded ad not ready");
        return;
    }

    Debug.Log("[Ads] Showing rewarded ad");
    // Show ad...
}

Troubleshooting

Ads not showing

• ✅ Check provider is set correctly
• ✅ Verify ad IDs are correct
• ✅ Check network connectivity
• ✅ Look for SDK errors in console

Rewards not granted

• ✅ Check callback is being called
• ✅ Verify ad completed (not skipped)
• ✅ Check for callback exceptions

Ads loading slowly

• ✅ Preload ads during menu
• ✅ Load next ad after showing
• ✅ Check network speed

What's Next?

• 🔊 Sound System - audio integration
• 🎮 Game Manager - game flow
• ⚙️ Customization - tune your game

---

Legal Reminder

Always comply with ad network policies and privacy laws (GDPR, COPPA, etc.). Get user consent where required!