{"id":35272584,"url":"https://github.com/partharoypc/smartads","last_synced_at":"2026-02-06T19:01:12.515Z","repository":{"id":308719157,"uuid":"1033154899","full_name":"partharoypc/SmartAds","owner":"partharoypc","description":"SmartAds: The ultimate Android AdMob wrapper for high-performance monetization Super Complete Android Library. Simplify Banner, Interstitial, Rewarded, App Open, and Native ads with lifecycle safety, automated UMP (GDPR) consent, and multi-network mediation.","archived":false,"fork":false,"pushed_at":"2026-02-04T03:41:17.000Z","size":1674,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T14:57:20.691Z","etag":null,"topics":["admob","admob-sdk","ads","android","android-library","android-library-publish","applovin","applovin-max","facebook-ads","facebook-ads-sdk","java","meta-ads","monetization","monetization-library","unity-ads","unity-ads-sdk"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/partharoypc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-06T11:33:04.000Z","updated_at":"2026-02-04T03:39:26.000Z","dependencies_parsed_at":"2025-08-07T14:37:24.596Z","dependency_job_id":null,"html_url":"https://github.com/partharoypc/SmartAds","commit_stats":null,"previous_names":["partharoypc/smartads"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/partharoypc/SmartAds","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partharoypc%2FSmartAds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partharoypc%2FSmartAds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partharoypc%2FSmartAds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partharoypc%2FSmartAds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/partharoypc","download_url":"https://codeload.github.com/partharoypc/SmartAds/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partharoypc%2FSmartAds/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29172722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T16:33:35.550Z","status":"ssl_error","status_checked_at":"2026-02-06T16:33:30.716Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admob","admob-sdk","ads","android","android-library","android-library-publish","applovin","applovin-max","facebook-ads","facebook-ads-sdk","java","meta-ads","monetization","monetization-library","unity-ads","unity-ads-sdk"],"created_at":"2025-12-30T12:59:19.895Z","updated_at":"2026-02-06T19:01:12.507Z","avatar_url":"https://github.com/partharoypc.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo/logo.png\" alt=\"SmartAds Logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n# SmartAds Android Library 🚀\n\n**SmartAds** is a professional-grade, lightweight, and developer-friendly Android wrapper for the Google Mobile Ads SDK (AdMob). It streamlines complex ad integrations into simple, lifecycle-aware components, allowing you to focus on building features while we handle the monetization.\n\n[![](https://jitpack.io/v/partharoypc/SmartAds.svg)](https://jitpack.io/#partharoypc/SmartAds)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Android](https://img.shields.io/badge/Platform-Android-green.svg)]()\n[![Google Mobile Ads](https://img.shields.io/badge/SDK-AdMob_24.0.0-blue.svg)]()\n\n---\n\n## 🤔 Why SmartAds?\n\nIntegrating ads can be messy—handling context, memory leaks, pre-fetching, and mediation verification often leads to boilerplate-heavy code. **SmartAds** solves this by:\n- **Reducing Boilerplate**: From 150+ lines of AdMob code to just 1-2 lines.\n- **Lifecycle Safety**: Built-in protection against Activity-based memory leaks.\n- **Smart Pre-fetching**: Automatically caches ads so they're ready the moment you need them.\n- **House Ads Fallback**: Never miss an impression—show your own promotions if the network fails.\n\n---\n\n## 🌟 Key Features\n\n- ✅ **Unified Initialization**: One-time setup in your `Application` class.\n- 📱 **Complete Format Support**: App Open, Banner (Adaptive/Collapsible), Interstitial, Rewarded, and Native Ads.\n- 🛠️ **Seamless Mediation**: Dedicated support for Meta, AppLovin, and Unity Ads.\n- 🏠 **House Ads System**: Native fallbacks for internal cross-promotion.\n- 📜 **Privacy First**: Built-in Google UMP (GDPR/CCPA) consent management.\n- 🧪 **Test Mode**: Automatically handles AdMob Test IDs during development.\n- 🔍 **Debug Suite**: Integrated Ad Inspector, Mediation Test Suite, and detailed logging.\n- � **Offline Smart-Check**: Automatically skips network calls when offline and switches to House Ads immediately.\n- 🧹 **Optimized ProGuard**: Smart rules save users ~30MB by stripping unused AdMob code.\n- �💰 **Paid Event Tracking**: Simple hook for revenue analytics (Firebase, AppsFlyer, etc.).\n\n---\n\n## 🚀 1. Installation\n\n### Project Level (`settings.gradle`)\n```gradle\ndependencyResolutionManagement {\n    repositories {\n        google()\n        mavenCentral()\n        maven { url 'https://jitpack.io' }\n    }\n}\n```\n\n### App Level (`build.gradle`)\n```gradle\ndependencies {\n    implementation 'com.github.partharoypc:SmartAds:5.4.0'\n    implementation 'com.google.android.gms:play-services-ads:24.9.0'\n\n    // SmartAds automatically handles other internal dependencies.\n    // Note: Mediation adapters are NOT included by default.\n}\n```\n\n### Manifest (`AndroidManifest.xml`)\n```xml\n\u003c!-- Ad And Internet Permission --\u003e\n\u003cuses-permission android:name=\"android.permission.INTERNET\"/\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/\u003e\n\u003cuses-permission android:name=\"com.google.android.gms.permission.AD_ID\"/\u003e\n\n\u003c!-- Admob Meta Data (inside the application tag) --\u003e\n\u003cmeta-data\n  android:name=\"com.google.android.gms.ads.APPLICATION_ID\"\n      android:value=\"ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy\"/\u003e\n```\n\n---\n\n## ✅ Quick Integration Checklist\nBefore you start, make sure you've:\n1. [ ] Added the JitPack repository.\n2. [ ] Added the `SmartAds` and `play-services-ads` dependencies.\n3. [ ] Added your **AdMob App ID** to `AndroidManifest.xml`.\n4. [ ] Initialized the SDK in your `Application` class.\n\n---\n\n## ⚙️ 2. Configuration \u0026 Initialization\n\nInitialize in your `Application` class using `SmartAdsConfig`.\n\n```java\nSmartAdsConfig config = new SmartAdsConfig.Builder()\n        .setAdsEnabled(true)        // Global switch to enable/disable ads\n        .setTestModeEnabled(true)   // Uses Google Test IDs when enabled\n        .setAdMobAppOpenId(\"AD_UNIT_ID\")\n        .setAdMobBannerId(\"AD_UNIT_ID\")\n        .setAdMobInterstitialId(\"AD_UNIT_ID\")\n        .setAdMobRewardedId(\"AD_UNIT_ID\")\n        .setAdMobNativeId(\"AD_UNIT_ID\")\n        .setUseUmpConsent(true)     // Enable GDPR/UMP consent flow\n        .setFrequencyCapSeconds(30) // Min time between full-screen ads\n        .build();\n\nSmartAds.initialize(this, config);\n```\n\n### Advanced Config Options\n| Method | Description |\n|--------|-------------|\n| `setLoggingEnabled(boolean)` | Enable internal debug logs. |\n| `setCollapsibleBannerEnabled(boolean)` | Enable collapsible banner feature. |\n| `setFacebookMediationEnabled(boolean)` | Verification for Meta Audience Network. |\n| `setAppLovinMediationEnabled(boolean)` | Verification for AppLovin. |\n| `setUnityMediationEnabled(boolean)` | Verification for Unity Ads. |\n| `setLoadingDialogText(String headline, String sub)` | Custom headline and sub-text for valid loading dialog. |\n| `setLoadingDialogColor(bg, text)` | Custom background and text/headline colors. |\n| `setLoadingDialogSubTextColor(int)` | Custom color for the sub-text (default is secondary text color). |\n| `setLoadingDialogProgressColor(int)` | Custom color for the circular progress indicator. |\n| `setMaxAdContentRating(String)` | Set content rating: `G`, `PG`, `T`, `MA`. |\n| `setTagForChildDirectedTreatment(int)` | COPPA compliance (`TAG_FOR_CHILD_DIRECTED_TREATMENT_TRUE`). |\n| `setTagForUnderAgeOfConsent(int)` | GDPR compliance (`TAG_FOR_UNDER_AGE_OF_CONSENT_TRUE`). |\n| `addTestDeviceId(String)` | Add a specific physical device for test ads. |\n| `setHouseAdsEnabled(boolean)` | Globally enable or disable internal promotions. |\n\n---\n\n## 📺 3. Ad Implementation\n\n### **Banner Ads**\n```java\n// Just pass the activity and a FrameLayout container\nSmartAds.getInstance().showBannerAd(activity, container, new BannerAdListener() {\n    @Override public void onAdLoaded(View adView) {}\n    @Override public void onAdFailed(String error) {}\n});\n```\n\n### **Interstitial Ads**\n```java\n// Preload once (ideally in onCreate or after previous ad)\nSmartAds.getInstance().loadInterstitialAd(context); \n\n// Show when the user completes an action\nif (SmartAds.getInstance().isInterstitialAdAvailable()) {\n    SmartAds.getInstance().showInterstitialAd(activity, new InterstitialAdListener() {\n        @Override public void onAdDismissed() {\n            // Proceed to the next screen\n        }\n    });\n}\n```\n\n### **Rewarded Ads**\n```java\nSmartAds.getInstance().showRewardedAd(activity, new RewardedAdListener() {\n    @Override public void onUserEarnedReward() { \n        // 🎁 Grant the reward! \n    }\n});\n```\n\n### **Native Ads**\n```java\n// Standard Template (MEDIUM, SMALL, or LARGE)\nSmartAds.getInstance().showNativeAd(activity, container, NativeAdSize.MEDIUM, null);\n\n// Custom XML Layout (Must be a NativeAdView in your XML)\nSmartAds.getInstance().showNativeAd(activity, container, R.layout.my_layout, null);\n```\n\n---\n\n## 🛠️ Common Implementation Patterns\n\n### **Showing an Ad Before Navigating**\n```java\nvoid onNextButtonClicked() {\n    if (SmartAds.getInstance().isInterstitialAdAvailable()) {\n        SmartAds.getInstance().showInterstitialAd(this, new InterstitialAdListener() {\n            @Override\n            public void onAdDismissed() {\n                startNextActivity();\n            }\n        });\n    } else {\n        startNextActivity();\n    }\n}\n```\n\n---\n\n## 🏠 4. House Ads (Internal Cross-Promotion)\nAdd your own app promotions to show when network ads are unavailable or for direct marketing.\n\n```java\n.addHouseAd(new HouseAd.Builder()\n        .setId(\"banner_house\")\n        .setTitle(\"Try Our New App!\")\n        .setDescription(\"Download now for free.\")\n        .setClickUrl(\"GP_LINK\")\n        .setIconResId(R.drawable.icon)\n        .setImageResId(R.drawable.banner)\n        .setRating(5.0f)\n        .build())\n.setHouseAdsEnabled(true)\n```\n\n---\n\n## 📊 5. Analytics \u0026 Paid Events\nTrack revenue with precision by hooking into the analytics listener.\n\n```java\nSmartAds.getInstance().setAnalyticsListener((adUnitId, adFormat, adNetwork, valueMicros, currencyCode, precision, extras) -\u003e {\n    // Send data to Firebase, AppsFlyer, etc.\n    // revenue = valueMicros / 1000000.0;\n});\n```\n\n---\n\n## 🤝 6. Mediation Setup (Optional)\n\n\u003e [!IMPORTANT]\n\u003e SmartAds library does **NOT** include any mediation adapters by default. Only add the networks you actually use in AdMob mediation to keep your app size minimal.\n\n### When to Add Mediation Adapters\n\nAdd mediation dependencies to your **app's** `build.gradle` ONLY if:\n- ✅ You have configured that network in your AdMob account mediation settings\n- ✅ You want to use that network for ad fill\n- ❌ **Don't** add them \"just in case\" - each adapter adds 3-5 MB to your app size\n\n---\n\n### Available Mediation Networks\n\nAlways check the [Google Mediation Page](https://developers.google.com/admob/android/mediation) for the latest adapter versions.\n\n#### 🔵 Meta (Facebook Audience Network)\n\n**Step 1**: Add dependency to your app's `build.gradle`\n```gradle\ndependencies {\n    implementation 'com.google.ads.mediation:facebook:6.21.0.0'\n}\n```\n\n**Step 2**: Enable in SmartAds config\n```java\nSmartAdsConfig config = new SmartAdsConfig.Builder()\n    .setFacebookMediationEnabled(true)  // Enable verification\n    // ... other config\n    .build();\n```\n\n**Manifest**: No extra meta-data required.\n\n---\n\n#### 🔴 AppLovin MAX\n\n**Step 1**: Add dependency to your app's `build.gradle`\n```gradle\ndependencies {\n    implementation 'com.google.ads.mediation:applovin:13.5.1.0'\n}\n```\n\n**Step 2**: Add SDK key to `AndroidManifest.xml` (inside `\u003capplication\u003e` tag)\n```xml\n\u003cmeta-data \n    android:name=\"applovin.sdk.key\" \n    android:value=\"YOUR_APPLOVIN_SDK_KEY\"/\u003e\n```\n\n**Step 3**: Enable in SmartAds config\n```java\nSmartAdsConfig config = new SmartAdsConfig.Builder()\n    .setAppLovinMediationEnabled(true)  // Enable verification\n    // ... other config\n    .build();\n```\n\n---\n\n#### 🟢 Unity Ads\n\n**Step 1**: Add dependency to your app's `build.gradle`\n```gradle\ndependencies {\n    implementation 'com.google.ads.mediation:unity:4.16.5.0'\n}\n```\n\n**Step 2**: Enable in SmartAds config\n```java\nSmartAdsConfig config = new SmartAdsConfig.Builder()\n    .setUnityMediationEnabled(true)  // Enable verification\n    // ... other config\n    .build();\n```\n\n**Manifest**: No extra meta-data required. Configuration is handled via AdMob UI.\n\n---\n\n### Recommended ProGuard / R8 Rules\n\nIf you use `minifyEnabled true`, add these rules to your app's `proguard-rules.pro` **only for the networks you're using**:\n\n```proguard\n# Google Mobile Ads (Always required)\n-keep public class com.google.android.gms.ads.** { *; }\n\n# Meta (Facebook) - Only if using Facebook mediation\n-keep class com.facebook.ads.** { *; }\n-dontwarn com.facebook.ads.**\n\n# AppLovin - Only if using AppLovin mediation\n-keep class com.applovin.** { *; }\n-dontwarn com.applovin.**\n\n# Unity Ads - Only if using Unity mediation\n-keep class com.unity3d.ads.** { *; }\n-keep class com.unity3d.services.** { *; }\n-dontwarn com.unity3d.ads.**\n-dontwarn com.unity3d.services.**\n```\n\n---\n\n### Mediation Verification \u0026 Debugging\n\nSmartAds provides built-in tools to ensure your mediation setup is working correctly:\n\n#### 1. Adapter Detection\nAutomatically logs which adapters are found during initialization (when logging is enabled):\n```java\nSmartAdsConfig config = new SmartAdsConfig.Builder()\n    .setLoggingEnabled(true)  // Enable to see adapter detection logs\n    .setFacebookMediationEnabled(true)\n    .setAppLovinMediationEnabled(true)\n    .build();\n\n// Logs will show:\n// ✅ Facebook / Meta Audience Network Adapter found.\n// ✅ AppLovin Adapter found.\n// ❌ Unity Ads Adapter NOT found. Add dependency.\n```\n\nYou can also manually verify at any time:\n```java\nSmartAds.getInstance().verifyMediation(activity);\n```\n\n#### 2. AdMob Ad Inspector\nLaunch the official AdMob inspector to see real-time ad fill status and mediation waterfall:\n```java\nSmartAds.getInstance().launchAdInspector(activity);\n```\n\n#### 3. Mediation Test Suite (Optional)\nFor comprehensive mediation testing, add the test suite to your app (debug builds only):\n```gradle\ndependencies {\n    debugImplementation 'com.google.android.ads:mediation-test-suite:3.0.0'\n}\n```\n\nThen launch it:\n```java\nSmartAds.getInstance().openMediationTestSuite(activity);\n```\n\n---\n\n### Example: Complete Setup with Selective Mediation\n\n**Scenario**: You only want to use Facebook and AppLovin mediation.\n\n**App's `build.gradle`**:\n```gradle\ndependencies {\n    implementation 'com.github.partharoypc:SmartAds:5.5.0'\n    \n    // Only the networks you use\n    implementation 'com.google.ads.mediation:facebook:6.21.0.0'\n    implementation 'com.google.ads.mediation:applovin:13.5.1.0'\n    \n    // Optional: Test suite for debugging\n    debugImplementation 'com.google.android.ads:mediation-test-suite:3.0.0'\n}\n```\n\n**AndroidManifest.xml**:\n```xml\n\u003capplication\u003e\n    \u003c!-- AdMob App ID (Required) --\u003e\n    \u003cmeta-data\n        android:name=\"com.google.android.gms.ads.APPLICATION_ID\"\n        android:value=\"ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy\"/\u003e\n    \n    \u003c!-- AppLovin SDK Key (Required for AppLovin) --\u003e\n    \u003cmeta-data \n        android:name=\"applovin.sdk.key\" \n        android:value=\"YOUR_APPLOVIN_SDK_KEY\"/\u003e\n\u003c/application\u003e\n```\n\n**Application class**:\n```java\nSmartAdsConfig config = new SmartAdsConfig.Builder()\n    .setAdsEnabled(true)\n    .setTestModeEnabled(BuildConfig.DEBUG)\n    .setLoggingEnabled(BuildConfig.DEBUG)\n    \n    // Enable only the networks you added\n    .setFacebookMediationEnabled(true)\n    .setAppLovinMediationEnabled(true)\n    .setUnityMediationEnabled(false)  // Not using Unity\n    \n    // Your ad unit IDs\n    .setAdMobBannerId(\"ca-app-pub-xxx/banner\")\n    .setAdMobInterstitialId(\"ca-app-pub-xxx/interstitial\")\n    .build();\n\nSmartAds.initialize(this, config);\n```\n\n---\n\n## 🛡️ 7. API Reference (Public Methods)\n\n### Core\n- `initialize(Application, SmartAdsConfig)`: Setup the SDK (Call once).\n- `getInstance()`: Access the singleton instance.\n- `isInitialized()`: Static check for initialization status.\n- `getVersion()`: Returns \"5.0.0\".\n- `shutdown()`: Fully stop all ad services and clear memory.\n\n### Ad Control \u0026 Status\n- `setAdsEnabled(boolean)`: Enable/Disable ads dynamically at runtime.\n- `areAdsEnabled()`: Check current global ad status.\n- `updateConfig(SmartAdsConfig)`: Switch ad unit IDs or logic on the fly.\n- `preloadAds(Context)`: Manually trigger pre-fetching for all formats.\n- `isAnyAdShowing()`: Returns true if any full-screen ad is active.\n\n### Format Availability\n- `isAppOpenAdAvailable()`: Check if App Open is ready.\n- `isInterstitialAdAvailable()`: Check if Interstitial is loaded.\n- `isRewardedAdAvailable()`: Check if Rewarded is loaded.\n- `getAppOpenAdStatus()`: Returns `LOADED`, `LOADING`, `IDLE`, etc.\n\n### UMP Consent\n- `isPrivacyOptionsRequired()`: Check if GDPR/CCPA settings are needed.\n- `showPrivacyOptionsForm(Activity)`: Display the UMP settings form.\n\n---\n\n## 🧹 8. Best Practices \u0026 Cleanup\nTo avoid memory leaks, always clean up containers in your Activity's `onDestroy()`.\n\n```java\n@Override\nprotected void onDestroy() {\n    SmartAds.getInstance().destroyBannerIn(bannerContainer);\n    SmartAds.getInstance().clearNativeIn(nativeContainer);\n    super.onDestroy();\n}\n```\n\n---\n\n## 📄 License\nLicensed under **MIT License**. Created by [Partha Roy](https://github.com/partharoypc).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpartharoypc%2Fsmartads","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpartharoypc%2Fsmartads","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpartharoypc%2Fsmartads/lists"}