Open Measurement

What is Open Measurement?

Advertisers/agencies use third-party measurement providers (verification vendors), such as MOAT, Meetrics, or Integral Ad Science, to provide ad verification and viewability measurements independently of the systems that serve and play ads. In order to provide these measurement services, measurement providers use JavaScript resources that are trafficked with the ad creative. These JavaScript resources interact with app environments at the time of ad delivery, collect data, and report it back to the advertisers/agencies. Advertisers use the collected data to optimize their campaigns and ensure ads are delivered to valid environments where viewers have the opportunity to interact with them.

Previously, you had to integrate multiple measurement providers' code with your app to give them access to the required data. Interactive Advertising Bureau (IAB) has designed the Open Measurement standard to facilitate the measurement of mobile in-app ads by third-party viewability and measurement providers without requiring their own SDK. The IAB Open Measurement SDK (OM SDK) consists of two components:
  • Native libraries for mobile (iOS and Android): The native libraries collect various signals regarding ad impressions and performance using direct communication with the mobile device’s native operating system and media players, and publish these signals using the Open Measurement Interface Definition (OMID) JavaScript API.
  • OMID JavaScript API: The OMID API signals the events to measurement providers using their JavaScript resources.

We have integrated the OM SDK with the Pulse Android SDK to make this communication possible when a third-party ad from Pulse is displayed in your native Android application. For more information, see Pulse Android SDK integration with OM SDK.

Key benefits

Using Open Measurement simplifies maintenance, reduces reporting inconsistencies, provides transparency, and inspires trust among all involved parties.
  • Publishers can provide required measurement data to all measurement providers and advertisers by accessing multiple measurement providers' SDKs collapsed into a single integration, simplifying maintenance without sacrificing functionality. Allowing such transparency can bring more demand for your inventory.
  • Advertisers can append the JavaScript resources from their measurement providers to their creatives. This provides them with greater transparency and greater insight into where their ads are viewed and how users interacted with the ads. It ensures them that their ads will be reaching real people and the right audiences, which allows them to buy more confidently.
  • Measurement providers can use their JavaScript resources to listen to the events coming from the OMID API and send that data to their servers. The collected data can then be used to calculate the viewable impressions, as defined by the Media Rating Council (MRC), and reported back to their clients.
    Note: The measurement providers' JavaScript resources are placed within the ad and served within the VAST response using the AdVerifications element. For more information, see Verification resources in VAST.

For more information, see official IAB documentation: Open Measurement SDK.

Pulse Android SDK integration with OM SDK

We have integrated the OM SDK version 1.2.22 with the Pulse Android SDK. To benefit from the OM SDK, upgrade to version 2.5.20.2.0 or later of our Android SDK. Collection and surfacing of impressions and viewability information is supported for normal and sponsor standard third-party ads (pre-rolls, mid-rolls, and post-rolls), which are VAST 2.0, 3.0, 4.0, and 4.1 compliant.

Using the Pulse Android SDK with OM SDK does not guarantee that ad verification and viewability measurement will work. The collection, processing, analysis, and reporting of information surfaced by the OM SDK is the responsibility of each measurement provider and requires them to collect additional information with their respective JavaScript resources that is served with the ad creative. Advertisers/agencies should run tests with each measurement provider to ensure that the provided verification scripts run as expected.

New methods

If you want to use the OM SDK for publishing ad events to measurement providers, you must call one of the below methods to initialize the OM SDK integration in Pulse Android SDK. The corresponding method should be called for each ad just before playing ad content otherwise ad session events will not be recorded. This notifies all involved measurement providers that the OMID ad session has started and ad view tracking will begin.

  • Create OMID ad session with friendly obstructions. Friendly obstructions are any native elements which you consider to be part of the ad, such as a close button, some logo text, or another decoration, so you should register them as friendly obstructions to exclude them from viewability calculations.
    OmidAdSession.createOmidAdSession(pulseVideoAd, context, adView, friendlyObstructions);
  • Create OMID ad session without friendly obstructions.
    OmidAdSession.createOmidAdSession(pulseVideoAd, context, adView);
