[Huawei Developers] HMS Community:
Introduction

In this article, we can learn how to integrate Roll Ads feature of Huawei Ads Kit into the android app. So, Roll ads are displayed as short videos or images, before, during, or after the video content is played.

Ads Kit

Huawei Ads provides to developers a wide-ranging capabilities to deliver good quality ads content to users. This is the best way to reach the target audience easily and can measure user productivity. It is very useful when we publish a free app and want to earn some money from it.

HMS Ads Kit has 7 types of Ads kits. Now we can implement Roll Ads in this application.

Requirements

1. Any operating system (MacOS, Linux and Windows).

2. Must have a Huawei phone with HMS 4.0.0.300 or later.

3. Must have a laptop or desktop with Android Studio, Jdk 1.8, SDK platform 26 and Gradle 4.6 and above installed.

4. Minimum API Level 24 is required.

5. Required EMUI 9.0.0 and later version devices.

How to integrate HMS Dependencies

1. First register as Huawei developer and complete identity verification in Huawei developers website, refer to register a Huawei ID.

2. Create a project in android studio, refer Creating an Android Studio Project.

3. Generate a SHA-256 certificate fingerprint.

4. To generate SHA-256 certificate fingerprint. On right-upper corner of android project click Gradle, choose Project Name > Tasks > android, and then click signingReport, as follows.

Note: Project Name depends on the user created name.

5. Create an App in AppGallery Connect.

6. Download the agconnect-services.json file from App information, copy and paste in android Project under app directory, as follows.

7. Enter SHA-256 certificate fingerprint and click Save button, as follows.

Note: Above steps from Step 1 to 7 is common for all Huawei Kits.

8. Add the below maven URL in build.gradle(Project) file under the repositories of buildscript, dependencies and allprojects, refer Add Configuration.

maven { url 'http://developer.huawei.com/repo/' }
classpath 'com.huawei.agconnect:agcp:1.6.0.300'

9. Add the below plugin and dependencies in build.gradle(Module) file.

apply plugin: id 'com.huawei.agconnect'
// Huawei AGC
implementation 'com.huawei.agconnect:agconnect-core:1.6.0.300'
// Huawei Ads Kit
implementation 'com.huawei.hms:ads-lite:13.4.51.300'

10. Now Sync the gradle.

11. Add the required permission to the AndroidManifest.xml file.

// Ads Kit
<uses-permission android:name="android.permission.INTERNET" />

Let us move to development

I have created a project on Android studio with empty activity let us start coding.

In the MainActivity.kt we can find the business logic for Ads.

class MainActivity : AppCompatActivity() {

private var videoContent: TextView? = null
private var skipAd: TextView? = null
private var countDown: TextView? = null
private var callToAction: TextView? = null
private var loadButton: Button? = null
private var registerButton: Button? = null
private var muteButton: Button? = null
private var pauseButton: Button? = null
private var instreamContainer: RelativeLayout? = null
private var instreamView: InstreamView? = null
private var whyThisAd: ImageView? = null
private var context: Context? = null
private var maxAdDuration = 0
private var whyThisAdUrl: String? = null
private var isMuted = false
private var adLoader: InstreamAdLoader? = null
private var instreamAds: List<InstreamAd>? = ArrayList()

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

context = applicationContext
setTitle(R.string.instream_ad)
initInstreamAdView()
initButtons()
configAdLoader()

}

private val mediaChangeListener = InstreamMediaChangeListener { instreamAd ->
whyThisAdUrl = null
whyThisAdUrl = instreamAd.whyThisAd
Log.i(TAG, "onSegmentMediaChange, whyThisAd: $whyThisAdUrl")
if (!TextUtils.isEmpty(whyThisAdUrl)) {
whyThisAd!!.visibility = View.VISIBLE
whyThisAd!!.setOnClickListener { startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(whyThisAdUrl))) }
} else {
whyThisAd!!.visibility = View.GONE
}
val cta = instreamAd.callToAction
if (!TextUtils.isEmpty(cta)) {
callToAction!!.visibility = View.VISIBLE
callToAction!!.text = cta
instreamView!!.callToActionView = callToAction
}
}

