🚀 1. Installation

Project Level (settings.gradle)

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

App Level (build.gradle)

dependencies {
    implementation 'com.github.partharoypc:SmartAds:6.0.0'
    implementation 'com.google.android.gms:play-services-ads:25.0.0'

    // SmartAds automatically handles other internal dependencies.
}

🔄 Upgrading to v6.0.0 (Important)

When you change the version number from 5.6.0 to 6.0.0 and sync:

1. Automatic Replacement: Gradle completely removes the old library files and downloads the new 6.0.0 version automatically.
2. Force Clean Cache: If you experience any weird resource issues after updating, simply navigate to Build -> Clean Project in Android Studio to wipe the old cache.
3. Deprecations Removed: Any old discarded classes or unused AdMob imports from v5.x have been permanently deleted inside the library. If your app relied on them, you will get a compile error prompting you to use the new, cleaner v6 APIs.

Manifest (AndroidManifest.xml)

<!-- Ad And Internet Permission -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

<!-- Admob Meta Data (inside the application tag) -->
<meta-data
  android:name="com.google.android.gms.ads.APPLICATION_ID"
      android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>

✅ Quick Integration Checklist

Before you start, make sure you've:

1. Added the JitPack repository.
2. Added the SmartAds and play-services-ads dependencies.
3. Added your AdMob App ID to AndroidManifest.xml.
4. Initialized the SDK in your Application class.

⚙️ 2. Configuration & Initialization

Initialize in your Application class using SmartAdsConfig.

SmartAdsConfig config = new SmartAdsConfig.Builder()
        .setAdsEnabled(true)        // Global Master Switch to enable/disable all ads
        .setInterstitialEnabled(true) // Granular switch for Interstitials
        .setRewardedEnabled(true)   // Granular switch for Rewarded ads
        .setAppOpenEnabled(true)    // Granular switch for App Open
        .setBannerEnabled(true)     // Granular switch for Banners
        .setNativeEnabled(true)     // Granular switch for Native ads
        .setTestModeEnabled(true)   // Uses Google Test IDs when enabled
        .setAdMobAppOpenId("AD_UNIT_ID")
        .setAdMobBannerId("AD_UNIT_ID")
        .setAdMobInterstitialId("AD_UNIT_ID")
        .setAdMobRewardedId("AD_UNIT_ID")
        .setAdMobNativeId("AD_UNIT_ID")
        .setUseUmpConsent(true)     // Enable GDPR/UMP consent flow
        .setFrequencyCapSeconds(30) // Min time between full-screen ads
        .build();

SmartAds.initialize(this, config);

Advanced Config Options

| setLoadingDialogText(String headline, String sub) | Custom headline and sub-text for valid loading dialog. | | setLoadingDialogColor(bg, text) | Custom background and text/headline colors. | | setLoadingDialogSubTextColor(int) | Custom color for the sub-text (default is secondary text color). | | setLoadingDialogProgressColor(int) | Custom color for the circular progress indicator. | | setMaxAdContentRating(String) | Set content rating: G, PG, T, MA. | | setTagForChildDirectedTreatment(int) | COPPA compliance (TAG_FOR_CHILD_DIRECTED_TREATMENT_TRUE). | | setTagForUnderAgeOfConsent(int) | GDPR compliance (TAG_FOR_UNDER_AGE_OF_CONSENT_TRUE). | | addTestDeviceId(String) | Add a specific physical device for test ads. | | setHouseAdsEnabled(boolean) | Globally enable or disable internal promotions. |

📺 3. Ad Implementation

Banner Ads

// Just pass the activity and a FrameLayout container
SmartAds.getInstance().showBannerAd(activity, container, new BannerAdListener() {
    @Override public void onAdLoaded(View adView) {}
    @Override public void onAdFailed(String error) {}
});

Interstitial Ads

// Preload once (ideally in onCreate or after previous ad)
SmartAds.getInstance().loadInterstitialAd(context); 

// Show when the user completes an action
if (SmartAds.getInstance().isInterstitialAdAvailable()) {
    SmartAds.getInstance().showInterstitialAd(activity, new InterstitialAdListener() {
        @Override public void onAdDismissed() {
            // Proceed to the next screen
        }
    });
}

Rewarded Ads

SmartAds.getInstance().showRewardedAd(activity, new RewardedAdListener() {
    @Override public void onUserEarnedReward() { 
        // 🎁 Grant the reward! 
    }
});

