Integrate Smart Instream SDK

Step by step guide to integrate instream ads in your application.

Overview
Configure the SDK
Create an Ad placement
Create optional configurations
Create an Ad Manager
Setup your content player plugin
Start your Ad Manager
Handling Activity lifecycle
Fullscreen management
Chrome Custom Tabs

Overview

Ad calls and ad breaks playback are performed by a SVSAdManager instance.

To initialize and start your SVSAdManager, you will need:

A SVSAdPlacement that will be used to perform ad calls to the delivery engine.
An object that implements the SVSContentPlayerPlugin interface, that will be used to retrieve the ad player container, to monitor your content's playback and place ad breaks where you defined them.
A array of SVSAdRule objects, optional, see the documentation.
A SVSAdPlayerConfiguration object, also optional, see the documentation.
If your application features a fullscreen mode, an object that implements the SVSAdManager.UIInteractionListener interface. This will allow you to respond properly to fullscreen events sent from the ad player to your app.

You can always refer to the samples if you just want to copy/paste the whole integration.

Configure the SDK

The SDK needs to be configured with your own SiteID before making any ad calls. You will have to call the method configure of the SVSConfiguration shared instance to do so.

A good place to configure the SDK is in the Application class of your app, in the onCreate method:


public class MyApplication extends Application {
	@Override
	public void onCreate() {
		super.onCreate();

		// Configure the SDK with your own SiteID
		SVSConfiguration.getSharedInstance().configure(this, 123);
	}
}

Note that you will not be able to start your SVSAdManager instance and display ads if the SDK is not configured first.

This configuration step will allow Smart to remotely customize your SDK behavior for example if you need help for troubleshooting.

Create an Ad placement

To perform ad calls, the SVSAdManager will need to know about your ad placement.

Instantiate a SVSAdPlacement using your SiteId, PageId (or PageName) and your FormatId.

You can also set targeting informations per ad break type and/or a global one on the ad placement.
Note: if the targeting is not set for an ad break type, the global targeting will be used instead.


// Create an SVSAdPlacement instance from your SiteID, PageID and FormatID.
SVSAdPlacement adPlacement = new SVSAdPlacement(YOUR_SITE_ID, YOUR_PAGE_ID, YOUR_FORMAT_ID);

// Optional: you can setup the custom targeting for your placement.
adPlacement.setGlobalTargetingString("Default keyword targeting"); // Global targeting
adPlacement.setPrerollTargetingString("Preroll keyword targeting"); // Preroll targeting
adPlacement.setMidrollTargetingString("Midroll keyword targeting"); // Midroll targeting
adPlacement.setPostrollTargetingString("Postroll keyword targeting"); // Postroll targeting

The newly created instance of SVSAdPlacement will be used for your SVSAdManager initialization.

Create optional configurations

For a better management of your ads and ad player you can set up optional configurations. This is not mandatory, and if you don't create these objects, default ones will be created by the SDK when instantiating the SVSAdManager.

You can create:

an array of SVSAdRule for an advanced management of your ad breaks. See the ad rules documentation for more informations.
a SVSAdPlayerConfiguration to modify the look and behavior of the ad player. See the ad player configuration documentation for more informations.
a SVSContentData to provide more informations about your content (metadata).



//////////////////////////////////////////////////////////////////////
// AD RULES
//////////////////////////////////////////////////////////////////////

// Instantiate 3 SVSAdRuleData that define:
// - a preroll with 2 ad.
// - a midroll with 1 ad when 50% of the content's duration is reached.
// - a postroll with 2 ad.
SVSAdRuleData prerollData = SVSAdRuleData.createPrerollAdRuleData(2, 120000); //120 seconds
SVSAdRuleData midrollData = SVSAdRuleData.createMidrollAdRuleData(1, 120000, new double[]{50});
SVSAdRuleData postrollData = SVSAdRuleData.createPostrollAdRuleData(2, 120000);

// Instantiate a SVSAdRule with preroll, midroll and postroll SVSAdRuleData for any content duration
SVSAdRule adRule = new SVSAdRule(0, -1, new SVSAdRuleData[]{prerollData, midrollData, postrollData}, 0);

// Instantiate the ad rules array
SVSAdRule[] adRules = new SVSAdRule[]{adRule};


//////////////////////////////////////////////////////////////////////
// AD PLAYER CONFIGURATION
//////////////////////////////////////////////////////////////////////

// Create a new SVSAdPlayerConfiguration.
SVSAdPlayerConfiguration adPlayerConfiguration = new SVSAdPlayerConfiguration();

// Force a skip delay of 5 seconds for any ad. See API for more options…
adPlayerConfiguration.getPublisherOptions().setForceSkipDelay(true);
adPlayerConfiguration.getPublisherOptions().setSkipDelay(5000);


//////////////////////////////////////////////////////////////////////
// CONTENT VIDEO DATA
//////////////////////////////////////////////////////////////////////

// Instantiate the builder.
SVSContentData.Builder builder = new SVSContentData.Builder();

// Sets your parameters.
builder.setContentID("contentID");
builder.setContentTitle("contentTitle");
builder.setVideoContentType("videoContentType");
builder.setVideoContentCategory("videoContentCategory");
builder.setVideoContentDuration(60);
builder.setVideoSeasonNumber(1);
builder.setVideoEpisodeNumber(2);
builder.setVideoContentRating("videoContentRating");
builder.setContentProviderID("contentProviderID");
builder.setContentProviderName("contentProviderName");
builder.setVideoContentDistributorID("videoContainerDistributorID");
builder.setVideoContentDistributorName("videoContainerDistributerName");
builder.setVideoContentTags(new String[]{"tag1", "tag2"});
builder.setExternalContentID("externalContentID");
builder.setVideoCMSID("videoCMSID");

