The myTarget SDK provides the ability to show in-stream video ads in your app, while watching a video. Ads can be shown before (preroll), during (midroll) and after (postroll) the video. The SDK loads the data and allows the application to show ads in both its video player and in the application'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
// MyTargetManager.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.
private InstreamAd ad;
private void initAd()
{
// Instantiate InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Install the player
ad.setPlayer(YOUR_PLAYER);
}
AdChoices button
The developer must draw the AdChoices button himself as he needs it. Also, the ad.handleAdAdChoicesClick(context) method must be called to handle clicking on the adchoices. By default, the AdChoices button is not displayed for InstreamAd.
customAdChoicesView.setOnClickListener(v->
{
ad.handleAdChoicesClick(context)
})
Customizing the rendering of AdChoice options
To change the design of displaying AdChoices options it is necessary to pass the object implementing the MenuFactory interface in the InstreamAd constructor, which in turn should return the object implementing the Menu interface. If the parameter is not passed to SDK, by default it will display the standard implementation of displaying AdChoices menu options.
MenuFactory menuFactory = new MenuFactory()
{
@Override
@NonNull public Menu createMenu()
{
return new Menu()
{
@Override
public void setListener(@Nullable Listener listener)
{
//the listener that needs to call the onActionClick(menuAction) method when you click on the UI element that was drawn with the corresponding menuAction title
}
@Override
public void addAction(@NonNull MenuAction menuAction)
{
// this is an object that contains the header and option type of AdChoices, these objects should be used when drawing
}
@Override
public void present(@NonNull Context context)
{
// this method is called when you want to display AdChoices options with those menuActions that were previously obtained from the addAction() method
}
@Override
public void dismiss()
{
// this method is called when it is necessary to close the rendering of the AdChoices options
}
};
}
};
...
ad = new InstreamAd(YOUR_SLOT_ID, menuFactory, this);
ad.load();
Interface InstreamAdPlayer
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.
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.
Method should be invoked after a successful start of playback of the advertising video as a response to the call playAdVideo().
void onAdVideoStarted();
Method should be called after pausing ad video playback as a response to the pauseAdVideo () method call.
void onAdVideoPaused();
Method should be invoked after the resumption of the playback of the advertising video as a response to the call resumeAdVideo().
void onAdVideoResumed();
Method should be called after the ad video playback stops, as a response to the stopAdVideo () method call.
void onAdVideoStopped();
Method should be invoked upon the occurrence of any error during the playback of the advertising video.
void onAdVideoError(String message);
The method must be called when the ad video is finished playing.
void onAdVideoCompleted();
The method must be called when the volume changes.
void onVolumeChanged(float volume);
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)
{
// Ad video playback is started
}
@Override
public void onBannerPause(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Ad video playback is suspended
}
@Override
public void onBannerResume(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Ad video playback is resumed
}
@Override
public void onBannerComplete(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Ad video playback is finished
}
@Override
public void onBannerTimeLeftChange(float timeLeft, float duration, InstreamAd ad)
{
// Called repeatedly during the playback of a ad video, it is used to update the timer before the end of the ad video
}
@Override
public void onComplete(String section, InstreamAd ad)
{
// Playback of all ad videos in the promotional section is complete
}
@Override
public void onBannerShouldClose()
{
// Called when ad playback should be completed by the developer himself. Example: ad.skip()
}
});
// 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.
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.
// 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.
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.
The duration of the current ad video in seconds.
public final float duration;
Is it allowed to close the advertising video during playback. Used to control the display of the “Close” or “Skip” button.
public final boolean allowClose;
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 float allowCloseDelay;
The width and height of the promotional video.
public final int videoWidth;
public final int videoHeight;
Text for call-to-action button.
public String ctaText;
Availability of AdChoices.
public boolean hasAdChoices;
Advertising headline.
public String advertisingLabel;
AdChoice icon.
public ImageData adChoicesIcon;
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.
1. Pauses the ad video playback.
public void pause()
2. Resumes advertising video playback.
public void resume()
3. Stops the advertising section
public void stop()
4. Stops the advertising section display if it was done by the user (clicking on the “Skip” or “Close” button).
public void skip()
5. 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 skipBanner()
6. Sets the volume from 0 to 1.
public void setVolume(float volume)
7. 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.
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.