1.1 Target Readers

This document is for Android developers who want to integrate ZPLAY Ads SDK into their product.

1.2 Development Environment

2.1 Choose third-party SDK

2.2 Download ZPLAY Ads SDK

Please download ZPLAY Ads SDK and add it to your project

2.3 Download third-party SDK

Please download third-party SDK and add it to your project according to instructions of the third-party platform

3.1 Add lib file

repositories {
	flatDir {
		dirs'libs'
	}
}
dependencies {
	compile(name： 'YumiAdsSDK_1.6.0-release'， ext： 'aar')
}							

About google_play_service project:

google_play_service is not mandatory, while some ad platforms need google_play_service, ZPLAY Ads does not. You need import this project into your project and use it as a library project, and add following code in tab <application> of your manifest.xml.

<meta-data android:name="com.google.android.gms.version" class="kix-line-break" android:value="@integer/google_play_services_version"/>

3.2 Add permission

Add the following permissions in manifest.xml of your project:

Mandatory：

Optional：

<uses-permission android：name="android.permission.ACCESS_FINE_LOCATION"/>	
<uses-permission android：name="android.permission.ACCESS_COARSE_LOCATION" />

3.3 Registered components

Add following in manifest.xml of your project:

4.1 Banner

Creat a ViewGroup as banner container, and add it in Activity.

Then call the code below:

//create YumiBanner object. Activity is the activity which you need to display banner ad.You need to create a YumiID on ZPLAY Ads. Auto indicates if the mode is automatic. 
//auto==true  Banner ads automatic rotation
//auto==flase  Banner ads manual rotation，call banner.requestYumiBanner() repeatedly to rotate
// If you are using ZPLAY Ads mediation alone, please enable ZPLAY Ads rotation, set the field as “true”; if you are using ZPLAY Ads in other mediations, to ensure ad performance, please disable ZPLAY Ads rotation, set the field as “false”.
 banner = new YumiBanner(activity， "YOUR_YUMI_ID"， auto);
//Set ViewGroup as banner container, set it along with size
// bannerContainer  Your ad container
// AdSize.BANNER_SIZE_AUTO  SDK automatically sets screen size as 320*50 or 728*90
// isMatchWindowWidth ==true Banner width equals screen width
banner.setBannerContainer(bannerContainer， AdSize.BANNER_SIZE_AUTO， isMatchWindowWidth);
//Start requesting ads, auto==true  The method needs to be called only once
banner.requestYumiBanner();

Implement in Activity lifecycle：

@Override
protected void onDestroy() {
	if (banner!= null) {
		banner.onDestory();
	}
	super.onDestroy();
}

4.2 Interstitial

Add the following code in onCreate method of Activity:

//Create YumiInterstitial object. Activity is the one you use to show interstitials, You need to create a YumiID on ZPLAY Ads. Auto indicates if the mode is automatic.
//auto==true  Automatically request the next ad, auto mode recommended to ensure ad performance
//auto==flase  Auto request disabled, to request please repeatedly call interstitial.requestYumiInterstitial()
// If you are using ZPLAY Ads, please enable ZPLAY Ads rotation, set the field as “true”.
 interstitial = new YumiInterstitial(activity， "YOUR_YUMI_ID"， auto);
 //Start requesting ads
interstitial.requestYumiInterstitial();

Call the following code when you need to show interstitial ads:

//Show immediately, if there is a pre-cached interstitial, immediately show the pop-up interstitial (Speed to pop up varies on different devices, there might be visual lag), if there isn't a pre-cached interstitial, show no ads and drop the impression opportunity until the next call.
if (interstitial != null) {
	interstitial.showInterstitial(false);
}
//Delayed display  If when you intend to show interstitial, it's still pre-caching, then delayed display allows SDK to wait for the pre-cach to complete, after completion it will show interstitial. Time waited is indefinite.
if (interstitial != null) {
	interstitial.showInterstitial(true);
}
//Cancel delayed display   If you need to do other operations when delayed display hasn't started, you need to call the following method to cancel this delayed display. After cancellation, interstitial won't be shown until the next call.
if (interstitial != null) {
	interstitial.cancelInterstitialDelayShown();
}

