Skip to content

pranavpandey/dynamic-ads

Repository files navigation

Dynamic Ads

License Release

A GDPR-compliant library to show ads via Google AdMob on Android 4.1 (API 16) and above.

It uses AndroidX so, first migrate your project to AndroidX.
It is dependent on Java 8 due to the dependency on Dynamic Utils.
Since v1.3.0, it is targeting Java 17 to provide maximum compatibility.
Since v1.4.0, the minimum SDK is Android 4.4 (API 19) to comply with the latest policies.


Contents


Installation

It can be installed by adding the following dependency to your build.gradle file:

dependencies {
  // For AndroidX enabled projects.
  implementation 'com.pranavpandey.android:dynamic-ads:1.4.0'
}

Usage

It supports various ad formats as mentioned in the official Google AdMob guide. Please sign in to or sign up for an AdMob account first.

For a complete reference, please read the documentation.

Initialize

DynamicAds must be initialized once before accessing its methods. Dynamic ad formats do that automatically before doing any operations but it should be done manually if anything has to be done before.

// Initialize with application context.
DynamicAds.initializeInstance(applicationContext);

Host

BaseAdListener is the base class that an ad host like an activity must implement. It guides the internal framework about how and when an ad should be displayed.

It is used to create various factory listeners to show different ad formats and they should be implemented according to the requirements.

Consent

It provides built-in support for the consent form required to be shown in GDPR regions before initializing any of the ads. It uses User Messaging Platform (UMP) underneath to do all the heavy lifting and provides a simple yet customizable interface.

// Show a consent form.
DynamicAds.getInstance()
        // Set the consent request parameters required to load the consent information.
        .setConsentRequestParameters(consentRequestParameters)
        // Try to show the consent form if available
        .showConsentForm(dynamicAdListener);

// Other methods related to the consent form.
DynamicAds.getInstance()
        // Checks whether a consent information is available.
        .isConsentInformationAvailable()
        // Checks whether a consent form is available.
        .isConsentFormAvailable()
        // Checks whether a consent form is visible to the user.
        .isConsentFormVisible()
        // Checks whether a consent is required from the user.
        .isConsentRequired()
        // Returns the status of the consent information.
        .getConsetStatus();

Dynamic Ad

DynamicAd is the base class to implement various ad formats.

/**
 * An activity to host a dynamic ad.
 */
public AdHostActivity extends Activity implements BannerAdListener {
    
    ...
        
    // Initialize the banner ad.
    mDynamicBannerAd = new DynamicBannerAd(AD_UNIT_ID, this) {
        ...
    
        @Override
        public @NonNull AdRequest getAdRequest() {
            return new AdRequest.Builder().build();
        }
    
        @Override
        public @NonNull RequestConfiguration getAdRequestConfigurations() {
            return MobileAds.getRequestConfiguration().toBuilder()
                    .setTagForChildDirectedTreatment(
                    RequestConfiguration.TAG_FOR_CHILD_DIRECTED_TREATMENT_TRUE)
                    .setTagForUnderAgeOfConsent(
                    RequestConfiguration.TAG_FOR_UNDER_AGE_OF_CONSENT_TRUE)
                    .setMaxAdContentRating(RequestConfiguration.MAX_AD_CONTENT_RATING_G)
                    .build();
        }
          
        ...
    };

    @Override
    public @NonNull Context getAdContext() {
        // Return context for this host.
        return this;
    }

    @Override
    public boolean isAdEnabled() {
        // Ads are enabled for this host.
        return true;
    }
    
    ...

    @Override
    public void onAdDisplay(@NonNull AdView adView) {
        // Add the ad view to a container to make it visible.
        DynamicViewUtils.addView(container, adView, true);
    }
    
    ...

    @Override
    public void onResume() {
        super.onResume();

        // Resume a dynamic ad if supported.
        DynamicAds.onAdResume(mDynamicBannerAd);
    }

    @Override
    public void onPause() {
        // Pause a dynamic ad if supported.
        DynamicAds.onAdPause(mDynamicBannerAd);
        super.onPause();
    }

    @Override
    public void onDestroy() {
        // Destroy a dynamic ad if supported.
        DynamicAds.onAdDestroy(mDynamicBannerAd);
        super.onDestroy();
    }
}

Sponsor

Please become a sponsor to get a detailed guide and priority support.

Dependency

It depends on the dynamic-utils to perform various internal operations. So, its functions can also be used to perform other useful operations.


Author

Pranav Pandey

GitHub Follow on Twitter Donate via PayPal


License

Copyright 2022-2024 Pranav Pandey

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.