private val mediaStateListener: InstreamMediaStateListener = object : InstreamMediaStateListener {
override fun onMediaProgress(per: Int, playTime: Int) {
updateCountDown(playTime.toLong())
}
override fun onMediaStart(playTime: Int) {
updateCountDown(playTime.toLong())
}
override fun onMediaPause(playTime: Int) {
updateCountDown(playTime.toLong())
}
override fun onMediaStop(playTime: Int) {
updateCountDown(playTime.toLong())
}
override fun onMediaCompletion(playTime: Int) {
updateCountDown(playTime.toLong())
playVideo()
}
override fun onMediaError(playTime: Int, errorCode: Int, extra: Int) {
updateCountDown(playTime.toLong())
}
}

private val mediaMuteListener: MediaMuteListener = object : MediaMuteListener {
override fun onMute() {
isMuted = true
Toast.makeText(context, "Ad muted", Toast.LENGTH_SHORT).show()
}
override fun onUnmute() {
isMuted = false
Toast.makeText(context, "Ad unmuted", Toast.LENGTH_SHORT).show()
}
}

private fun initInstreamAdView() {
instreamContainer = findViewById(R.id.instream_ad_container)
videoContent = findViewById(R.id.instream_video_content)
skipAd = findViewById(R.id.instream_skip)
skipAd!!.setOnClickListener(View.OnClickListener {
if (null != instreamView) {
instreamView!!.onClose()
instreamView!!.destroy()
instreamContainer!!.visibility = View.GONE
}
})
countDown = findViewById(R.id.instream_count_down)
callToAction = findViewById(R.id.instream_call_to_action)
whyThisAd = findViewById(R.id.instream_why_this_ad)
instreamView = findViewById(R.id.instream_view)
instreamView!!.setInstreamMediaChangeListener(mediaChangeListener)
instreamView!!.setInstreamMediaStateListener(mediaStateListener)
instreamView!!.setMediaMuteListener(mediaMuteListener)
instreamView!!.setOnInstreamAdClickListener(InstreamView.OnInstreamAdClickListener {
Toast.makeText(context,"instream clicked.", Toast.LENGTH_SHORT).show()
})
}

private val clickListener = View.OnClickListener { view ->
when (view.id) {
R.id.instream_load -> if (null != adLoader) {
loadButton!!.text = getString(R.string.instream_loading)
adLoader!!.loadAd(AdParam.Builder().build())
}
R.id.instream_register -> if (null == instreamAds || instreamAds!!.isEmpty()) {
playVideo()
} else {
playInstreamAds(instreamAds!!)
}
R.id.instream_mute -> if (isMuted) {
instreamView!!.unmute()
muteButton!!.text = getString(R.string.instream_mute)
} else {
instreamView!!.mute()
muteButton!!.text = getString(R.string.instream_unmute)
}
R.id.instream_pause_play -> if (instreamView!!.isPlaying) {
instreamView!!.pause()
pauseButton!!.text = getString(R.string.instream_play)
} else {
instreamView!!.play()
pauseButton!!.text = getString(R.string.instream_pause)
}
else -> {
}
}
}

private fun initButtons() {
loadButton = findViewById(R.id.instream_load)
registerButton = findViewById(R.id.instream_register)
muteButton = findViewById(R.id.instream_mute)
pauseButton = findViewById(R.id.instream_pause_play)
loadButton!!.setOnClickListener(clickListener)
registerButton!!.setOnClickListener(clickListener)
muteButton!!.setOnClickListener(clickListener)
pauseButton!!.setOnClickListener(clickListener)
}