Implement in Activity lifecycle：

@Override
protected void onDestroy() {
	if (interstitial != null) {
		interstitial .onDestory();
	}
	super.onDestroy();
}

Because different platforms have different pop-up displays, you need to add the following code in onBackPressed()：

Note: please make sure you add this method in order not to confuse back key logic.

// please make sure you add this method in order to avoid confusing back key logic.
if (interstitial.onBackPressed()) {
	return ;
}
super.onBackPressed();

4.3 Rewarded Video

Add following code in onCreate method of Activity:

//  Create YumiInterstitial object. Activity is the one you use to show interstitials, YumiID is the app ID which is assigned to you by the platform, auto indicates if the mode is automatic.
media = new YumiMedia(activity， "YOUR_YUMI_ID");
//Start requesting ads.
media.requestYumiMedia();

Note: For every YumiMedia instantiation, the method to start requesting ads needs to be called only once.

To check if video is available, call the following code：

if (media!= null) {
	media. isMediaPrepared ();
}

When you need to show rewarded video, call the following code：

//Show immediately
if (media!= null) {
	media.showMedia();
}

Note：

1. Rewarded video is available after the above integration but rewards are still unavailable. To get rewards callback, please add listener to get rewards callback according to Advanced Features.

2. A new request for the next ad will be sent after the previous one has been closed or previous request has failed.

3. Method media.requestYumiMedia() needs to be called only once at the begining.

Implement in Activity lifecycle:

@Override
protected void onDestroy() {
	if (media != null) {
		media.onDestory();
	}
	super.onDestroy();
}

4.4 Splash

Add the following code in method onCreate of Activity：

//Create splash object. 
//activity used to show splash
//YumiID AppID assigned by the platform
// container:ad container
// width/height:width and height of ad container
// SplashADListener:ad callback listener
splashAD = new SplashAD(activity， YumiID， container， adwidth， adheight， SplashADListener); 

Call the following method in corresponding Activity lifecycle:

@Override
protected void onDestroy() {
	if (splashAD!= null) {
		splashAD.onDestory();
	}
	super.onDestroy();
}

5.1 Banner

5.1.1 Set ad status listener

If you need to listen to the lifecycle of banner ads, please call the following method after you create YumiBanner object:

// Set ad status listener.
banner.setBannerEventListener(bannerListener);

Regarding ad listener, you can instantiate an IYumiBannerListener, and add your own logic according to the callback. The callbacks are shown below:

onBannerPreparedFailed(LayerErrorCode errorCode)

Callback when caching fails. Reasons can be found through errorCode.getMsg()

onBannerPrepared()

Callback when caching succeeds.

onBannerExposure()

Callback when impression succeeds.

onBannerClosed()

Callback when Banner is closed.

onBannerClicked()

Callback when Banner is clicked.

Sample：

// Created banner ad status listener.
bannerListener = new IYumiBannerListener() {
	@Override
	public void onBannerPreparedFailed(LayerErrorCode errorCode) {
		// Callback when caching fails. Reasons can be found through errorCode.getMsg()
	}
	@Override
	public void onBannerPrepared() {
		//Callback when caching succeeds.
	}
	@Override
	public void onBannerExposure() {
		//Callback when impression succeeds.
	}
	@Override
	public void onBannerClosed() {
		//Callback when Banner is closed.
	}
	@Override
	public void onBannerClicked() {
		//Callback when Banner is clicked.
	}
};

5.1.2 Show and hide banner

Use the following methods to show and hide banner:

//Hide banner, pause rotation at the same time.
banner.dismissBanner();
//Resume to show banner, resume rotation at the same time.
banner.resumeBanner();

5.1.3 Banner ads automatically adapt to screen size

When you set banner ad container, you can use isMatchWindowWidth, a parameter of boolean type provided by ZPLAY Ads SDK. This parameter indicates if banner width has populated full screen. When it's true, banner width equals the screen width.

5.2 Interstitial

