v6.25.0 - Android Yieldlove SDK Integration Manual

1 1. Overview
2 2. Before you start
3 3. Try Out Our Example App
4 4. Use Java 17 in Your Project
5 5. Add SDK Dependency to Your Project
6 6. Set Up Application Name
7 7. Request a banner ad
8 8. Banner Destroy
9 9. Request An Interstitial
10 10. Rewarded Ad
11 11. Quick Start: Testing Configuration
12 12. Get Ad Sizes For Specific ‘adSlot’ From External Config
13 13. Ad Targeting
14 14. Clear Configuration Cache
15 15. Banner Ad Auto-Refresh
16 16. Debug Info Panel

1. Overview

To show a banner ad, perform the following steps:

These steps are described in more detail in the following paragraphs.

For interstitial ads the procedure is the same, perform steps 1 to 3 and then go to the Interstitial section described here

2. Before you start

You need to set an APPLICATION_NAME (assigned only once) and a PUBLISHER_CALL_STRING (which represents ad slots). These values must be provided when requesting an ad using the SDK. Please contact your Ströer account manager to obtain the APPLICATION_NAME and PUBLISHER_CALL_STRING.

If you want to start testing before your ad slots are fully set up, we can provide you with test configurations.

The PUBLISHER_CALL_STRING typically takes values like "b1", "b2", "b3", or "interstitial", depending on your configuration. You can also combine this string with a ZONE, which helps ad servers and SSPs (Supply-Side Platforms) organize and serve ads contextually.

Example:

"home_b1" → Ad slot "b1" within the "home" zone
"content_b1" → Ad slot "b1" within the "content" zone

3. Try Out Our Example App

We invite you to explore our example app.

It already contains a test configuration, which comes pre-configured with test settings. This allows you to try it out even before receiving your APPLICATION_NAME and PUBLISHER_CALL_STRING.

The example app also helps clarify key implementation details. Once you receive your configuration, you can modify the app’s settings and run it with your setup.

4. Use Java 17 in Your Project

To ensure compatibility, configure your project to use Java 17 by adding the following settings to your Gradle file:

compileOptions {
   targetCompatibility = "17"
}

5. Add SDK Dependency to Your Project

Using Gradle

For existing projects that have already been initialized and include this setting in build.gradle, add the following dependency block:

allprojects {
	repositories {
	    mavenCentral()
	    google()
	    maven { url 'https://slabs-yieldlove-ad-integration.s3.eu-central-1.amazonaws.com/android' }
	}
}

The following block is useful for newly set up projects that have repositories specified in settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://slabs-yieldlove-ad-integration.s3.eu-central-1.amazonaws.com/android'}
    }
}

Use our libraries as dependencies:

implementation 'com.yieldlove.adIntegration:yieldlove:6.25.0'
implementation 'com.yieldlove.adIntegration:cmp:4.9.0' // use CMP lib only if you use our CMP solution

For other package management tools, see page on Bintray

6. Set Up Application Name

Before requesting an ad, you must set the APPLICATION_NAME property. This needs to be done only once, ideally in the main application constructor.

Yieldlove.setApplicationName("APPLICATION_NAME");

7. Request a banner ad

7.1. Create a view element YieldloveAdView in your layout

To display a banner ad, add YieldloveAdView to the layout where you want the ad to appear, assigning it an ID for reference..

<com.yieldlove.adIntegration.YieldloveAdView
    android:id="@+id/adContainer"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

7.2. Using an EventHandler

