OMIDAdSession

Objective-C

@interface OMIDAdSession : NSObject

Swift

class OMIDAdSession : NSObject

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.

  • The AdSession configuration is used for check owners.

    Declaration

    Objective-C

    @property (nonatomic, readonly) OMIDAdSessionConfiguration *_Nonnull configuration;

    Swift

    var configuration: OMIDAdSessionConfiguration { get }

  • The native view which is used for viewability tracking.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) UIView *mainAdView;

    Swift

    weak var mainAdView: UIView? { get set }

  • Initializes new ad session supplying the context.

    Note that creating an OMIDAdSession 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 OMIDAdSession. The easiest way is to create the OMIDAdSession in a webview delegate callback (-[WKNavigationDelegate webView:didFinishNavigation:]. 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.

    Declaration

    Objective-C

    - (nullable instancetype)
    initWithConfiguration:(nonnull OMIDAdSessionConfiguration *)configuration
         adSessionContext:(nonnull OMIDAdSessionContext *)context
                    error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(configuration: OMIDAdSessionConfiguration, adSessionContext context: OMIDAdSessionContext) throws

    Parameters

    context

    The context that provides the required information for initialising the ad session.

    Return Value

    A new OMIDAdSession instance, or nil if the supplied context is nil.

  • Notifies all verification providers that the ad session has started and ad view tracking will begin.

    This method will have no affect if called after the ad session has finished.

    Declaration

    Objective-C

    - (void)start;

    Swift

    func start()

  • Notifies all verification providers that the ad session has finished and all ad view tracking will stop.

    This method will have no affect 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.

    Declaration

    Objective-C

    - (void)finish;

    Swift

    func finish()

  • Adds friendly obstruction which should then be excluded from all ad session viewability calculations. It also provides a purpose and detailed reason string to pass forward to the measurement vendors.

    This method will have no affect if called after the ad session has finished.

    Declaration

    Objective-C

    - (BOOL)addFriendlyObstruction:(nonnull UIView *)friendlyObstruction
                       purpose:(OMIDFriendlyObstructionType)purpose
                detailedReason:(nullable NSString *)detailedReason
                         error:(NSError *_Nullable *_Nullable)error;

    Swift

    func addFriendlyObstruction(_ friendlyObstruction: UIView, purpose: OMIDFriendlyObstructionType, detailedReason: String?) throws

    Parameters

    friendlyObstruction

    The view to be excluded from all ad session viewability calculations.
    purpose

    The purpose of why this obstruction was necessary.
    detailedReason

    An explanation for why this obstruction is part of the ad experience if not already obvious from the purpose. Can be nil. If not nil, must be 50 characters or less and only contain characers A-z, 0-9, or spaces.

    Return Value

    Whether this friendly obstruction was successfully added. If the session has finished or the friendlyObstruction has already been added for this session, this method will return NO with no associated error object. However, if one or more arguments are against requirements, it will return NO with an error object assigned.

  • Removes registered friendly obstruction.

    This method will have no affect if called after the ad session has finished.

    Declaration

    Objective-C

    - (void)removeFriendlyObstruction:(nonnull UIView *)friendlyObstruction;

    Swift

    func removeFriendlyObstruction(_ friendlyObstruction: UIView)

    Parameters

    friendlyObstruction

    The view to be removed from the list of registered friendly obstructions.

  • Utility method to remove all registered friendly obstructions.

    This method will have no affect if called after the ad session has finished.

    Declaration

    Objective-C

    - (void)removeAllFriendlyObstructions;

    Swift

    func removeAllFriendlyObstructions()

  • Notifies the ad session that an error has occurred.

    When triggered all registered verification providers will be notified of this event.

    Declaration

    Objective-C

    - (void)logErrorWithType:(OMIDErrorType)errorType
                 message:(nonnull NSString *)message;

    Swift

    func logError(withType errorType: OMIDErrorType, message: String)

    Parameters

    errorType

    The type of error.
    message

    The message containing details of the error.