Additional methods are available but have no effect if called after the OMID ad session has finished.
  • registerAdView: Ad view is the native view that OMID should consider for viewability tracking. If the ad view changes, for example due to fullscreen expansion, you need to call this method to update the ad view reference to whatever is appropriate at that time.
    OmidAdSession.registerAdView(adView);
  • addFriendlyObstructions: You should use this method to subsequently add friendly obstructions, if they appear at a later point during ad playback, which then excludes them from all ad session viewability calculations.
    OmidAdSession.addFriendlyObstructions(friendlyObstructions);
  • removeFriendlyObstructions: Remove registered friendly obstructions.
    OmidAdSession.removeFriendlyObstructions(friendlyObstructions);
  • removeAllFriendlyObstructions: Remove all registered friendly obstructions.
    OmidAdSession.removeAllFriendlyObstructions(friendlyObstructions);

For more information, see OmidAdSession.

Three new events related to viewability calculations are available:
  • When calling adStarted, report the player volume, with a range between 0 and 1 (default value is 1). Sending in the value ensures that the OM SDK has the correct initial player volume value.
    adStarted(playerVolume);
  • Notify all video listeners that the native video player volume has changed, with a range between 0 and 1. You do this by calling the following method:
    playerVolumeChanged(videoPlayerVolume);

    Device volume changes will be detected by the OM SDK.

  • Notify all video listeners that the native video player state has changed. You do this by calling the following method:
    playerStateChanged(playerState);
    • COLLAPSED: The player has been reduced from its original size. The video is still potentially visible.
      playerStateChanged(PlayerState.COLLAPSED);
    • MINIMIZED: The player is collapsed in such a way that the video is hidden. The video may or may not still be progressing in this state, and sound may be audible. This refers specifically to the video player state on the page, and not the state of the browser window.
      playerStateChanged(PlayerState.MINIMIZED);
    • NORMAL: The player's default playback size.
      playerStateChanged(PlayerState.NORMAL);
    • EXPANDED: The player has expanded from its original size.
      playerStateChanged(PlayerState.EXPANDED);
    • FULLSCREEN: The player has entered fullscreen mode.
      playerStateChanged(PlayerState.FULLSCREEN);

For more information, see PulseVideoAd and PlayerState.

Native app integration example scenario

The below sequence diagram does not include all events and assumes the following:
  • An advertiser/agency uses the services of a measurement provider.
  • A measurement provider provides the advertiser/agency with their JavaScript resources to append within the creatives.
  • The Pulse Android SDK is integrated with the OM SDK.
  • A publisher has the Pulse Android SDK version 2.5.20.2.0 or later integrated with their native Android app.
  • The publisher has a third-party ad booked in Pulse.

Integration with Pulse SDK and OM SDK example event sequence

Note:

For brevity, not all events are included.

  • *When calling adStarted, report the initial player volume, with a range between 0 and 1 (default value is 1). This ensures that the OM SDK has the correct initial player volume value.
  • **As playback progresses, the native app must also send the player volume changed event and the playback progress events (start, quartiles, paused, resumed, skipped, complete).
  • ***As playback progresses, the native app must also update the ad view if there are any changes, for example due to fullscreen expansion.

Measurements reported for each ad

Note: If the OM SDK fails to load a measurement provider's JavaScript resource, the ad continues playing without any events recorded for the corresponding measurement provider.

The following events signal to all involved measurement providers when key events and key states related to viewability calculations have occurred during an OMID ad session. The Pulse SDK integration with OM SDK signals the following ad session, user interaction, and video ad lifecycle events.

Ad session information

