interactiveadvertisingbureau / open-measurement-jsclients

Open-Measurement-JSClients

Overview

This repository contains the client JavaScript code of Open Measurement SDK, also known as OM SDK JS. It has two primary components:

• OMID JS Verification Client (omid-verification-client-v1.js) is used by verification scripts to communicate with OMID JS Service. It handles situations when the verification script runs in the same HTML document as the creative (in the top level of the webview), or in a cross-domain iframe, or in an invisible webview or DOM-less JavaScript execution environment for native ads. Verification scripts include the OMID JS Verification Client source code at build time (when the verification script is transpiled/minified).

• OMID JS Session Client (omid-session-client-v1.js) is used by integration partners to perform ad session activities in the JavaScript layer. It functions both at the top level of the webview and in a cross-domain iframe. Ad SDKs include its source code into ad HTML at build time.

Folder Structure

/

Contains the files covered under Apache License 2.0.

src/

Contains the source code.

src/common/

Contains source code files that are shared across multiple binaries.

src/externs/

Contains externs declarations used by Google Closure compiler when building OMID JS client binaries.

src/session-client/

Contains all source code files that comprise the OMID JS Session Client and go into the omid-session-client-v1.js binary.

src/validation-verification-script/

Contains source code files that comprise the example verification script and go into the omid-validation-verification-script-v1.js binary.

src/verification-client/

Contains all source code files that comprise the OMID JS Verification Client and go into the omid-verification-client-v1.js binary.

creatives/

Contains all source code files that comprise the HTML creatives used by reference Apps.

creatives/display/

Contains all source code files that comprise the display HTML creative used by reference Apps.

creatives/video/

Contains all source code files that comprise the video HTML creative used by reference Apps.

test/unit/

Contains utility files as well as subdirectories of source code files used for unit tests.

test/unit/common/

Contains source code files used for unit tests of shared code (src/common/).

test/unit/session-client/

Contains source code files used for unit tests related to the OMID JS Session Client (src/session-client/).

test/unit/verification-client/

Contains source code files used for unit tests related to the OMID JS Verification Client (src/verification-client/).

test/validation-verification-script/

Contains source code files used for unit tests related to src/validation-verification-script/.

bin/

This folder will be ignored for code submissions (through .gitignore). The OMID JS Session Client binary (omid-session-client-v1.js) and the OMID JS Verification Client binary (omid-verification-client-v1.js) are generated here during a build.

package.json

npm configuration and build file.

Developer Setup

The JavaScript tools are managed using an NPM project. Google Closure compiler composes modules together and minifies the output JavaScript binary. Builds are automated with Gulp. Tests are written with Jasmine and executed with Karma.

Prerequisites

• Node version 8.4.0 or later
• NPM version 5.3.0. Specifically use v5.3.0 because newer versions have issues.
• Java Runtime environment

Clone the Repository

git clone [email protected]:InteractiveAdvertisingBureau/Open-Measurement-JSClients.git
cd Open-Measurement-JSClients

Install Tools

Running the following command will download and install the dependencies locally, into ./node_modules/:

npm install

Run npm list to see the tree of installed dependencies. Note: If you are experiencing issues here, check your version of npm via npm -v, specifically, ensure that you are using npm version 5.3.0. See "Prerequisites" above. After this step, the repo is ready to be built.

Building

Running the following command builds omid-session-client-v1.js, omid-verification-client-v1.js, and omid-compliance-verification-client-v1.js, locally in a new ./bin/ folder. Note that running build will always first remove any and all existing content in./bin/ prior to producing the output bundles.

npm run build

Consuming

The build products omid-session-client-v1.js and omid-verification-client-v1.js are UMD modules. Therefore, they can be consumed in CommonJS, Google Closure, and generic environments. The following examples show how the VerificationClient can be imported. The same logic can be applied to the SessionClient.

CommonJS

Make sure the require statement reflects the path to the omid-verification-client-v1.js file. The following example works when the omid-verification-client-v1.js file sits in the same directory as the example source file.

const Omid = require('./omid-verification-client-v1');
const {OmidVerificationClient} = Omid;

Google Closure

Add the OMID source files to the Google Closure compiler (version 20200112.0.0 or later).

For the verification client these are:

