Pocket Media Native Ads open source library for Android
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.buildscript
Supporting files
adapters
demoApp
gradle
javadoc
nativeadslib
.gitignore
.travis.yml
LICENSE
README.md
build.gradle
changelog.md
codecov.yml
gradlew
gradlew.bat
mopub.md
settings.gradle

README.md

PocketMedia: Android NativeAds library

Code Climate Build Status codecov Gitter Maven Central Javadocs Gitter

This open-source library allows developers to easily show ads provided by PocketMedia natively in their apps. While the traditional way of advertising in mobile applications usually involves a disruption in natural user-flow to show the ad (Interstitial ads, banners, etc.) this native solution allows the ads to be integrated in the context where they will be displayed. That in turn makes it less intrusive for the user experience.

The library comes with standard ad units (ways of displaying the ad). You are encouraged to extend/copy these into project and and customize them to your liking, specially to match your application look and feel. This method is called using the NativeAdsAdapter - and requires just a few lines of code to start using it.

The alternative solution is using the library to just do the network calls and use the NativeAd (Class) model. Using these core functionalities, you are able to write your own custom ad units and manipulate them in any way that fits your app. This method is called manual integration.

Requirements

In order to use the library and have monetization tracking you need to get an advertiser token from Pocket Media. You can get it online, at our sign up page:

LandingPage 2016-02-15 10-19-32.png

Building the demo

To run the example project, just clone the repo and import it into Android Studio. Once imported, you will find two different modules: the demoApp, and the nativeAds library project.

ProjectOverview.png

Sample projects

PlayStore Pocket Media Native Ads Demo contained in this project is published on the PlayStore. Install and test it out :)

Installation

PocketMediaNativeAds is available through Maven Central. This repository is already included in the default jcenter() repository. In case you don't have it, you might need to add the repo:

repositories {
    jcenter()
}

And the library dependency:

 dependencies {
     compile 'mobi.pocketmedia:nativeadslib:1.3.2'
 }

Usage

There are several ways to implement native ads in your application. Firstly, there is the NativeAdsAdapter which will take care of the integration for you. This adapter extends the BaseAdapter class and mixes your items of the existing adapter with native adListings. For maximum customizability however there is always the option to manually integrate the NativeAds with a custom view - and that will allow you to shape and place the ads in any way you can think of in your app.

For both methods the parameters used are:

  • placement key, to be generated in the user dashboard
  • NativeAdsRequestListener, to receive the event callbacks as the ads are ready.

Further documentation is available on our website.

NativeAdsAdapter Integration

The NativeAdsAdapter allows to easily show native ads in your List views. Using the a adPositionHandler you can specify the positions of the ads in the list. Prewritten examples are the MarginAdPositionHandler and PredefinedAdPositionHandler.

	nativeAdRequest = new NativeAdRequest(getActivity().getApplicationContext(), null, "4bea87cd5549527b10d2886061121d0f8e22071b");
	AdPositionHandler adPositionHandler;
    adPositionHandler = new MarginAdPositionHandler(2);
    /*
    another option would be:
    AdPositionHandler = new PredefinedAdPositionHandler(new int[]{2, 4, 8});
    */

    nativeAdsAdapter = new NativeAdsAdapter(
            adapter,
            getActivity(),
            adPositionHandler,
            R.layout.custom_native_ad_layout_simple_item,
            R.id.native_ad_icon,
            R.id.native_ad_title,
            R.id.native_ad_description,
            R.id.native_ad_image,
            R.id.install_button);
    myListView.setAdapter(nativeAdsAdapter);

    nativeAdRequest.setListener(nativeAdsAdapter);
    nativeAdRequest.retrieveAds(10, imageType);

Manual Integration

You could also opt for just using the library to do the network request and manually integrate the ads. To do so create a new listener class that implements NativeAdsRequestListener and call NativeAdRequest to initiate an ad request call.

In this repo you will find an example of the usage of the NativeAds library in your own app. It's intended to be totally customizable by you, and that's why provide you the source code. The only thing we need from is to start a Native Ads Request, and provide a listener for the callback - so you can receive the ads information and display them integrated in your app.