Measurements reported for the OMID ad session identify details for session start, finish, and any errors that occur.

  • sessionStart: This is always the first event fired for a session. Pulse SDK fires the event as soons as the OMID ad session has been initialized. It notifies all measurement providers that the OMID ad session has started and ad view tracking will begin. It does not imply that the ad has rendered or that the ad playback has started.
  • loaded: Notifies all video listeners that the player has loaded the video ad content, either fully or to the extent that it is ready to play.
  • impression: Notifies all measurement providers that an impression event should be recorded.
  • sessionError: This event is fired following ad playback, ad rendering, or other ad-related error. It notifies all measurement providers that an error has occurred during the OMID ad session, and includes the error type and message. There are two types of OMID ad session errors:
    • VIDEO: corresponds to REQUEST_FAILED Pulse ad error.
    • GENERIC: corresponds to all other Pulse ad errors, NO_SUPPORTED_MEDIA_FILE, REQUEST_TIMED_OUT, and COULD_NOT_PLAY.
  • sessionFinished: This event is fired in case of ad completed, ad skipped, or ad failed. It notifies all measurement providers that the OMID ad session has finished and all ad view tracking will stop. It indicates that measurement resources should start clean up and handle end-of-session reporting. This is always the last event sent for an OMID ad session.

User interactions

Measurements reported for user interactions include metrics for direct interactions, like clicks and view dimension changes.

  • click: Notifies all video listeners that the user clicked to load the ad's landing page.
  • geometryChange: This event is fired every time the ad container state changes so that any field of the viewport or ad view would change value from the previous report. Ad calls that signal a change in geometry are triggered every 200ms or when the dimensions of the ad change.

    The following is included: percentageInView, geometry, onScreenGeometry, measuringElement, containerGeometry, onScreenContainerGeometry, viewport width and height, adView, reasons, pixel, friendlyObstructions, declaredFriendlyObstructions.

Video ad lifecycle

Measurements reported for the video ad lifecycle include metrics for tracking the video player and ad events.

  • start: Notifies all video listeners that the video player has started playing the video ad.
  • firstQuartile: Notifies all video listeners that the video ad played continuously for at least 25% of the total duration.
  • midpoint: Notifies all video listeners that the video ad played continuously for at least 50% of the total duration.
  • thirdQuartile: Notifies all video listeners that the video ad played continuously for at least 75% of the total duration.
  • complete: Notifies all video listeners that the video ad played to the end for 100% of the total duration.
  • pause: Notifies all video listeners that video ad playback has paused due to user interaction.
  • resume: Notifies all video listeners that video ad playback has resumed (after being paused) due to user interaction.
  • skipped: Notifies all video listeners that video ad playback has stopped due to user skip interaction.
  • volumeChange: Notifies all video listeners that the native video player and/or device volume has changed, with a range between 0 and 1.
  • playerStateChange: Notifies all video listeners that the native video player state has changed, generally to resize. This includes moving from non-fullscreen to fullscreen state.

Pulse Android SDK event limitations

  • The following events are not tracked and signaled by the Pulse Android SDK even though they are supported by the OM SDK:
    • invitationAccept
    • bufferStart
    • bufferFinish
  • For the loaded event, autoplay is always sent as true.

Verification resources in VAST

This provides details around the information that measurement providers should load in the AdVerifications element, based on what is supported in the Pulse Android SDK integration with OM SDK.

The collection, processing, analysis, and reporting of information surfaced by the OM SDK is the responsibility of each measurement provider and requires them to collect additional information with their respective JavaScript resource that is served with the ad creative. Advertisers/agencies should run tests with each measurement provider to ensure that the provided verification scripts run as expected.

VAST 4.1