private val instreamAdLoadListener: InstreamAdLoadListener = object : InstreamAdLoadListener {
override fun onAdLoaded(ads: MutableList<InstreamAd>) {
if (null == ads || ads.size == 0) {
playVideo()
return
}
val it = ads.iterator()
while (it.hasNext()) {
val ad = it.next()
if (ad.isExpired) {
it.remove()
}
}
if (ads.size == 0) {
playVideo()
return
}
loadButton!!.text = getString(R.string.instream_loaded)
instreamAds = ads
Toast.makeText(context, "onAdLoaded, ad size: " + ads.size + ", click REGISTER to play.", Toast.LENGTH_SHORT).show()
}
override fun onAdFailed(errorCode: Int) {
Log.w(TAG, "onAdFailed: $errorCode")
loadButton!!.text = getString(R.string.instream_load)
Toast.makeText(context, "onAdFailed: $errorCode", Toast.LENGTH_SHORT).show()
playVideo()
}
}

private fun configAdLoader() {
// if the maximum total duration is 60 seconds and the maximum number of roll ads is eight,
// at most four 15-second roll ads or two 30-second roll ads will be returned.
// If the maximum total duration is 120 seconds and the maximum number of roll ads is four,
// no more roll ads will be returned after whichever is reached.
val totalDuration = 60
val maxCount = 4
val builder = InstreamAdLoader.Builder(context, getString(R.string.instream_ad_id))
adLoader = builder.setTotalDuration(totalDuration)
.setMaxCount(maxCount)
.setInstreamAdLoadListener(instreamAdLoadListener)
.build()
}

// play your normal video content.
private fun playVideo() {
hideAdViews()
videoContent!!.setText(R.string.instream_normal_video_playing)
}

private fun hideAdViews() {
instreamContainer!!.visibility = View.GONE
}

private fun playInstreamAds(ads: List<InstreamAd>) {
maxAdDuration = getMaxInstreamDuration(ads)
instreamContainer!!.visibility = View.VISIBLE
loadButton!!.text = getString(R.string.instream_load)
instreamView!!.setInstreamAds(ads)
}

private fun updateCountDown(playTime: Long) {
val time = Math.round((maxAdDuration - playTime) / 1000.toFloat()).toString()
runOnUiThread { countDown!!.text = time + "s" }
}

private fun getMaxInstreamDuration(ads: List<InstreamAd>): Int {
var duration = 0
for (ad in ads) {
duration += ad.duration.toInt()
}
return duration
}

override fun onPause() {
super.onPause()
if (null != instreamView && instreamView!!.isPlaying) {
instreamView!!.pause()
pauseButton!!.text = getText(R.string.instream_play)
}
}

override fun onResume() {
super.onResume()
if (null != instreamView && !instreamView!!.isPlaying) {
instreamView!!.play()
pauseButton!!.text = getText(R.string.instream_pause)
}
}

override fun onDestroy() {
super.onDestroy()
if (null != instreamView) {
instreamView!!.removeInstreamMediaStateListener()
instreamView!!.removeInstreamMediaChangeListener()
instreamView!!.removeMediaMuteListener()
instreamView!!.destroy()
}
}

companion object {
private val TAG = MainActivity::class.java.simpleName
}

}

In the activity_main.xml we can create the UI screen.

<?xml version="1.0" encoding="utf-8"?>
<ScrollView xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity">

<RelativeLayout
android:layout_width="match_parent"
android:layout_height="wrap_content">

<RelativeLayout
android:id="@+id/your_video_content"
android:layout_width="match_parent"
android:layout_height="200dp"
android:background="@android:color/black">
<TextView
android:id="@+id/instream_video_content"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:textAlignment="center"
android:layout_centerInParent="true"
android:text="Your video content"
android:textColor="@android:color/white"/>
</RelativeLayout>

<RelativeLayout
android:id="@+id/instream_ad_container"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:visibility="gone">

<com.huawei.hms.ads.instreamad.InstreamView
android:id="@+id/instream_view"
android:layout_width="match_parent"
android:layout_height="match_parent" />

<TextView
android:id="@+id/instream_skip"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:paddingVertical="3dp"
android:paddingHorizontal="5dp"
android:layout_alignStart="@id/instream_view"
android:layout_alignLeft="@id/instream_view"
android:layout_alignTop="@id/instream_view"
android:layout_marginStart="16dp"
android:layout_marginLeft="16dp"
android:layout_marginTop="8dp"
android:text="Skip"
android:textColor="@android:color/white"
android:textSize="16sp"
android:background="@drawable/emui_button_select"/>

