Android SDK: In-stream video
myTarget SDK provides the ability to show in-stream video ads in your app while watching videos. Ads can be shown before a video (preroll), during a show (midroll), and after a show (postroll). The SDK downloads the data and gives the app the ability to display ads both in its video player and in the app's player.
Initialization
To display a promotional video in your application, you must create an instance of the class InstreamAd. To create an InstreamAd instance, you must specify your slotId. For each video in the application, you need to create your own copy of the class InstreamAd.
private InstreamAd ad;
private void initAd()
{
// Enable debug mode
// InstreamAd.setDebugMode(true);
// Instantiate InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
}Using the application player
To play ads in the player application, it must implement the interface InstreamAdPlayer and notify the installed listener AdPlayerListener.
To use your player, call the setPlayer(InstreamAdPlayer player) method on the InstreamAd instance you created.
To use your player, call the setPlayer(InstreamAdPlayer player) method on the InstreamAd instance you created.
private InstreamAd ad;
private void initAd()
{
// Instantiate InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Install the player
ad.setPlayer(YOUR_PLAYER);
}Interface InstreamAdPlayer
Interface methods are invoked InstreamAdPlayer instance InstreamAd. You do not need to call them yourself.
1. The duration of the promotional video
float getAdVideoDuration();
2. The current position of the promotional video. The method is called multiple times during ad video playback and should return the actual value in seconds.
float getAdVideoPosition();
3. Sets a listener to the player
void setAdPlayerListener(AdPlayerListener listener);
4. Visual representation of the player, usually "this".
View getView();
5. Sets the volume from 0 to 1.
void setVolume(float volume);6. Starts playback of the promotional video.
- uri - the path to the video
- width - video width in pixels
- height - video height in pixels
void playAdVideo(Uri uri, int width, int height);7. Pauses the playback of the advertising video.ht - height of video in pixels
void pauseAdVideo();
8. Resumes playing the promotional video.
void resumeAdVideo();
9. Stops the playback of the advertising video.
void stopAdVideo();
Interface InstreamAdPlayer.AdPlayerListener
Methods of the callback interface for the installed AdPlayerListener listener must be invoked by the player in response to the calls of interface methods InstreamAdPlayer upon the occurrence of certain events.
void onAdVideoStarted();
Method should be invoked after a successful start of playback of the advertising video as a response to the call playAdVideo().
void onAdVideoPaused();
Method should be called after pausing ad video playback as a response to the pauseAdVideo () method call.
void onAdVideoResumed();
Method should be invoked after the resumption of the playback of the advertising video as a response to the call resumeAdVideo().
void onAdVideoStopped();
Method should be called after the ad video playback stops, as a response to the stopAdVideo () method call.
void onAdVideoError(String message);
Method should be invoked upon the occurrence of any error during the playback of the advertising video.
void onAdVideoCompleted();
The method must be called when the ad video is finished playing.
void onVolumeChanged(float volume);The method must be called when the volume changes.
Using the SDK player
myTarget SDK provides a ready-made player for playing ads. To use the SDK player, simply call the useDefaultPlayer() method on the InstreamAd instance you created and add the player to the application screen.
private InstreamAd ad;
private void initAd()
{
// Create an instance of InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Install the player SDK
ad.useDefaultPlayer();
// Add player to the screen
layout.addView(ad.getPlayer().getView());
}Download ads
To receive notifications (such as a successful data download or a download error, an ad serving), you must create an InstreamAdListener instance and set it as an event listener, and then you can start the data download.
private InstreamAd ad;
private void initAd()
{
// Create an instance of InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Set the event listener
ad.setListener(new InstreamAd.InstreamAdListener()
{
@Override
public void onLoad(InstreamAd instreamAd)
{
// The data was successfully loaded
}
@Override
public void onNoAd(String reason, InstreamAd instreamAd)
{
// No data received
}
@Override
public void onError(String reason, InstreamAd ad)
{
// An error occurred while playing the promotional video
}
@Override
public void onBannerStart(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Began playing the promotional video
}
@Override
public void onBannerPause(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Ad video playback paused
}
@Override
public void onBannerResume(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Ad video playback resumed
}
@Override
public void onBannerComplete(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Ad video playback completed
}
@Override
public void onBannerTimeLeftChange(float timeLeft, float duration, InstreamAd ad)
{
// Is called multiple times during playback of the promotional video is used to update the timer before the end of the show promotional video
}
@Override
public void onComplete(String section, InstreamAd ad)
{
// Playback of all promotional videos in the advertising section is completed
}
});
// Start loading data
ad.load();
}Display ads
After the data has been successfully uploaded, you can start displaying ad sections. Each partition section can contain multiple ad video, after the playing of each method will be called onBannerStart in the prescribed listener InstreamAdListener, after playing each video method will be called onBannerComplete.
After the playback of all advertising videos in the running section is completed, the onComplete method will be called - this is what you should use for further actions, it will be called even if an error occurred during playback and the onError method was called.
After the playback of all advertising videos in the running section is completed, the onComplete method will be called - this is what you should use for further actions, it will be called even if an error occurred during playback and the onError method was called.
Display of preroll and postroll sections
To display preroll section must before you start showing the video to invoke a method startPreroll instance InstreamAd.
To show the postroll section is necessary after the end of the video to call the method startPostroll.
To show the postroll section is necessary after the end of the video to call the method startPostroll.
// Before starting the main video
ad.startPreroll();
// After showing the main video
ad.startPostroll();Display the midroll section
To display the midroll section at some position in the video, after instreamad is created, you must specify an array of positions at which you plan to display the midroll section. Positions can be set in seconds or as a percentage of the video duration.
After successful data loading, an array of positions for which there are promotional videos will be available. That is, if positions were set for the first and fifth seconds, and advertising videos in the downloaded data are only for the first, then there will be only one first position in the available array.
If the positions were not set by the application, they will be set by the server. If the array of positions after loading is empty, then there is no data to show the midroll section.
After successful data loading, an array of positions for which there are promotional videos will be available. That is, if positions were set for the first and fifth seconds, and advertising videos in the downloaded data are only for the first, then there will be only one first position in the available array.
If the positions were not set by the application, they will be set by the server. If the array of positions after loading is empty, then there is no data to show the midroll section.
private InstreamAd ad;
private void initAd()
{
// Create an instance of InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Set positions on the first and fifth seconds of the video
ad.configureMidpoints(videoDuration, new float[]{1f,5f});
// or percentage, 10% and 50% video
// ad.configureMidpointsPercents(videoDuration, new float[]{10f,50f});
// Set the event listener
ad.setListener(new InstreamAd.InstreamAdListener()
{
@Override
public void onLoad(InstreamAd instreamAd)
{
// The data was successfully loaded
// Array of positions (in seconds) available to display the midroll section
adPositions = ad.getMidPoints();
}
...
});
// Start loading data
ad.load();
}When the main video reaches one of the positions for the midroll section, it is necessary to call the startMidroll method and pass this position as a parameter to it.
// The video was played to the 5th second and it has a position in the array adPositions
ad.startMidroll(adPositions[1]);Available ad video properties
An instance of InstreamAdBanner is sent to the onBannerStart and onBannerComplete methods of the InstreamAdListener listener, which contains information about the current advertising video that can be used by the application.
public final float duration;The duration of the current ad video in seconds.
public final boolean allowClose;Is it allowed to close the advertising video during playback. Used to control the display of the "Close" or "Skip" button.
public final float allowCloseDelay;
The time in seconds after which the ad video can be closed. Used to control the display of the "Close" or "Skip" button.
public final int videoWidth;
public final int videoHeight;The width and height of the promotional video.
public String ctaText;
Text for call-to-action button.
Click processing
The application should independently track clicks on the advertising video (usually on the cta button) and call the handleClick method on InstreamAd instance to process the click and go to the advertised site or application.
private void onAdClick()
{
ad.handleClick();
}Condition management
The following control methods are available on the InstreamAd instance.
public void pause()Pauses the ad video playback.
public void resume()
Resumes advertising video playback.
public void stop()
Stops the advertising section.
public void skip()Stops the advertising section display if it was done by the user (clicking on the "Skip" or "Close" button).
public void skipBanner()Stops the current ad video and proceeds to the next if it was done by the user (clicking on the "Skip" or "Close" button).
public void setVolume(float volume)Sets the volume from 0 to 1.
public void setLoadingTimeout(int loadingTimeout)Sets the timeout for advertising loading in seconds. In case if after the expiration of the specified interval it was not possible to get banners, the onNoAd callback will be called. The default is 10 seconds, the minimum is 5 seconds.
User Data
For a better selection of advertisements, you can additionally specify the gender and age of the user. If your application uses its own localization model, you can also specify the language of the selected localization in ISO 639-1 format ("ru", "en", "fr", etc.).
To set user data, you need to use the customParams property.
To set user data, you need to use the customParams property.
private InstreamAd ad;
private void initAd()
{
// Create an instance of InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// We receive an instance of additional parameters CustomParams
CustomParams customParams = ad.getCustomParams();
// Set age
customParams.setAge(25);
// Set gender
customParams.setGender(CustomParams.Gender.MALE);
}Samples
Integration examples are available in our demo application on Github.
Was this article helpful?
Yes
No
