com.iab.omid.library.adsession

Class AdSession

java.lang.Object

com.iab.omid.library.adsession.AdSession

public abstract class AdSession
extends java.lang.Object

Ad session API enabling the integration partner to notify OMID of key state relating to viewability calculations. In addition to viewability this API will also notify all verification providers of key ad session lifecycle events.

Constructor Summary

Constructors

Constructor and Description
AdSession()

Method Summary

Modifier and Type	Method and Description
abstract void	addFriendlyObstruction(android.view.View friendlyObstruction) Add friendly obstruction which should then be excluded from all ad session viewability calculations.
static AdSession	createAdSession(AdSessionConfiguration adSessionConfiguration, AdSessionContext adSessionContext) Create new ad session supplying the adSessionConfiguration and adSessionContext.
abstract void	error(ErrorType errorType, java.lang.String message) Notify all verification providers that an error has occurred on the ad session.
abstract void	finish() Notify all verification providers that the ad session has finished and all ad view tracking will stop.
abstract java.lang.String	getAdSessionId()
abstract com.iab.omid.library.publisher.AdSessionStatePublisher	getAdSessionStatePublisher() Use of getAdSessionStatePublisher() and getAdSessionId() is highly discouraged.
abstract void	registerAdView(android.view.View adView) Register ad view to be used for tracking viewability.
abstract void	removeAllFriendlyObstructions() Utility method to remove all registered friendly obstructions.
abstract void	removeFriendlyObstruction(android.view.View friendlyObstruction) Remove registered friendly obstruction.
abstract void	start() Notify all verification providers that the ad session has started and ad view tracking will begin.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdSession

public AdSession()

Method Detail

start

public abstract void start()

Notify all verification providers that the ad session has started and ad view tracking will begin. This method will have no effect if called after the ad session has finished.

error

public abstract void error(ErrorType errorType,
                           java.lang.String message)

Notify all verification providers that an error has occurred on the ad session.

Parameters:

errorType - of the reported error

message - containing details of the reported error

Throws:

java.lang.IllegalArgumentException - if the supplied error type is null.

java.lang.IllegalArgumentException - if the supplied message is either null or blank.

java.lang.IllegalStateException - if the ad session has finished.

registerAdView

public abstract void registerAdView(android.view.View adView)

Register ad view to be used for tracking viewability. This method should be called each time the ad view to track changes - i.e. two-part expandable. If an ad view is already registered for the current session, that ad view will be automatically unregistered and the new ad view will be registered in its place. If the ad view being registered has been previously registered with a different ad session, then the ad view will be automatically unregistered from those previously registered ad sessions. This method will have no effect if called after the ad session has finished.

Parameters:

adView - the native view which should be registered for viewability tracking.

Throws:

java.lang.IllegalArgumentException - if the supplied ad view is null.

finish

public abstract void finish()

Notify all verification providers that the ad session has finished and all ad view tracking will stop. This method will have no effect if called after the ad session has finished. Note that ending an OMID ad session sends a message to the verification scripts running inside the webview supplied by the integration. So that the verification scripts have enough time to handle the 'sessionFinish' event, the integration must maintain a strong reference to the webview for at least 1.0 seconds after ending the session.

addFriendlyObstruction

public abstract void addFriendlyObstruction(android.view.View friendlyObstruction)

Add friendly obstruction which should then be excluded from all ad session viewability calculations. This method will have no effect if called after the ad session has finished.

Parameters:

friendlyObstruction - to be excluded from all ad session viewability calculations.

Throws:

java.lang.IllegalArgumentException - if the supplied friendly obstruction is null.

removeFriendlyObstruction

public abstract void removeFriendlyObstruction(android.view.View friendlyObstruction)

Remove registered friendly obstruction. This method will have no effect if called after the ad session has finished.

Parameters:

friendlyObstruction - to be removed from the list of registered friendly obstructions.

Throws:

java.lang.IllegalArgumentException - if the supplied friendly obstruction is null.

removeAllFriendlyObstructions

public abstract void removeAllFriendlyObstructions()

Utility method to remove all registered friendly obstructions. This method will have no effect if called after the ad session has finished.

getAdSessionStatePublisher

public abstract com.iab.omid.library.publisher.AdSessionStatePublisher getAdSessionStatePublisher()

Use of getAdSessionStatePublisher() and getAdSessionId() is highly discouraged. These are undocumented calls that will be removed in future version.

getAdSessionId

public abstract java.lang.String getAdSessionId()

createAdSession

public static AdSession createAdSession(AdSessionConfiguration adSessionConfiguration,
                                        AdSessionContext adSessionContext)

Create new ad session supplying the adSessionConfiguration and adSessionContext. Note that creating an AdSession sends a message to the OM SDK JS Service running in the webview. If the OM SDK JS Service has not loaded before the ad session is created, the message is lost, and the verification scripts will not receive any events. To prevent this, the implementation must wait until the webview finishes loading OM SDK JavaScript before creating the AdSession. The easiest way is to create the AdSession in a webview callback WebViewClient.onPageFinished(). Alternatively, if an implementation can receive an HTML5 DOMContentLoaded event from the webview, it can create the OMIDAdSession in a message handler for that event.

Parameters:

adSessionContext - that provides the required information for initialising the ad session.

Returns:

new AdSession instance

Throws:

java.lang.IllegalArgumentException - if the supplied adSessionContext is null.

java.lang.IllegalStateException - if this method has been executed before OMID has been activated.