Native Ads

// Standard Template (MEDIUM, SMALL, or LARGE)
SmartAds.getInstance().showNativeAd(activity, container, NativeAdSize.MEDIUM, null);

// Custom XML Layout (Must be a NativeAdView in your XML)
SmartAds.getInstance().showNativeAd(activity, container, R.layout.my_layout, null);

🛠️ Common Implementation Patterns

Showing an Ad Before Navigating

void onNextButtonClicked() {
    if (SmartAds.getInstance().isInterstitialAdAvailable()) {
        SmartAds.getInstance().showInterstitialAd(this, new InterstitialAdListener() {
            @Override
            public void onAdDismissed() {
                startNextActivity();
            }
        });
    } else {
        startNextActivity();
    }
}

🏠 4. House Ads (Internal Cross-Promotion)

Add your own app promotions to show when network ads are unavailable or for direct marketing.

.addHouseAd(new HouseAd.Builder()
        .setId("banner_house")
        .setTitle("Try Our New App!")
        .setDescription("Download now for free.")
        .setClickUrl("GP_LINK")
        .setIconResId(R.drawable.icon)
        .setImageResId(R.drawable.banner)
        .setRating(5.0f)
        .build())
.setHouseAdsEnabled(true)

📊 5. Analytics & Paid Events

Track revenue with precision by hooking into the analytics listener.

SmartAds.getInstance().setAnalyticsListener((adUnitId, adFormat, adNetwork, valueMicros, currencyCode, precision, extras) -> {
    // Send data to Firebase, AppsFlyer, etc.
    // revenue = valueMicros / 1000000.0;
});

🤝 6. Debugging & Verification

SmartAds provides built-in tools to ensure your ad setup is working correctly:

1. AdMob Ad Inspector

Launch the official AdMob inspector to see real-time ad fill status and network behavior:

SmartAds.getInstance().launchAdInspector(activity);

Example: Complete Setup

Scenario: You want to set up Google AdMob with Banner and Interstitial Ads.

App's build.gradle:

dependencies {
    implementation 'com.github.partharoypc:SmartAds:6.0.0'
}

AndroidManifest.xml:

<application>
    <!-- AdMob App ID (Required) -->
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
</application>

Application class:

SmartAdsConfig config = new SmartAdsConfig.Builder()
    .setAdsEnabled(true)
    .setTestModeEnabled(BuildConfig.DEBUG)
    .setLoggingEnabled(BuildConfig.DEBUG)
    
    // Your ad unit IDs
    .setAdMobBannerId("ca-app-pub-xxx/banner")
    .setAdMobInterstitialId("ca-app-pub-xxx/interstitial")
    .build();

SmartAds.initialize(this, config);

🛡️ 7. API Reference (Public Methods)

Core

• initialize(Application, SmartAdsConfig): Setup the SDK (Call once).
• getInstance(): Access the singleton instance.
• isInitialized(): Static check for initialization status.
• getVersion(): Returns "6.0.0".
• shutdown(): Fully stop all ad services and clear memory.

Ad Control & Status

• setAdsEnabled(boolean): Enable/Disable ads dynamically at runtime.
• areAdsEnabled(): Check current global ad status.
• updateConfig(SmartAdsConfig): Switch ad unit IDs or logic on the fly.
• preloadAds(Context): Manually trigger pre-fetching for all formats.
• isAnyAdShowing(): Returns true if any full-screen ad is active.

Format Availability

• isAppOpenAdAvailable(): Check if App Open is ready.
• isInterstitialAdAvailable(): Check if Interstitial is loaded.
• isRewardedAdAvailable(): Check if Rewarded is loaded.
• getAppOpenAdStatus(): Returns LOADED, LOADING, IDLE, etc.

UMP Consent

• isPrivacyOptionsRequired(): Check if GDPR/CCPA settings are needed.
• showPrivacyOptionsForm(Activity): Display the UMP settings form.

🧹 8. Best Practices & Cleanup

To avoid memory leaks, always clean up containers in your Activity's onDestroy().

@Override
protected void onDestroy() {
    SmartAds.getInstance().destroyBannerIn(bannerContainer);
    SmartAds.getInstance().clearNativeIn(nativeContainer);
    super.onDestroy();
}

📄 License

Licensed under **MI