Package com.iab.omid.library.adsession

Class AdSession

java.lang.Object

com.iab.omid.library.adsession.AdSession

public abstract class AdSession
extends Object

Ad session API enabling the integration partner to notify OM SDK 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	Description
AdSession()

Method Summary

Modifier and Type	Method	Description
abstract void	addFriendlyObstruction(View friendlyObstruction, FriendlyObstructionPurpose purpose, String detailedReason)	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, 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 void	registerAdView(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(View friendlyObstruction)	Remove registered friendly obstruction.
abstract void	setPossibleObstructionListener(PossibleObstructionListener possibleObstructionListener)	For debugging purposes only.
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 Details

AdSession

public AdSession()

Method Details

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,
 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:

IllegalArgumentException - if the supplied error type is null.

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

IllegalStateException - if the ad session has finished.

registerAdView

public abstract void registerAdView(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.

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(View friendlyObstruction,
 FriendlyObstructionPurpose purpose,
 String detailedReason)

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. If the same friendly obstruction view is added multiple times in a session, the purpose and detailedReason parameters of only the first addition are used.

Parameters:

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

purpose - why this obstruction was necessary

detailedReason - an explanation for why this obstruction is part of the ad experience if not already obvious from the FriendlyObstructionPurpose selected. Must be 50 characters or less and only contain characters `A-z`,`0-9` or space.

Throws:

IllegalArgumentException - if the supplied friendly obstruction is null.

IllegalArgumentException - if the detailedReason is over 50 characters or contains a character that is not in `A-z`,`0-9` or a space.

removeFriendlyObstruction

public abstract void removeFriendlyObstruction(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:

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.

setPossibleObstructionListener

public abstract void setPossibleObstructionListener(PossibleObstructionListener possibleObstructionListener)

For debugging purposes only. Sets a PossibleObstructionListener on the AdSession that will listen for views that could be obstructing the ad view. Only meant to be used by integrators who are having trouble determining which views are obstructing their ad views. Passing in a value of null will unset a previously set obstruction listener.

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:

IllegalArgumentException - if the supplied adSessionContext is null.

IllegalStateException - if this method has been executed before OM SDK has been activated.