Android SDK: In-stream audio

Help
/
Partners
/
Android SDK: In-stream audio

Initialization
Using the application player
Interface InstreamAudioAdPlayer
Interface InstreamAudioAdPlayer.AdPlayerListener
Ad downloads
Playing ads

Available advertising audio properties
Working with companion banners
Condition management
User Data
Samples

myTarget SDK provides the ability to play in-stream audio ads in your application while listening to audio.

Advertising can be launched before the start of audio playback (preroll), during playback (midroll) and after playback (postroll). The SDK downloads data and provides the application with the ability to play ads in the application player.

Initialization

To play advertising audio in your application, you must create an instance of the class InstreamAudioAd. To create an InstreamAudioAd instance, you must specify your slotId.

For each audio in the application, you need to create your own copy of the class InstreamAudioAd.

private InstreamAudioAd ad;
 
private void initAd()
{
    // Enable debug mode
    // InstreamAudioAd.setDebugMode(true); 
    // Create an instance of InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
}

Using the application player

To play ads in the application player, it must implement the InstreamAudioAdPlayer interface and notify the AdPlayerListener listener installed to it.

To use your player, you must call the setPlayer method (InstreamAudioAdPlayer player) on the created instance InstreamAudioAd.

private InstreamAudioAd ad;
 
private void initAd()
{
    // Create an instance of InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
     
    // Install the player
    ad.setPlayer(YOUR_PLAYER);
}

Interface InstreamAudioAdPlayer

Interface methods InstreamAudioAdPlayer are called by an instance of InstreamAudioAd. Call them yourself is not required.

float getAdAudioDuration();

Duration of ad audio

float getAdAudioPosition();

Current advertising audio position. The method is called repeatedly during the playback of advertising audio and should give the current value in seconds.

void setAdPlayerListener(AdPlayerListener listener);

Sets the player listener

Context getCurrentContext();

Current context

void setVolume(float volume);

Sets the volume from 0 to 1.

void playAdAudio(Uri uri);

Starts playing ad audio.

uri - the path to audio

void pauseAdAudio();

Pauses the playback of ad audio.

void resumeAdAudio();

Resumes playing advertising audio.

void stopAdAudio();

Stops playing ad audio.

Interface InstreamAudioAdPlayer.AdPlayerListener

The callback methods of the AdPlayerListener interface for the installed listener should be called by the player in response to calls to the methods of the InstreamAudioAdPlayer interface when certain events occur.

void onAdAudioStarted();

The method should be called after the successful start of playing advertising audio, as an answer to the call to the playAdAudio () method.

void onAdAudioPaused();

The method should be called after pausing playback of the ad video, as an answer to the pauseAdVideo() method call.

void onAdAudioResumed();

The method should be called after resuming playback of the advertising audio, as an answer to the call to the resumeAdAudio() method.

void onAdAudioStopped();

The method should be called after stopping the playback of advertising audio, as an answer to the stopAdAudio() method call.

void onAdAudioError(String message);

The method must be called when any error occurs when playing advertising audio.

void onAdAudioCompleted();

The method must be called when the ad audio has been played.

void onVolumeChanged(float volume);

The method must be called when the volume is changed.

Ad downloads

To receive notifications (such as successful data download or download error), you need to create an instance of InstreamAudioAdListener and set it as an event listener, after which you can start downloading data.

private InstreamAudioAd ad;
 
private void initAd()
{
    // Create an instance of InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
     
    // Install the event listener
    ad.setListener(new InstreamAudioAd.InstreamAudioAdListener()
    {
        @Override
        public void onLoad(InstreamAudioAd ad)
        {
            // Data uploaded successfully
        }
 
        @Override
        public void onNoAd(String reason, InstreamAudioAd ad)
        {
            // Data not received
        }
 
        @Override
        public void onError(String reason, InstreamAudioAd ad)
        {
            // An error occurred while playing the ad audio
        }
 
        @Override
        public void onBannerStart(InstreamAudioAd ad, InstreamAudioAd.InstreamAudioAdBanner banner)
        {
            // Ad Audio Playback Started
        }
 
        @Override
        public void onBannerComplete(InstreamAudioAd ad, InstreamAudioAd.InstreamAudioAdBanner banner)
        {
            // Ad Audio Playback Completed
        }
 
        @Override
        public void onBannerTimeLeftChange(float timeLeft, float duration, InstreamAudioAd ad)
        {
            // Called repeatedly during the playback of advertising audio, used to update the timer until the end of the display of advertising audio
        }
 
        @Override
        public void onComplete(String section, InstreamAudioAd ad)
        {
            // Playback of all advertising audio in the advertising section is completed.
        }
    });
         
    // We start data loading
    ad.load();
}

