Android SDK 9

Requirements

  • FairBid works on Android 4.1 (API Level 16) and higher
  • When using FairBid 1.0 or higher, you will need to use Fyber's maven repository (for more details, see # Step 3. Add the FairBid SDK to your project)

Step 1. Configure Dynamic Documentation

Select the version of the FairBid SDK you wish to view documentation for, and then select the networks you are integrating. The documentation on this page will update with specific instructions that may apply to your selections.

Network Selection:

Step 2. Download the SDK

The SDK includes FairBid, as well as wrappers for all 3rd-party networks.

SDK v9.50.0

Step 3. Add the FairBid SDK to your project

When using FairBid 1.0 or higher, you will need to use Fyber's maven repository and add the following to your gradle build: Sample code (adding the repository ):

repositories {
    maven {
        url  "https://fyber.bintray.com/fairbid-maven" 
    }
}

You will also need to add the following dependency: Sample code (Fairbid SDK depedency):

implementation 'com.fyber:fairbid:9.50.0

You can copy this code directly from the readme file which is included in the SDK you have downloaded

Important! When targeting Android P please note : For best performing video Ads please add an exception rule to 'localhost' as done in the following example.

Example of a config file for the 'network security config':

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="user" />
        </trust-anchors>
    </base-config>
</network-security-config>

Step 4. Add 3rd-party SDKs to your project

AdColony

AdMob

AppLovin

Chartboost

Domob

Facebook Audience Network

Fractional Media

Fyber Direct

HyprMX

InMobi

ironSource

Leadbolt

MoPub

Tapjoy

UnityAds

Vungle

If you haven't already, use our Integration Wizard to setup the 3rd-party networks you want to use with mediation.

The FairBid SDK will automatically detect and initialize the SDKs from 3rd-party networks. Some 3rd-party networks fail when initialized multiple times. Please do not initialize or otherwise directly interact with 3rd-party networks mediated by FairBid.

Step 5. Modify your Android Manifest

Mandatory Permissions

Add the following permissions to your AndroidManifest.xml:



Optional Permissions

The following permissions are not required for our SDK and 3rd-party SDKs to function, but including them in your AndroidManifest.xml may result in improved eCPM and user experience:



Activities

Add the following activities to your AndroidManifest.xml:



Google Play Services

The Google Play Services SDK must be added to your project for these networks. Follow Google's documentation on integrating the Google Play Services SDK into your app. Only the Ads and Location APIs need to be included. If you are using a Gradle build system with Android Studio adding the following to build.gradle should suffice:

implementation 'com.google.android.gms:play-services-ads:11.+'
implementation 'com.google.android.gms:play-services-location:11.+'

Hardware Acceleration

Add an attribute to the <application> tag to enable hardware acceleration:

<application android:hardwareAccelerated="true" ...>

Step 6. Adding User Consent

The General Data Protection Regulation requires you to scope your user's consent. A user is within the GDPR scope for your app when one or all of the following apply:

  • The user is currently located in the EU
  • The user has registered with the app as an EU resident
  • The app is specifically targeted to EU users

Once you have collected the user’s consent, you can pass it onto the SDK using the following API:

HeyzapAds.setGdprConsent(isGdprConsentGiven, context);

isGdprConsentGiven is a boolean. It is true if you have the user’s consent. If you do not have the user's consent, it is false. context is a valid Android Context.

If you don’t pass the user’s consent to the SDK, only contextual ads will be shown to that user.

We recommend that the first time you gather the user’s consent, you pass it onto the SDK before starting the SDK. The SDK will then take the user’s consent into consideration when initializing. In the following sessions, you will only need to call the API if the user updates his or her consent.

Step 7. Initialize the SDK

In your root Activity, start the FairBid SDK:

import com.heyzap.sdk.ads.HeyzapAds;

Activity activity = this; // must be an Activity
// Your Publisher ID is: <PUBLISHER ID>
HeyzapAds.start("<PUBLISHER ID>", activity);

Step 8: Test your 3rd-Party Integrations (Optional)

The mediation SDK comes with a Mediation Test Suite that you can use to test each of the networks you've chosen:

The first screen lets you isolate a network to test its integration with the FairBid SDK. Once you choose a network, you'll see if:

  1. The network is installed correctly.
  2. The network has valid credentials on your dashboard.
  3. The network is enabled on your dashboard.

To use the Mediation Test Suite, call this method after starting the SDK:

HeyzapAds.startTestActivity(activity);

At this point, you should launch the Mediation Test Suite and verify that each network you want to use has the correct credentials and shows ads correctly.

Step 9. Show Ads

Methods you call on the FairBid SDK will automatically dispatch to your enabled 3rd-party SDKs; a call to display will iterate over ad networks in order of expected CPM until it finds one that has an ad, optimizing CPM and fill rate. Use the code below to display your preferred ad format:

Interstitial Ads

import com.heyzap.sdk.ads.InterstitialAd;

// InterstitialAds are automatically fetched from our server
InterstitialAd.display(this);

Video Ads

Unlike interstitial ads, video ads are not pre-cached automatically. They must be fetched manually. Depending on the available internet connection, it may take some time to fully download the necessary assets, so it is strongly recommended fetching at the earliest point in your application lifecycle, and following the view of any video ad.

import com.heyzap.sdk.ads.VideoAd;

// As early as possible, and after showing each video ad, call fetch
VideoAd.fetch();

Later, such as after a level is completed, you can check if the ad has fetched, and display the ad if it is available.

if (VideoAd.isAvailable()) {
    VideoAd.display(this);
}

Rewarded Video Ads

Unlike interstitial ads, video ads are not pre-cached automatically. They must be fetched manually. Depending on the available internet connection, it may take some time to fully download the necessary assets, so it is strongly recommended fetching at the earliest point in your application lifecycle, and following the view of any video ad.

import com.heyzap.sdk.ads.IncentivizedAd;

// As early as possible, and after showing a rewarded video, call fetch
IncentivizedAd.fetch();

Later, such as after a level is completed, you can check if the ad has fetched, and display the ad if it is available.

if (IncentivizedAd.isAvailable()) {
    IncentivizedAd.display(this);
}

Banner Ads

FairBid offers banner ads through its in-house network, FairBid Exchange. We also mediate banners from AdMob, Facebook Audience Network, Mopub, and InMobi.

Note: Most banner networks have a setting on their dashboard to automatically refresh at a given time interval. If you want to use this feature, it is strongly recommended that you use the same time interval on all of the banner networks you are using. Different refresh rates for different networks can result in confusing impression statistics.

import com.heyzap.sdk.ads.BannerAdView;

private BannerAdView bannerAdView;

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...

    Activity activity = this; // Must be an Activity.
    bannerAdView = new BannerAdView(activity);

    // This must be some view in your layout.
    FrameLayout bannerWrapper = (FrameLayout) findViewById(R.id.banner_wrapper);

    // Add the banner ad view to the wrapper.
    bannerWrapper.addView(bannerAdView);

    // Load the banner ad.
    bannerAdView.load();
}

You should also destroy the banner ad view in the onDestroy method of your Activity.

@Override
protected void onDestroy() {
  bannerAdView.destroy();
  super.onDestroy();
}

Offer Wall Ads

The FairBid SDK provides access to the Fyber Offer Wall as of SDK version 9.12.0. The Offer Wall allows your users to complete certain activities in exchange for in-game currency.

Fetch

To fetch an Offer Wall ad:

OfferWall.fetch("default");

Show

To show an Offer Wall ad:

  OfferWall.OfferWallOptions offerWallOptions = new OfferWall.OfferWallOptions();
  offerWallOptions.closeOnRedirect = true; // auto-close after first offer interaction?
  OfferWall.display(this, "default", offerWallOptions);

See our detailed Offer Wall docs for more code examples on how to reward the user for offer wall interactions.

The Back Button

Some networks need a handler to the back button, FairBid proxies this in with a single function which can be used like this:

@Override
public void onBackPressed(){
    if(HeyzapAds.onBackPressed()){
        return;
    }
    //put your normal onBackPressed code here 
}

All good? Head over to your mediation dashboard to view revenue, impressions, eCPM, network credentials, and more.


More Information:

To learn more about Native Ads, click here.
To view an Example App, click here.
To go to basic Android SDK setup, click here.
To view Advanced Features, click here.