One example implementation to retrieve the ads (not yet displaying them) could be:

    /**
     * Method to download the ads. Initializing the ad request.
     */
    private void downloadAds() {
    
        NativeAdRequest nativeAdRequest = new NativeAdRequest(
                this,
                this,
               "4bea87cd5549527b10d2886061121d0f8e22071b");
        nativeAdRequest.retrieveAds(1, NativeAdFilters.ImageType.allImages);
    }
    
    @Override
    public void onAdRequestSuccess(List<NativeAd> ads) {
        Log.i("onAdRequestSuccess", "onAdRequestSuccess");
        this.nativeAds = ads;
        // process them to show them to the user
    }

    @Override
    public void onAdRequestError(Exception error) {
        Log.e("onAdRequestError", "onAdRequestError");
        // silently handle the exception
    }

Make sure you modify the ad placement token to include your own (in the sample app, 4bea87cd5549527b10d2886061121d0f8e22071b). Otherwise we cannot track your ad displays or conversions!

And after that, we provide you with two callbacks to be aware of the status of your ads request (success/error), as you can check in the NativeAdsRequestListener:

  1. onAdRequestSuccess
  2. onAdRequestError

In the usual situation, you will be displaying the ads in the onAdRequestSuccess, with the layout of your choice (provided by the library, or customised).

Check the CustomIntegrationFragment class in the DemoApp for further code and reference implementation.

Opening the URL

In the interface NativeAdOpenerInterface we specify the method that the implementation of an Ad Opener should implement. We provide one implementation in NativeAdWebViewOpener - it will take charge of opening the ad click URL in an invisible webview, until we reach the final URL that the user should see.

The reason why this is done this way is because the urls of the ads point to tracking domains that will save the clicks of your users for us to know what it was your user who clicked on an ad. To improve the user experience, this process happens in-app.

The key method to open an ad in a seamless way within your app (think of the way Facebook opens their ads, for example) is this:

           installButton.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(View v) {
                    ad.openAdUrl(new NativeAdWebViewOpener(activity));
                }
            });
            installButton.setText(ad.getActionText());

By handling the click event with the new instance of NativeAdWebViewOpener we ensure the ad will be open with the nicest user experience, taking the user smoothly from your app to Google Play or the browser.

MoPuB's Network Mediation

If you've already got the MoPub SDK integrated, you can easily make use of this library. Do this by following the plug-and-play MoPub+PocketMedia instructions.

Displaying an ad

To display the Ad, you will want to take a look to the NativeAd class, containing the different data about the offers you will display:

  • campaignName: the title of the campaign, usually a few words.
  • campaignDescription: the description of the campaign, usually a short paragraph with a few lines of text.
  • clickURL: the URL that must be opened when the user clicks in the ad
  • appStoreUrl: the preview URL, where the user will be taken. It could be empty (it's just the preview, you must not open this URL but the click url).
  • actionText: the text that the "action" button should have. It will be something like "Install", "Get now", "Get offer",...
  • campaignImage: this property should be accessed trough the getImageUrl(), as the field can come in two different attributes from the API (campaignImage and defaultIcon). It's the default icon.
  • images: an object holding the different assets a campaign might have (icons, high resolution icons, banners, and bigger images).
  • shouldBeManagedExernally: indicates if the offer should be taken directly to the browser (usually, because it's not an app install offer, but a campaign leading to a landing page). photo18534536685136897.jpg

Author

Pocket Media Tech Team, support@pocketmedia.mobi. Feel free to contact us for any suggestion improvements, doubts or questions you might have. We will also assist you with the implementation.

We work for you, we want you to be able to implement the ads in 5 minutes and start monetizing your audience with a totally native and tailored experience! Tell us what you are missing, what else you need our library to make for you - and it will happen.

Contributing

If you'd like to contribute to this project. Please feel free to fork it and bring over your changes in the form of a pull request. If you don't feel like solving the problem yourself, feel free to report it to us, and we will take it to our backlog and try to solve it as soon as possible.

License

PocketMediaNativeAds is available under the MIT license. See the LICENSE file for more info.