Ads must be configured to include the AdVerifications element. For example:
<AdVerifications>
    <Verification vendor=”company.com-omid”>
        <JavaScriptResource apiFramework="omid" browserOptional=”true”>
            <![CDATA[https://verification.com/omid_verification.js]]>
        </JavaScriptResource>
        <TrackingEvents>
            <Tracking event="verificationNotExecuted">
                <![CDATA[https://verification.com/trackingurl/[REASON]l]]>
            </Tracking>
        </TrackingEvents>
        <VerificationParameters>
            <![CDATA[parameter1=value1&parameter2=value2&parameter3=value3]]>
        </VerificationParameters>
    </Verification>
</AdVerifications>

Earlier versions: VAST 2.0, 3.0, 4.0

Ads must be configured to include the <Extension type="AdVerifications"> in the Extensions element. The AdVerifications schema is the same as in VAST 4.1. For example:
<Extensions>
    <Extension type="AdVerifications">
        <AdVerifications>
            <Verification vendor=”company.com-omid”>
                <JavaScriptResource apiFramework="omid" browserOptional="true">
                    <![CDATA[https://verification.com/omid_verification.js]]>
                </JavaScriptResource>
                <TrackingEvents>
                    <Tracking event="verificationNotExecuted">
                        <![CDATA[https://verification.com/trackingurl]]>
                    </Tracking>
                </TrackingEvents>
                <VerificationParameters>
                    <![CDATA[parameter1=value1&parameter2=value2&parameter3=value3]]>
                </VerificationParameters>
            </Verification>
        </AdVerifications>
    </Extension>
</Extensions>
The AdVerifications element can contain one or more Verification elements.
VAST Element Description Attributes
Verification Contains the resources and metadata required to execute third-party measurement code to verify creative playback for a single measurement provider. Multiple Verification elements may be listed, in order to support multiple measurement providers. (Required) vendor: the identifier for a measurement provider. The recommended format is [domain]-[useCase], to avoid name collisions. For example, vendor="company.com-omid".
JavaScriptResource Represents the container for the URI to the measurement provider's JavaScript resource used to collect verification data. Contains a CDATA-wrapped URI to the JavaScript resource.
Note: OM SDK supports only the JavaScriptResource in the Verification element.
  • (Required) apiFramework: the name of the API framework used to execute the ad verification code.

    OM SDK supports only OMID as the API framework: apiFramework="omid"

    Note: The IAB Tech Lab strongly recommends using code that supports the Open Measurement Interface Definition (OMID) for this purpose, and strongly against using VPAID (which is being retired).
  • (Required) browserOptional: indicates the kind of environment where players execute the code. Players that execute verification code in a non-browser environment may only execute resources marked browserOptional="true".
TrackingEvents The measurement provider may provide URIs for tracking events relating to the execution of their code during the ad session. One event type is currently supported: verificationNotExecuted -
Tracking

Defines the event to be tracked by the measurement provider. Contains a CDATA-wrapped URI to the tracking resource for the event specified using the event attribute. One event type is currently supported: verificationNotExecuted.

The [REASON] macro should be supported specifically in URIs for this event type. The reason code corresponds to the cause of the failure.
Reason Code Description
1

VERIFICATION_RESOURCE_REJECTED: Pulse SDK does not recognize or allow code from the measurement provider in the parent.

Happens if vendor key is null or empty.

2

VERIFICATION_NOT_SUPPORTED: Pulse SDK does not support verification through OM SDK for given API framework.

Happens if:
  • apiFramework is not "omid"
  • browserOptional is either not defined or false
3

VERIFICATION_RESOURCE_LOAD_ERROR: Error during resource load. Pulse SDK was not able to fetch the measurement provider's JavaScript resource.

Happens if JavaScriptResource URL is null.

Note: The verificationNotExecuted event is not tracked in case the OM SDK fails to load the JavaScript resource.
(Required) event: A string that defines the event being tracked. Only verificationNotExecuted event is currently supported and means that the player did not or was not able to execute the provided verification code.
VerificationParameters Contains a CDATA-wrapped string intended for bootstrapping the verification code and providing metadata about the current impression. The format of the string is up to the individual measurement provider. -