Replace the PUBLISHER_CALL_STRING and APPLICATION_NAME placeholders with your actual values. Banner sizes and key-value targeting parameters will be retrieved dynamically from an external source.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Set the application name only once
    Yieldlove.setApplicationName("your_actual_application_name");

    final ViewGroup adContainer = findViewById(R.id.adContainer); // Follow camelCase convention

    try {
        YieldloveBannerAd ad = new YieldloveBannerAd(this);

        // Load the ad with actual publisher call string
        ad.load("home_b1", new YieldloveBannerAdListener() { // Replace with actual ID

            @Override
            public AdManagerAdRequest.Builder onAdRequestBuild() {
                // If needed, add custom parameters like content URL
                // AdManagerAdRequest.Builder builder = new AdManagerAdRequest.Builder();
                // builder.setContentUrl("http://www.example.com");
                // return builder;
                return null; // Keep null if no modifications needed
            }

            @Override
            public void onAdLoaded(YieldloveBannerAdView banner) {
                adContainer.removeAllViews(); // Ensure no duplicates or the old banner. 
                adContainer.addView(banner);
            }

            @Override
            public void onAdFailedToLoad(YieldloveBannerAdView banner, YieldloveException ex) {
                Log.e("YieldloveAd", "Ad failed to load: " + ex.getMessage());
            }

            @Override
            public void onAdOpened(YieldloveBannerAdView banner) {
                Log.d("YieldloveAd", "Ad opened.");
            }

            @Override
            public void onAdClosed(YieldloveBannerAdView banner) {
                Log.d("YieldloveAd", "Ad closed.");
            }

            @Override
            public void onAdClicked(YieldloveBannerAdView banner) {
                Log.d("YieldloveAd", "Ad clicked.");
            }

            @Override
            public void onAdImpression(YieldloveBannerAdView banner) {
                Log.d("YieldloveAd", "Ad impression registered.");
            }
        });

    } catch (YieldloveException e) {
        Log.e("YieldloveAd", "Error initializing ad", e);
    }
}

8. Banner Destroy

Destroy the banner when leaving the page that contains the ad slot or when the ad needs to be hidden. Keeping unused banners active can slow down ad loading, especially if multiple slots exist on the page.

YieldloveBannerAd ad = new YieldloveBannerAd(this);
//...
ad.destroy();

8.1. Is Loading In Progress?

If you know that the same ad slot will be used again soon, you can check if a banner is already loading. Instead of destroying and reloading it, simply wait for the ad to finish loading.

YieldloveBannerAd ad = new YieldloveBannerAd(this);
//...
if(ad.isLoadingInProgress()){
//...
}

9. Request An Interstitial

An interstitial ad is a full-screen advertisement that appears between content transitions in an app or website. Unlike banner ads, interstitial ads cover the entire screen, requiring user interaction (such as closing or clicking) before returning to the app experience. Here are the characteristics of Interstitial Ads.

Unlike banners, interstitial ads take up the entire screen, making them more noticeable.
Typically shown between levels in a game, between articles, or when navigating between pages.
Helps reduce disruption to the user experience.
Users must either close or engage with the ad before continuing.
Example interactions:
- Clicking on the ad (opens external link or app store)
Due to its visibility, interstitial ads tend to have higher click-through rates (CTR) and generate more revenue compared to banners.

Use the following code to display an interstitial ad. Replace the PUBLISHER_CALL_STRING and APPLICATION_NAME placeholders with your actual values. Key-value targeting will be dynamically retrieved from an external source.

9.1 Interstitial Example Using an EventHandler

public void showInterstitialAd() {
    // Set the application name (should be done once in the app lifecycle)
    Yieldlove.setApplicationName("your_actual_application_name");

    try {
        YieldloveInterstitialAd ad = new YieldloveInterstitialAd(this);

        ad.load("your_actual_publisher_call_string", new YieldloveInterstitialAdListener() {

            @Override
            public AdManagerAdRequest.Builder onAdRequestBuild() {
                return null; // Modify if additional request parameters are needed
            }

            @Override
            public void onAdLoaded(YieldloveInterstitialAdView interstitial) {
                Log.d("YieldloveAd", "Interstitial ad loaded.");
                interstitial.show();

                // Retrieve and log ad source information
                AdSourceInfo source = interstitial.getAdSource();
                Log.d("YieldloveAd", "Ad Source: " + source);
            }

            @Override
            public void onAdFailedToLoad(YieldloveInterstitialAdView interstitial, YieldloveException exception) {
                Log.e("YieldloveAd", "Interstitial ad failed to load: " + exception.getMessage());
            }
        });

    } catch (YieldloveException e) {
        Log.e("YieldloveAd", "Error initializing interstitial ad", e);
    }
}

9.2 Set the FullScreenContentCallback

If you want to use FullScreenContentCallback (as described in the Google Mobile Ads library), you can set it inside the onAdLoaded callback like this:

public void showInterstitialAd() {
    // Set the application name (should be done once in the app lifecycle)
    Yieldlove.setApplicationName("your_actual_application_name");

    try {
        YieldloveInterstitialAd ad = new YieldloveInterstitialAd(this);

        ad.load("your_actual_publisher_call_string", new YieldloveInterstitialAdListener() {

            @Override
            public AdManagerAdRequest.Builder onAdRequestBuild() {
                return null; // Modify if additional request parameters are needed
            }

            @Override
            public void onAdLoaded(YieldloveInterstitialAdView interstitial) {
                Log.d("YieldloveAd", "Interstitial ad loaded.");

                // Set FullScreenContentCallback before showing the ad
                interstitial.setFullScreenContentCallback(new FullScreenContentCallback() {
                    @Override
                    public void onAdDismissedFullScreenContent() {
                        Log.d("YieldloveAd", "Interstitial ad dismissed.");
                    }

                    @Override
                    public void onAdFailedToShowFullScreenContent(AdError adError) {
                        Log.e("YieldloveAd", "Failed to show interstitial ad: " + adError.getMessage());
                    }

                    @Override
                    public void onAdShowedFullScreenContent() {
                        Log.d("YieldloveAd", "Interstitial ad is now showing.");
                    }

                    @Override
                    public void onAdClicked() {
                        Log.d("YieldloveAd", "Interstitial ad clicked.");
                    }

                    @Override
                    public void onAdImpression() {
                        Log.d("YieldloveAd", "Interstitial ad impression recorded.");
                    }
                });

                // Show the interstitial ad
                interstitial.show();

                // Retrieve and log ad source information
                AdSourceInfo source = interstitial.getAdSource();
                Log.d("YieldloveAd", "Ad Source: " + source);
            }

            @Override
            public void onAdFailedToLoad(YieldloveInterstitialAdView interstitial, YieldloveException exception) {
                Log.e("YieldloveAd", "Interstitial ad failed to load: " + exception.getMessage());
            }
        });

    } catch (YieldloveException e) {
        Log.e("YieldloveAd", "Error initializing interstitial ad", e);
    }
}

10. Rewarded Ad

A rewarded ad is a full-screen video ad that offers users a reward (e.g., in-game currency, extra lives, premium content) in exchange for watching the ad. Here are the characteristics of rewarded ads.

User-initiated: The user chooses to watch the ad in exchange for a reward.
Typically non-skippable (ensuring full ad view time).
Higher engagement rates than interstitial ads since users willingly interact.
Best for gaming apps, premium content unlocks, and app engagement strategies.

Use the following code to display a rewarded ad, replacing the PUBLISHER_CALL_STRING and APPLICATION_NAME placeholders with actual values. Key-value targeting will be dynamically fetched from an external source.

10.1 Rewarded Ad Example Using an EventHandler

public void showRewardedAd() {
    // Set the application name (should be set once in the app lifecycle)
    Yieldlove.setApplicationName("your_actual_application_name");

    try {
        YieldloveRewardedAd rewardedAd = new YieldloveRewardedAd(this);

        rewardedAd.load("your_actual_publisher_call_string", new YieldloveRewardedAdListener() {
            
            @Override
            public void onAdLoaded(@NonNull YieldloveRewardedAd rewardedAd) {
                Log.d("YieldloveAd", "Rewarded ad loaded.");
                rewardedAd.show();
            }

            @Override
            public void onUserEarnedReward(Reward reward) {
                Log.d("YieldloveAd", "User earned reward.");
            }

            @Override
            public void onAdFailedToLoad(@NonNull YieldloveException exception) {
                Log.e("YieldloveAd", "Rewarded ad failed to load: " + exception.getMessage());
            }
        });

    } catch (YieldloveException e) {
        Log.e("YieldloveAd", "Error initializing rewarded ad", e);
    }
}

11. Quick Start: Testing Configuration

By following the instructions above, developers can use the testing configuration below to start early implementation.

App Name: appDfpTest

Banner Ad Slot: "banner"

Large Banner Ad Slot: "banner?large"

Interstitial Ad Slot: "interstitial"

12. Get Ad Sizes For Specific ‘adSlot’ From External Config

To retrieve ad sizes for a specific ad slot from an external configuration, use the getAdSizes() method available on the YieldloveBannerAd object.

This method may return null if the specified SLOT_NAME is not found in the configuration.

YieldloveBannerAd ad = new YieldloveBannerAd(activity);

ad.getAdSizes("SLOT_NAME", (AdSize[] adSizes) -> {
    if (adSizes != null && adSizes.length > 0) {
        int width = adSizes[0].getWidth();
        int height = adSizes[0].getHeight();
        
        // Use width and height as needed
    }
});

13. Ad Targeting

Ad targeting is the process of delivering advertisements to a specific audience based on predefined criteria. It helps advertisers show ads to the right users at the right time, increasing engagement, relevance, and conversion rates.