// Then build your instance of SVSContentData
SVSContentData contentData = builder.build();

You are now ready to create your SVSAdManager.

Create an Ad Manager

SVSAdManager is the main class of the SDK. This object is responsible for applying configurations, monitoring your content and displaying ad breaks when defined by your advertising policy.


// Creating the SVSAdPlacement, SVSAdRule, SVSAdPlayerConfiguration, SVSContentData as seen earlier
// …

// Creating the SVSAdManager instance
SVSAdManager adManager = new SVSAdManager(
	this,
	adPlacement,
	adRules,
	adPlayerConfiguration,
	contentData
);

// A UI interaction listener can be added to the ad manager: this will be helpful to handle the ad player
// fullscreen button properly, as you will see in the 'Fullscreen management' section.
adManager.addUIInteractionListener(this);

Now that your SVSAdManager is created, you need to bind it to your content player using a plugin so you can display ads along the content's playback.

Setup your content player plugin

To be able to trigger ad breaks at the right moment, the SVSAdManager needs to monitor your content in real time: the total duration, the current time, the volume, etc… It also need to be able to pause or resume your content player and know where to show the ad player view.

For this, the SVSAdManager will query information from an object implementing the SVSContentPlayerPlugin interface, which is called a content player plugin.

In this example, we will assume that our content player is based on ExoPlayer, so we will use the SVSExoPlayerPlugin class. This class is shipped in our samples and in our Github account.

To adapt your content player to our solution, please refer to the Content player plugin documentation.


// Creating the the content player plugin
SVSExoPlayerPlugin exoPlayerPlugin = new SVSExoPlayerPlugin(
	myExoPlayer,
	myExoPlayerView,
	myContentPlayerContainer, // this is the view group in which the ad player view will be added
	false // true if the content video is live, false otherwise
);

You are now ready to start your ad manager and display your first ads !

Start the Ad Manager

Once your content player is ready to play, you should not start it right away.

First you should start your SVSAdManager that will take care to resume the content player through the content player plugin.

To be started, the SVSAdManager needs a valid SVSContentPlayerPlugin instance, for instance the one we instantiated in the previous section.

Note: do not try to start your SVSAdManager before the asset loaded in your content player is ready. If you do so, the content player plugin will still not know about content duration and ad breaks scheduling will be impossible. The SVSAdManager will throw a IllegalStateException if the content duration is 0


myExoPlayer.addListener(new Player.EventListener() {

	// …

	@Override
	public void onPlayerStateChanged(boolean playWhenReady, int playbackState) {
		// Start the SVSAdManager only when the player is about to play
		if (playbackState == Player.STATE_READY && !adManagerStarted) {

			// Starting the ad manager using the content player plugin created earlier
			adManager.start(exoPlayerPlugin);

		}
	}

	// …

});

Handling Activity lifecycle

To avoid any weird behavior or crashes, you must forward some Activity lifecycle events to the SVSAdManager.

These Activity lifecycle events are:

onResume
onPause
onDestroy


@Override
protected void onResume() {
	super.onResume();
	if (adManager != null) {
		adManager.onResume();
	}
	// …
}
@Override
protected void onPause() {
	super.onPause();
	if (adManager != null) {
		adManager.onPause();
	}
	// …
}

@Override
protected void onDestroy() {
	super.onDestroy();
	if (adManager != null) {
		adManager.onDestroy();
	}
	// …
}

Fullscreen management

To avoid breaking your app, the SVSAdManager will never force your content player into fullscreen. It is your app that decides how the fullscreen will be handled for your content player and the ad player.

If you choose to display the fullscreen / exit fullscreen buttons on the ad player interface (this can be configured using the SVSAdPlayerConfiguration object), the SVSAdManager will call the onFullscreenStateChangeRequest method of the SVSAdManager.UIInteractionListener provided at initialization every time fullscreen / exit buttons are pressed.

You are responsible for responding to this event. The ad player view will always stays in the container provided by your SVSContentPlayerPlugin. You can use the method onFullscreenStateChangeRequest to resize this container as you wish.

Once you have modified the container size or status, let the SVSAdManager know about it by setting the new state of the content player through the onFullscreenStateChange method of SVSAdManager. This will allow the ad player interface to update itself properly.


/**
 * Implementation of SVSAdManager.UIInteractionListener.
 */
@Override
public void onFullscreenStateChangeRequest(boolean isFullscreen) {
	// Called when the enter (or exit) fullscreen button of an ad is clicked by the user.

	// Modify your UI as you wish here
	configureMyAppForFullscreenState(isFullscreen);

	// Then don't forget to inform the SVSAdManager about the fullscreen state change
	// (if your app does not feature a fullscreen state, just pass false value to the method below)
	adManager.onFullscreenStateChange(isFullscreen);
}

Chrome Custom Tabs

Note: since Android TV SDK does not support clickthrough, this step is not useful for 'TV only' apps.

The SDK is compatible with Chrome Custom Tabs. It can open post click landing pages in a light and fast in-app webview, instead of redirecting the user to the device's default browser.

To enable Chrome Custom Tabs, simply add the dependencies in your app's build.gradle:


compile 'com.android.support:customtabs:+'
// Note: using the relevant version number at the time of the integration instead of '+' is better

Please note that:

using Chrome Custom Tabs is optional: the SDK will fallback on the default browser if you don't add support,
if you enable Chrome Custom Tabs on an incompatible Android device, the SDK will fallback on the default browser as well,
deep links (like Google Play Store links) will always be opened in the relevant app.