<TextView
android:id="@+id/instream_count_down"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:paddingVertical="3dp"
android:paddingHorizontal="5dp"
android:layout_alignEnd="@id/instream_view"
android:layout_alignRight="@id/instream_view"
android:layout_alignTop="@id/instream_view"
android:layout_marginEnd="16dp"
android:layout_marginRight="16dp"
android:layout_marginTop="8dp"
android:textColor="@android:color/white"
android:textSize="16sp"
android:background="@drawable/emui_button_select"/>

<TextView
android:id="@+id/instream_ad_flag"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignStart="@id/instream_view"
android:layout_alignLeft="@id/instream_view"
android:layout_alignBottom="@id/instream_view"
android:layout_marginStart="16dp"
android:layout_marginLeft="16dp"
android:layout_marginBottom="8dp"
android:background="@drawable/emui_button_select"
android:gravity="center"
android:text="Ad"
android:textColor="@android:color/white"
android:textSize="8sp"
android:textStyle="bold" />

<ImageView
android:id="@+id/instream_why_this_ad"
android:layout_width="14dp"
android:layout_height="14dp"
android:layout_toEndOf="@id/instream_ad_flag"
android:layout_toRightOf="@id/instream_ad_flag"
android:layout_alignBottom="@id/instream_view"
android:layout_marginLeft="8dp"
android:layout_marginStart="8dp"
android:layout_marginBottom="8dp"
android:src="@drawable/app_whythisad_info"/>

<TextView
android:id="@+id/instream_call_to_action"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:paddingVertical="3dp"
android:paddingHorizontal="5dp"
android:layout_alignEnd="@id/instream_view"
android:layout_alignRight="@id/instream_view"
android:layout_alignBottom="@id/instream_view"
android:layout_marginEnd="16dp"
android:layout_marginRight="16dp"
android:layout_marginBottom="8dp"
android:text="Learn more"
android:textColor="@android:color/white"
android:textSize="16sp"
android:background="@drawable/emui_button_select"/>
</RelativeLayout>

<RelativeLayout
android:id="@+id/instream_ctrl_panel"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:paddingHorizontal="16dp"
android:paddingVertical="16dp"
android:layout_below="@id/your_video_content">
<LinearLayout
android:id="@+id/load_and_register"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:orientation="horizontal"
android:layout_centerHorizontal="true">
<Button
android:id="@+id/instream_load"
android:layout_width="120dp"
android:layout_height="wrap_content"
android:layout_marginRight="10dp"
android:text="Load Ad"/>
<Button
android:id="@+id/instream_register"
android:layout_width="120dp"
android:layout_height="wrap_content"
android:text="Register"/>
</LinearLayout>
<LinearLayout
android:id="@+id/play_ctrl"
android:layout_below="@id/load_and_register"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:orientation="horizontal"
android:layout_centerHorizontal="true">
<Button
android:id="@+id/instream_mute"
android:layout_width="100dp"
android:layout_marginRight="10dp"
android:layout_height="wrap_content"
android:text="Mute"/>
<Button
android:id="@+id/instream_pause_play"
android:layout_width="100dp"
android:layout_height="wrap_content"
android:text="Pause"/>
</LinearLayout>
</RelativeLayout>
</RelativeLayout>

</ScrollView>

Demo

Tips and Tricks

1. Make sure you are already registered as Huawei developer.

2. Set minSDK version to 24 or later, otherwise you will get AndriodManifest merge issue.

3. Make sure you have added the agconnect-services.json file to app folder.

4. Make sure you have added SHA-256 fingerprint without fail.

5. Make sure all the dependencies are added properly.

Conclusion

In this article, we have learned how to integrate Roll Ads feature of Huawei Ads Kit into the android app. So, Roll ads are displayed as short videos or images, before, during, or after the video content is played.

I hope you have read this article. If you found it is helpful, please provide likes and comments.

Reference

Ads Kit - Roll Ads

Ads Kit – Training Video