Set ad status listener

If you need to listen to the lifecycle of interstitial ads, please call the following method after you create YumiBanner object:

// Set ad status listener.
interstitial.setInterstitialEventListener(interstitialListener);

Regarding ad listener, you can instantiate an IYumiInterstitialListener, and add your own logic according to the callback. The callbacks are shown below:

onInterstitialPreparedFailed(LayerErrorCode error)

Callback when caching fails. Reason can be found through errorCode.getMsg()

onInterstitialPrepared()

Callback when loading succeeds.

Note: please do not call show interstitial method in this callback.

onInterstitialExposure()

Callback when impression succeeds.

onInterstitialClosed()

Callback when interstitial is closed.

onInterstitialClicked()

Callback when interstitial is clicked.

Sample：

// Set ad status listener.
interstitialListener = new IYumiInterstititalListener() {			
	@Override
	public void onInterstitialPreparedFailed(LayerErrorCode error) {
		// Callback when loading fails. Reason can be found through errorCode.getMsg()
	}			
	@Override
	public void onInterstitialPrepared() {
		// Callback when loading succeeds.
	}			
	@Override
	public void onInterstitialExposure() {
		// Callback when impression succeeds.
	}			
	@Override
	public void onInterstitialClosed() {
		// Callback when interstitial is closed.
	}			
	@Override
	public void onInterstitialClicked() {
		//Callback when interstitial is clicked.
	}
};

5.3 Rewarded Video

Set ad status listener

If you need to listen to the lifecycle of video ads, please call the following method after you create YumiBanner object:

// Set ad status listener.
media.setMediaEventListner(mediaListener);

Regarding ad listener, you can instantiate an IYumiMediaListener, and add your own logic according to the callback. The callbacks are shown below:

onMediaExposure()

Callback when impression succeeds

onMediaClosed()

Callback when rewarded video is closed

onMediaClicked()

Callback when rewarded video is clicked.

Note: this does not guarantee 100% callback due to platform differences.

onMediaIncentived()

Callback for rewards after rewarded video has been played completely.

Note: if the video has not been played completely, this callback won't be used. In addition, this method is always triggered after onInterstitialClosed().

Sample：

// Set ad status listener.
mediaListener = new IYumiMediaListener() {							
	@Override
	public void onMediaIncentived() {
		//Callback when reward is obtained		
        }			
	@Override
	public void onMediaExposure() {
		// Callback when impression succeeds.
	}			
	@Override
	public void onMediaClosed() {
		//Callback when interstitial is closed.			
	}			
	@Override
	public void onMediaClicked() {
		//Callback when interstitial is clicked.
	}
};

5.4 Splash

Set ad status listener

Regarding ad listener, you can instantiate a SplashADListener, and add your own logic according to the callback. The callbacks are shown below:

onSplashShow()

Callback when splash is shown

onSplashClose()

Callback when splash is closed

onSplashClick()

Callback when splash is clicked

onSplashFailed()

Callback when loading fails

Sample：

// Set ad status listener.
splashListener = new SplashADListener () {							
	@Override
	public void onSplashShow () {
		//Callback when splash is shown		
        }			
	@Override
	public void onSplashFailed () {
		//Callback when caching failed
	}			
	@Override
	public void onSplashClose () {
		//Callback when splash is closed				
	}			
	@Override
	public void onSplashClick () {
		//Callback when splash is clicked
	}
};

5.5 Test Mode

ZPLAY Ads SDK provideds a test mode to test your 3rd-party Integrations.

5.6 Permissions for Android 6.0 and newer versions

When the targetSdkVersion of your app is 23 or above, you can choose the following method to check permission and prompt for user authorization.

Note: default setting for this method is false, it won't prompt for user authorization and won't cause crash. If set as true, it will check permission and prompt for user authorization. This method should be called before the instantiated ads and android-support-v4.jar needs to be added.

YumiCheckPermission.runInCheckPermission(true);

YumiCheckPermission.runInCheckPermission(true);

5.7 Proguard

If you are using Proguard add the following to your Proguard config file: