NativeAdManager

NativeAdManager Wiki

Welcome to the NativeAdManager wiki! This guide covers everything you need to know about integrating and using the NativeAdManager for managing native ads in your Android application. Learn how to efficiently preload, manage, and display ads using custom keys to create a seamless user experience.

---

Table of Contents

1. Overview
2. Features
   • Prerequisites
   • Adding Dependencies
   • Importing NativeAdManager
3. Configuration
   • Custom Keys and Ad Unit IDs
4. Using NativeAdManager
   • Preloading Ads
   • Observing Ad States
   • Binding Native Ads to UI
5. Resource Management
6. Best Practices
7. FAQs
8. Troubleshooting

---

Overview

The NativeAdManager is a centralized solution for preloading and managing multiple native ads within your Android application. Using custom keys, developers can efficiently manage different ad placements, track ad states, and ensure a smooth ad experience for users without resource issues.

---

Features

• Multiple Ad Management: Handle multiple native ads simultaneously using custom keys.
• Custom Key Integration: Manage ads using meaningful identifiers for different placements.
• State Tracking: Track the ad lifecycle using states like Idle, Loading, Ready, Showed, and Error.
• Retry Mechanism: Automatically retry loading ads with configurable retry limits.

  // Retry configuration
  NativeAdManager.setMaxRetries(5) //default is 3

• Resource Management: Ensure proper release of ad resources to prevent memory leaks.

---

Configuration

Custom Keys and Ad Unit IDs

Define custom keys for your ad placements and their corresponding AdMob ad unit IDs. This helps in organizing ad placements efficiently.

object AdConfig {
    const val HOMEPAGE_AD = "homepage_ad"
    const val SIDEBAR_AD = "sidebar_ad"
    // Add more as needed
}

Replace the placeholders with relevant identifiers and ad unit IDs from AdMob.

---

Using NativeAdManager

Native Ads Caching

This will display last cached native ad if current native does not fill from server. To cache a native ad use following code one time on application scope

// for small and medium native ads
NativeAdManager.enableCachingNativeAds = true
// for large native ads
NativeAdManager.enableCachingLargeNativeAds = true

Preloading Ads

To preload ads, use the preloadAd function, which takes context, a custom key, and the AdMob ad unit ID as parameters.

NativeAdManager.preloadAd(
    context = this,
    customKey = AdConfig.HOMEPAGE_AD,
    adUnitId = "your-homepage-ad-unit-id"
)

Observing Ad States

NativeAdManager uses LiveData to track ad states, allowing you to observe state changes for each ad placement.

NativeAdManager.getAdStatesLiveData().observe(this, Observer { adStates ->
    adStates.forEach { (customKey, adState) ->
        handleAdState(customKey, adState)
    }
})

Ad States:

• Idle: No ad is being loaded or displayed.
• Loading: The ad is being loaded.
• Ready: The ad is successfully loaded and ready to be displayed.
• Showed: The ad has been displayed.
• Error: An error occurred while loading the ad.

Binding Native Ads to UI

To display native ads, bind them to your UI components. Ensure that the NativeAdView layout is properly designed in XML.

private fun displayAd(customKey: String, nativeAd: NativeAd) {
    val nativeBannerMedium: NativeBannerMedium = findViewById(R.id.nativeBannerMedium)
    nativeBannerMedium.displayAd(nativeAd)
}

---

Resource Management

To prevent memory leaks, ensure that native ads are released properly when no longer needed.

override fun onDestroy() {
    super.onDestroy()
    NativeAdManager.releaseAllAds()
}

You can also release specific ads using:

NativeAdManager.releaseAd(AdConfig.HOMEPAGE_AD)

---

Best Practices

• Lifecycle Management: Release ads during appropriate lifecycle events (onDestroy, onStop) to prevent memory leaks.
• Retry Logic: Configure retry limits to balance ad availability and resource usage.
• Error Handling: Provide user feedback in case of ad loading failures.
• Ad Placement Strategy: Strategically place ads to maximize visibility without negatively affecting user experience.

---

FAQs

1. How do I manage different types of ads (e.g., banner, interstitial)?

NativeAdManager is designed for native ads. For managing other ad types, consider creating separate managers or extending NativeAdManager.

2. How can I observe changes in ad states?

Use the getAdStatesLiveData() function and set up an observer to handle state changes appropriately.

3. How do I handle concurrent ad loads?

NativeAdManager prevents concurrent loads for the same ad key using an internal flag. Ensure your app logic manages preload calls efficiently.

---

Troubleshooting

Ads Not Loading

• Ad Unit Configuration: Verify that ad unit IDs are correct and match those in AdMob.
• Network Connectivity: Ensure that the device has an active internet connection.
• AdMob Settings: Verify your AdMob account status and settings.

Memory Leaks

• Always call releaseAd or releaseAllAds during appropriate lifecycle events.
• Ensure that NativeAd.destroy() is invoked for every loaded ad when no longer needed.

Custom Keys Not Working

• Make sure each customKey is unique and consistently used across the app to avoid state mismatches.

---

---

License

This project is licensed under the MIT License.

---

For further questions, open an issue or reach out to the maintainers.

Happy Coding! 🚀