Android SDK Usage

Important: When building and testing your apps, make sure you use test ads rather than production ads. Failure to do so can lead to suspension of your account. Please see the Optional Parameters section for more info on toggling the test ads.

Banner Ads

Views (XML & Code)

Once the initialization of the SDK is complete, you can get and load banner ads from the EMAManager instance automatically by using the following method:

EMAManager.loadBannerAd(this, zoneId, bannerContainer, this)

this: Activity or Fragment

zoneId: Banner id that will be loaded in the view.

bannerContainer: ViewGroup container that banner ad is loaded.

this(Optional): AdStatusListener to be informed by the banner load status.

adConfiguration: If you don't want to load ads automatically, create AdConfiguration object and send as false. ex: (AdConfiguration(false))

customParameters: You can pass custom key-value pairs to target Google Ad Manager campaigns.

keywords: If you are using keywords for targeting, send your parameters as string value.

Note: You should callloadBannerAdmethod in the onCreate().

You can set a manager's AdStatusListener. An AdStatusListener is used for getting callbacks during the ads' lifecycles. You can send as a fourth parameter for the listener.Depending on the callbacks, you may either display the ad to the user or skip it entirely.

Java

EMAManager.getInstance().loadBannerAd(this, zoneId, bannerContainer, this)// AdStatusListener

Kotlin

EMAManager.instance.loadBannerAd(this, zoneId, bannerContainer, this) // AdStatusListener

If you implement AdStatusListener, Once the EMAManager.getInstance().loadBannerAd method is called, one of these below three will happen, otherwise SDK will manage the lifecycle of bannerAd.

bannerStatusChanged will be called with status of bannerManager set to AdStatus.READY.
bannerStatusChanged will be called with status of bannerManager set to AdStatus.FAILED.
If ads are disabled or the user in an unfinished ad session, then bannerManager.loadBannerAd call will be ignored and nothing will happen.

Note: In the full example code you will see sample zoneId 123456. You will be given your actual zoneIds by us, and you will have to replace these sample ids with actual zone ids.

Java/Kotlin Usage

Java

public class MyActivity extends AppCompatActivity {
private RelativeLayout relativeLayoutForBanner;
  @Override protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_sample);
    relativeLayoutForBanner = findViewById(relativeLayoutForBanner);
    EMAManager.getInstance().loadBannerAd(this,123456, relativeLayoutForBanner);
  }
}

Kotlin

class MyActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_sample)
    EMAManager.instance.loadBannerAd(this,123456, relativeLayoutForBanner)
  }
}

Jetpack Compose

The SDK provides a composable function EmpowerBannerAd to easily display banner ads in your Compose UI.

Compose Usage

To display a banner ad, simply call the EmpowerBannerAd composable and provide the required parameters.

import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.platform.LocalLifecycleOwner
import net.empower.mobile.ads.compose.EmpowerBannerAd
@Composable
fun MyScreen() {
    Box(modifier = Modifier.fillMaxSize()) {
        // ... other content ...
        val context = LocalContext.current
        val lifecycleOwner = LocalLifecycleOwner.current
        EmpowerBannerAd(
            modifier = Modifier.align(Alignment.BottomCenter),
            zoneId = "YOUR_ZONE_ID", // Replace with your Zone ID
            context = context,
            lifecycleOwner = lifecycleOwner
        )
    }
}

Parameters

modifier: (Optional) A Modifier to be applied to the banner ad container. This allows you to position the ad within your layout (e.g., at the bottom of the screen).
zoneId: (Required) The unique identifier for the ad zone you want to display.
context: (Required) The current Context. You can obtain this using LocalContext.current.
lifecycleOwner: (Required) The current LifecycleOwner. You can obtain this using LocalLifecycleOwner.current.

Controlling Ad Visibility

To ensure a smooth user experience, it is best practice to only show banner ads once the Empower SDK has finished its initial setup and is ready to display ads. The SDK will notify your application when it's ready by broadcasting an Intent with the action EMAManager.ACTION_ADS_READY_TO_LOAD.

You can listen for this broadcast using a BroadcastReceiver and update a state variable to control the visibility of your EmpowerBannerAd composable.

Here is an example of how to implement this in your Activity:

File: MainActivity.kt

class MainActivity : ComponentActivity() {
    private val showStickyBanner = mutableStateOf(false)
    private val adsReadyReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            Log.d(TAG, "Empower SDK is ready to load ads.")
            // SDK is ready, show the ad
            showStickyBanner.value = true
            // Unregister receiver as it's no longer needed
            unregisterAdsReceiver()
        }
    }
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            YourAppTheme {
                BannerScreen(
                    loadStickyBanner = showStickyBanner.value,
                    // ...
                )
            }
        }
        registerSDKAdsReceiver()
    }
    @SuppressLint("UnspecifiedRegisterReceiverFlag")
    private fun registerSDKAdsReceiver() {
        val filter = IntentFilter(EMAManager.ACTION_ADS_READY_TO_LOAD)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
            registerReceiver(adsReadyReceiver, filter, RECEIVER_NOT_EXPORTED)
        } else {
            registerReceiver(adsReadyReceiver, filter)
        }
    }
    private fun unregisterAdsReceiver() {
        try {
            unregisterReceiver(adsReadyReceiver)
        } catch (e: Exception) {
            Log.e(TAG, "Error unregistering ads receiver: ${e.message}")
        }
    }
    override fun onDestroy() {
        super.onStop()
        unregisterAdsReceiver()
    }
}