• public/src/common/**.js
• public/src/verification-client/**.js

For the session client these are:

• public/src/common/**.js
• public/src/session-client/**.js

And the code for the verification client (similar pattern for the session client):

const OmidVerificationClient = goog.require('omid.verificationClient.VerificationClient');

Globals (generic approach)

Prior to running the example code, the omid-verification-client-v1.js must have already been loaded and run in the current context. This is what causes the global to be exported. One way of doing this is by using a <script\> tag.

<html>
  <head>
    <script src="./omid-verification-client-v1.js"></script>
    <script src="./your-verification-script.js"></script>
  </head>
  <body></body>
</html>

Another way to do this is by concatenating omid-verification-client-v1.js into the top of your-verification-script.js.

To access the VerificationClient API in your-verification-script.js, use the following:

const OmidVerificationClient =
    OmidVerificationClient && OmidVerificationClient['4.0.0'];

Example HTML Creatives

The html creatives are built as part of the main build script(npm run build), but can be built separately.

To build display creative:

npm run build-display-creative

To build video creative:

npm run build-video-creative

Testing

Unit Tests

To run all unit tests:

npm run test

or the shorthand alias:

npm t

It will bring up a Chrome instance orchestrated by the Karma runner, which will run the tests once, print the results, and exit.

Continuously Run Unit Tests

In order to have Karma runner loop forever, waiting for any changes in the production code or test code, use the following command.

npm run watch-unit-tests

Tracking Changes

During each release (in other words, a version number increase), a single commit is made to this repository with all of the changes. For a more readable summary of changes, consult the CHANGELOG.md.

open-measurement-jsclients's Issues

id for setTimeout and setInterval are prone to errors

Hello,

We are using the verification client setTimeout method to compute a custom viewability.
As it is using an internal generation of id's (starting at 0) it is prone to errors as it is using a falsy value and so we need to explicitly check against undefined
if (timeoutId !== undefined) { ... } instead of if(timeoutId) { ... }

I can suggest a PR where we change the id returned to start at 1. WDYT?
https://github.com/InteractiveAdvertisingBureau/Open-Measurement-JSClients/blob/master/src/verification-client/verification-client.js#L381

Thanks!

Every file coming out of the build is 2kb

I cloned the repo on a Windows 10 machine running Node 12.7, NPM 6.10.2 and JRE 8 Update 231. Ran npm install in the root, and then npm build - the build completed successfully, but each of the output files is only 2KB in size and contains only a bit of short bootstrapping code. Also the directory created in the bin directory is named omsdk-js-undefined which is clearly wrong but may or may not be related. Any advice appreciated.

Issue building on Windows 10

When trying to build on Windows 10, I get a compilation error when trying to build the verification client, with the following message:

gulp-google-closure-compiler: ERROR - [JSC_MISSING_ENTRY_ERROR] required entry point "omid.verificat
ionClient.VerificationClient" never provided

Please note that the two prior build tasks build-session-client and package-session-client run successfully.

Java version details:

java version "1.8.0_401"
Java(TM) SE Runtime Environment (build 1.8.0_401-b10)
Java HotSpot(TM) 64-Bit Server VM (build 25.401-b10, mixed mode)

multiple creatives

Hi,

i'm trying to implement omid interface for video player, but there is gap in documentation. Verification is related to VAST Ad tag which can contain multiple Creative tags, f.e. linear(videoElement ) + companion variations(slotElement). Documentation menions only single element for sessionStart, either a videoElement or slotElement (which makes sense because there is no identifier like evt.creativeId). So only way to measure also companion that comes to my mind is to create multiple adSessionId for each element and run multiple sessions in parallel which contradicts property name adSessionId (should be slotSessionId). The second way is to skip measuring companion variations.

Thanks.

is there a method to check if open measurement integration is present only for video and not for display?

on a web page we have integrated bitmovin player with the omsdk module.
but on the same page, omsdk for display ads is not integrated. can for example ias, doubleverify, etc. recognize that for display omid is not present but for video it is?
in the web page, an iframe is created with the id 'omid_v1_present' and from what I have seen, this iframe is the same for video advertising and display advertising.
thanks in advance

Error in Open-Measurement-SDKJS documentation points to wrong interfaces

Hey,

While implementing OM for Web, I noticed two problems in the documenation at https://interactiveadvertisingbureau.github.io/Open-Measurement-SDKJS/
As there's no clear way given to contact anyone responsible, I assume it's okay to raise the issue here - however please feel free to move it to the correct location or give me pointers to do so myself.

At 4. Create and Start the AdSession:
adSession.setVideoElement(VIDEO_ELEMENT) should be context.setVideoElement(VIDEO_ELEMENT)

At 5. Signal Ad and Video Events:
videoEvents.loaded(vastProperties) should be adEvents.loaded(vastProperties)

Take care, and thanks!

`<iframe srcdoc` conflict with Content-Security-Policy settings

Hello,
We're trying to introduce omsdk on our website, and the sdk creates an iframe with srcdoc attribute, the value of srcdoc contains inline script, which conflicts with our website's Content Security Policy, makes the sdk fail to execute.
(In order to avoid XSS attack, we set script-src to forbid inline script.)

Here is a simplest example to show the conflict.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="Content-Security-Policy" content="script-src 'self'">
</head>
<body>
  <iframe srcdoc="<p>hello</p><script>alert(1)</script>"></iframe>
</body>
</html>

The browser will console error:

So I wonder if it's possible to modify the inline script as

<script type="text/template">
 window['omidVerificationProperties'] = { // blah blah };
</script>

then eval the content inside "text/template" in your external javascript. This could be a workaround for CSP.

Looking forward to your reply. Thanks in advance!

omid_v1_present iframe missing sandbox attribute

Overview

The iframe created to detect if omid is present, or not, does not contain a sandbox attribute.

Current output:

<iframe id="omid_v1_present" name="omid_v1_present" style="display: none;">
...
</iframe>

Desired output:

<iframe id="omid_v1_present" name="omid_v1_present" style="display: none;" sandbox>
...
</iframe>

Code reference.

Why is this a problem?

This is a problem because the sandbox attribute "controls the restrictions applied to the content embedded in the <iframe>" (ref). Although this iframe only exists so that verification scripts can detect if omid is present, it is best practice to enable all iframe restrictions.

What can be done?

Add sandbox to the iframe.

Questions about future updates

Hello, my name is Jong Park and I am a senior engineer in JW Player. We are working to support OM Web in our Web Player, and would highly appreciate if we could have a couple of clarifications.

1. Are any future plans for publishing OM JS Client to npm so that we can pull down the code as a dependency?
2. When using the github source code as opposed to using the zip files from IAB tools, what is the expectation to handle upgrades to newer versions (seems like there are no version tags in this repo, and the updates are pushed to master branch). Should we fork this branch, and make updates by merging this repo when newer versions come out?

Thank you for your help!

`session.start` and `session.finish` missing in session API

Hey,

I've tried to integrate the JS client into our web player but I've multiple issues due to lacks within the documentation for web. Could you please help me? I will try to give you an example code where the session somehow is/can not be started:

import { OmidSessionClient } from './omid-session-client-v1.js';
const {
  VerificationScriptResource,
  Partner,
  Context,
  AdSession,
  AdEvents,
  VideoEvents
} = OmidSessionClient;

const verificationScriptResource = new VerificationScriptResource(
          resourceUrl,
          vendorKey,
          verificationParameters
        );
const partner = new Partner(config.omPartnerName, VERSION);
const context = new Context(partner, [verificationScriptResource]);
context.setVideoElement(videoElement);
context.setSlotElement(domNode);
const session = new AdSession(context);
const adEvents = new AdEvents(session);
const videoEvents = new VideoEvents(session);
session.registerSessionObserver(event => {
      // it never gets here
});

// Here I'm missing the session.start api or similar and I don't know how to start the session from the player side

adEvents.impressionOccurred(); // throws that session is not started

Could you give me a hint what's going wrong please?

Regards,
Martin

Getting console error from sendMessage

Issue: console error from sendMessage
Browser: Chrome
System: MAC

We are using omweb included with moat video analytics. We are noticing a bunch of console errors from omweb code, please find complete error details below.

The source window of session client post messages cannot be changed from the source of the first message

any leads are greatly appreciated.

Promises on AdSession Tracks Issuing

We are using the client Web SDK in JavaScript to be able to send OMID tracking.

When we are about to close an Ad, due to an User Interaction, we call the method adContext.finish() before closing the Ad. The issue is that we do not know "how long" to wait before closing the Ad to be sure the Track is sent.
On a documentation I found on a Java Client, it is said 1 second. However, we found this a bit random when using this approach.

Is there a way to get a kind of promise to be sure when the track is sent ? Such as:

await adContext.finish();
closeAd();

Use Releases

Hey there,

Do you have any plan of use the releases of github ? We would like to follow this repository activity, but are only interested in releases.

Thanks !

Session start from JS is not supported in mobile app. Error from Chromecast receiver

I am adding Open Measurement to a Chromecast receiver Javascript app but keep getting this error when starting the session: Session start from JS is not supported in mobile app. I went through the sample app a few times and I think everything is setup correctly, how do you determine if the sdk is being used in a mobile app?

how to export `src/common/event-typedefs.js`

When using Google Closure compiler with ADVANCED_OPTIMIZATIONS, the @typedef properties in src/common/event-typedefs.js get renamed which means things break.

There looks to be nothing relevant for us VerificationClient users in src/externs and there is no documented advice so it is unclear how this should be handled.

My awful solution is to concatenate constants.js and event-typedefs.js as a make shift externs file but either I am missing something or everyone has to manually do something like this?

Can we have an externs file for VerificationClient users please that preserves the the properties appearing in the events from OMID.registerSessionObserver or alternatively advise on what we all should be doing?

Example for Video

In the example you are setting the creative type to htmlVideo but in constants there is not mention of htmlVideo.

Example:

Open-Measurement-JSClients/creatives/video/omid_video_creative_session_main.js

Line 10 in 207f271

omidSession.setCreativeType('htmlVideo');

Open-Measurement-JSClients/src/common/constants.js

Line 412 in d1f08a1

VIDEO: 'video',

Which is the correct value for a video creative type?

Where is omsdk-v1.js ?

Hey there,

We manage to implement Omid with part of this repository, and the omsdk-v1.js which we download somehow (we don't remember).
We are curious to know where is the repository for this file, or if it's not, where is the official download link ?

Thanks

How to add verification script to html advertisement

Hi,

I'm implementing the OM SDK for iOS and Android.
We are having html advertisements were we need to add the necessary script to.
It's not clear for me in the documentation how to add the omid-validation-verification-script-v1 script in the html advertisement so we can verify our OM implementation.
We already tried to contact [email protected] but we have not got any response after weeks and couple reminders.
Can someone help us out with this?

Thanks!

npm run buildDeps is not working

npm run buildDeps command in reference-app-web is not working with following error

and it seems there is no build-web-service and build-domain-loader scripts in package.json of root