Types of Ad Targeting

There are several methods of ad targeting used in digital advertising to reach the right audience effectively.

Contextual Targeting

Ads are displayed based on the content of the website or app.

Uses keywords, topics, or page context to match relevant ads.

Example: Showing car insurance ads on a website about automobiles.

Behavioral Targeting

Ads are shown based on a user’s past behavior, such as browsing history, clicks, and searches.

Uses cookies, tracking pixels, and device IDs to collect data.

Example: A user who searched for laptops sees ads for electronics and accessories.

Demographic Targeting

Ads are targeted based on attributes such as age, gender, income, and education.

Example: A luxury watch brand might target men aged 30-50 with high income.

Geographic (Geo) Targeting

Ads are displayed based on location, including country, city, ZIP code, or GPS data.

Example: A food delivery app shows different ads in New York compared to Los Angeles.

Interest-Based Targeting

Ads are shown to users based on their interests, such as sports, technology, or fashion.

Data is collected from social media activity, website visits, or user profiles.

Example: A sportswear brand targets users interested in fitness and running.

Retargeting (Remarketing)

Ads are shown to users who previously interacted with a brand but did not convert.

Uses tracking cookies to remind users about products they viewed.

Example: A user who visited an online store but did not purchase a phone sees ads for the same phone later.

Device and Platform Targeting

Ads are shown based on the type of device, such as mobile, tablet, or desktop, and the operating system, such as iOS or Android.

Example: A mobile game app displays ads only to iOS users.

Time-Based Targeting

Ads are displayed at specific times of the day or week when users are most active.

Example: A coffee shop runs ads promoting morning discounts between 7 AM and 10 AM.

13.1 Global Targeting

Global targeting allows you to set ad request properties that apply to all ads in your application. This ensures consistent targeting parameters across different ad placements without needing to define them for each ad request.

How It Works

Global targeting settings are applied to all ad requests, regardless of the ad slot or format.

Set as early as possible in the app lifecycle (e.g., during app initialization) to ensure all requests include the targeting parameters.

If a specific local targeting is set for an individual ad, it will override the global settings.

Map<String, List<String>> map = new HashMap<>();
map.put("userAge", List.of("25"));
map.put("userInterest", List.of("sports","technology","music"));
map.put("userLocation", List.of("New York"));

Yieldlove.setCustomTargeting(map);

We strongly recommend setting global targeting, especially when user consent is not given in the Consent Management Platform (CMP). In such cases, monetization performance improves when relevant contextual data, such as the Content URL, can be included in the ad request.

13.2. Local Targeting - adSlot/adView Specified

Local request settings can be defined within the AdListener. These settings take priority over global settings, meaning that if both local and global settings are applied, the local settings will override the global ones.

This approach allows properties to be configured individually for each ad request, providing greater flexibility and control over ad behavior.
In each listener (YieldloveBannerAdListener, YieldloveInterstitialAdListener), you must override the onAdRequestBuild() method to customize the ad request.

new YieldloveBannerAdListener() {
    //...
    @Override
    public AdManagerAdRequest.Builder onAdRequestBuild() {
        return new AdManagerAdRequest.Builder()
            .addCustomTargeting("adSlotVariable", "value")
            .setContentUrl("contentUrl")
            .addKeyword("testKeyWord");
    }
    //...
};

14. Clear Configuration Cache

The library maintains an extended configuration based on the application name, which is automatically updated at a defined interval. To refresh the configuration immediately, you can clear the configuration cache, prompting the library to download the latest configuration. This may take about 5-10 seconds to reload.

Yieldlove.clearConfigurationCache(activity)

15. Banner Ad Auto-Refresh

This feature allows banner ads to auto-refresh at a set interval, such as every 30 seconds. To enable this functionality in your app, please contact your Ströer account manager

16. Debug Info Panel

To enter ad debugging mode, press and hold three fingers on an ad for three to four seconds until a notification appears.

Ad Debugging Mode Features:

A debug info label appears in the top-left corner of a banner.

Tap the label to open a panel displaying debugging information about the ad.

Double-tap anywhere on the panel to copy the displayed text.

Force close and reopen the app to exit debugging mode.

Alternatively, you can enable debugging programmatically by setting:

Yieldlove.developerModeEnabled = true;

This flag is strictly for ad debugging and should not be enabled by default in builds intended for distribution.