Playing ads

After a successful data download, you can start playing ad sections.

Each section of the section can contain several promotional audio, after the start of each playback, the onBannerStart method will be called in the installed InstreamAudioAdListener, after the completion of each audio playback, the onBannerComplete method will be called.

After completion of playback of all advertising audio in the running section, the onComplete method will be called - that's what you should use for further actions. It will be called even if an error occurred during the playback and the onError method was called.

Showing preroll and postroll sections

To play the preroll section, you must call the startPreroll method on the InstreamAudioAd instance before playing the audio.

To play the postroll section, you must call the startPostroll method after the end of the audio playback.

// Before you start playing the main audio
ad.startPreroll();
 
// After playing the main audio
ad.startPostroll();

Show midroll section

To play the midroll section in some audio position, it is necessary after creating an instance of InstreamAudioAd to specify an array of positions where the midroll section will be played. Positions can be set both in seconds and as a percentage of the duration of the audio.

After successful data loading, an array of positions will be available for which there are promotional audio. That is, if positions were set at the first and fifth seconds, and the advertising audio in the downloaded data is only for the first, then there will be only one first position in the available array. If the positions were not specified by the application, they will be set by the server.

If the array of positions after the loading is empty, then there is no data for playing the midroll section.

private InstreamAudioAd ad;
 
private void initAd()
{
    // Create an instance of InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
     
    // Set the position in the first and fifth seconds of audio
    ad.configureMidpoints(videoDuration, new float[]{1f,5f});
    // or as a percentage, at 10% and 50% audio
    // ad.configureMidpointsPercents(audioDuration, new float[]{10f,50f});
 
    // Install the event listener
    ad.setListener(new InstreamAudioAd.InstreamAudioAdListener()
    {
        @Override
        public void onLoad(InstreamAudioAd ad)
        {
            // Data uploaded successfully
            // Array of positions (in seconds) available for playing midroll section
            adPositions = ad.getMidPoints();
        }
         
        ...
    });
     
    // We start data loading
    ad.load();
}

When the main audio reaches one of the positions for the midroll section, you must call the startMidroll method and pass this position as a parameter.

// Audio played out to the 5th second and for it there is a position in the adPositions array
ad.startMidroll(adPositions[1]);

Available advertising audio properties

An instance of InstreamAudioAdBanner is sent to the onBannerStart and onBannerComplete methods of the InstreamAudioAdListener listener, which contains information about the current advertising audio that can be used by the application.

float getDuration();

The duration of the current ad audio in seconds.

boolean isAllowSeek();

Is it allowed to scroll through audio advertising.

boolean isAllowSkip();

Is it allowed to skip ad audio.

boolean isAllowTrackChange();

Is it allowed to move to the next track.

List<InstreamAdCompanionBanner> getInstreamAdCompanionBanners();

List of companion banners.

String getAdText();

Promotional text.

Working with companion banners

The application should independently monitor impressions and clicks on companion banners and call the handleCompanionShow and handleCompanionClick methods in the InstreamAudioAd instance to handle the display and click and go to the advertised site or application.

private void onCompanionAdShow(InstreamAdCompanionBanner companionBanner)
{
    ad.handleCompanionShow(companionBanner);
}
 
private void onCompanionAdClick(InstreamAdCompanionBanner companionBanner)
{
    // Processing a click in the context of current activity
    ad.handleCompanionClick(companionBanner, context);
 
    // Processing a click in the context that was passed during the creation of the advertising instance
    // ad.handleCompanionClick(companionBanner);
}

Condition management

The following management methods are available on the InstreamAudioAd instance.

public void pause()

Pauses the playback of ad audio.

public void resume()

Resumes playing advertising audio.

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 audio 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.

private InstreamAudioAd ad;
 
private void initAd()
{
    // Create an instance of InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
    // 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