Then, in your screen's composable, you can use this state to conditionally display the banner:

File: BannerScreen.kt

@Composable
fun BannerScreen(
    modifier: Modifier = Modifier,
    loadStickyBanner: Boolean,
    // ...
) {
    Box(modifier = modifier.fillMaxSize()) {
        // ... your screen content ...
        if (loadStickyBanner) {
            val context = LocalContext.current
            val lifecycleOwner = LocalLifecycleOwner.current
            EmpowerBannerAd(
                modifier = Modifier.align(Alignment.BottomCenter),
                zoneId = "YOUR_ZONE_ID",
                context = context,
                lifecycleOwner = lifecycleOwner
            )
        }
    }
}

Lifecycle Management

The EmpowerBannerAd composable is designed to handle the ad's lifecycle automatically. It uses a DisposableEffect to ensure that the ad is loaded when the composable enters the composition and properly destroyed when it leaves the composition. This prevents memory leaks and ensures that resources are managed efficiently without any manual intervention from your side.

Interstitial Ad

Interstitial ads are full-screen ads that cover the interface of their host app.

Full Example

Java

public class MyActivity extends AppCompatActivity implements AdStatusListener {
    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_sample);
        EMAManager.loadInterstitialAd(zoneId, listener);
    }
    @Override
    public void empowerInterstitialStatusChanged(@NonNull DFPInterstitialManager manager) {
        AdStatusListener.super. empowerInterstitialStatusChanged(manager);
        if(manager.getStatus().equals(AdStatus.READY)) {
            EMAManager.showInterstitial();
        }
    }
}

Kotlin

class MyActivity : AppCompatActivity(), AdStatusListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_sample)
        EMAManager.loadInterstitial(zoneId, listener)
    }
    override fun empowerInterstitialStatusChanged(manager: EmpowerInterstitialManager) {
        super.DFPInterstitialStatusChanged(manager)
        if(manager.status == AdStatus.READY) {
            EMAManager.showInterstitial()
        }
    }
}

By setting InterstitialDisplayManager's listener you can listen to the status events of interstitial ads. These events are:

AdStatus.READY: interstitial is ready for display.
AdStatus.FAILED: insterstitial is failed to load an ad.
AdStatus.PRESENT: interstitial is displayed and is on screen.
AdStatus.WILL_LEAVE: interstitial is redirecting user to a URL.
AdStatus.USED: interstitial is dismissed and needs reloading for another display

Rewarded Ads

Rewarded ads are the ads where users have the option of interacting with in exchange for in-app rewards.

Before you load and show a rewarded ad you must set EMASettings.instance.activity = currentActivity and the listener for the status of ad RewardedAdDisplayManager.instance.listener = this.

Full Example

Java

public class MyActivity extends AppCompatActivity implements AdStatusListener {
    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_sample);
        EMAManager.loadRewardedAd(zoneId, listener);
    }
    @Override public void rewardedStatusChanged(manager: EmpowerRewardedManager) {
        if(manager.getStatus().equals(AdStatus.READY)) {
            EMAManager.showRewarded(zoneId, this);
        }
    }
}

Kotlin

class MyActivity : AppCompatActivity(), AdStatusListener {
    override fun onCreate() {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_sample)
        EMAManager.loadRewardedAd(zoneId, listener)
    }
    override fun rewardedStatusChanged(manager: RewardedAdManager) {
        super.rewardedStatusChanged(manager)
        if(manager.status == AdStatus.READY) {
            EMAManager.showRewarded(zoneId, this)
        }
    }
}

By setting RewardedAdDisplayManager's listener you can listen to the status events of rewarded ads. These events are:

AdStatus.READY: rewarded is ready for display.
AdStatus.FAILED: rewarded ad is failed to load.
AdStatus.OPENED: rewarded ad is started to play and is on screen.
AdStatus.REWARDED: user complete playing and earns reward.
AdStatus.CLOSED: rewarded ad is closed either by user or complete playing.

#Banner Ads

#Views (XML & Code)

#Java

#Kotlin

#Java/Kotlin Usage

#Java

#Kotlin

#Jetpack Compose

#Compose Usage

#Parameters

#Controlling Ad Visibility

#Lifecycle Management

#Interstitial Ad

#Full Example

#Java

#Kotlin

#Rewarded Ads

#Full Example

#Java

#Kotlin

Banner Ads

Views (XML & Code)

Java

Kotlin

Java/Kotlin Usage

Java

Kotlin

Jetpack Compose

Compose Usage

Parameters

Controlling Ad Visibility

Lifecycle Management

Interstitial Ad

Full Example

Java

Kotlin

Rewarded Ads

Full Example

Java

Kotlin