Migrating to OM SDK 1.4 from 1.3


OM SDK 1.4 is a minor update. It adds support for some key new use cases for OMID 1.4 while allowing scripts using OMID 1.2 and 1.3 to run correctly. Integrations (apps and SDKs) using OM SDK will only need to make code changes if adding support for Android TV.

OM SDK 1.4 Features

Summary of the new features added in OM SDK 1.4:

Semantic Versioning and Deprecation Policy

Open Measurement SDK follows semantic versioning for the OMID JavaScript session and verification interfaces. This means that verification scripts and session scripts for a major version (1.x) will run on any integration also running OM SDK 1.x. (Of course, features introduced in later minor versions of OM SDK will not be available when running on an integration using an earlier minor version.)

The native-layer integration APIs for Open Measurement SDK don’t follow semantic versioning. Instead, integration APIs are added or deprecated at minor releases and phased out gradually. This gives integrators time to import OM SDK with the new API, develop against it, and test their changes. This process takes at least 4 OM SDK patch releases (2 months):

Compatibility between Native and JavaScript layers of OM SDK

Apps that embed OM SDK can be out in the field for a long time. Users can be slow to download new versions of apps, and the app developers may choose to not update apps. So apps by a single OM SDK integrator can have a mix of versions.

That means that the OM SDK JavaScript service needs to be compatible with both old and current versions of the native layer, but not vice versa.

So an integration must ensure that they deploy new versions of the JavaScript service (omsdk-v1.js) before they deploy new versions of the native SDKs.

Suggested Migration Plan

  1. Start with the OM SDK JavaScript service, which is backward compatible with the installed base of apps using OM SDK 1.1.x, 1.2.x, and 1.3.x.
    1. Import the OM SDK JavaScript service (omsdk-v1.js) 1.4.x into your build system.
    2. Test your existing (1.3.x) integration against the 1.4.x service. It should continue to work without any changes.
    3. Deploy the OM SDK 1.4.x JavaScript service. It should continue to work without new errors.
  2. Next rebuild your integration using the new OM SDK library code with a release of OM SDK 1.4.0 or later.
    1. Import the Android, iOS, and JavaScript libraries for OM SDK 1.4.0 or later into your build system. Your existing OM integration should work without changing source code.
    2. Test your software against OM SDK 1.4.0 or later. It should function the same.
    3. Deploy your software linked against OM SDK 1.4.0 or later. It should function the same.
  3. Then port your integration to use the new OM SDK 1.4 API.
    1. Still using OM SDK 1.4.0 or later, migrate your source code to use the new API.
    2. Test your migrated software. It should function the same, though the OMID events will include additional data.
    3. Deploy your migrated software.
  4. As OM SDK releases incremental versions (1.4.1, 1.4.2, etc.), import them into your build system, test your software, and deploy. You should not need any source code changes to your already migrated software.

Android TV Support

The OM SDK has been expanded to support Android TV (including Amazon Fire TV) operating systems.

Activating OM SDK

Previous versions of the OM SDK recommended activating the OM SDK at any time before the ad session, via the following code:


To allow for the OM SDK to detect signs of user interaction, the SDK has been modified to detect app activation (foregrounding) outside of an ad session. This is especially important on Android TV, where extended periods of no activity is a concern. Please activate the SDK as early as possible in the app’s lifecycle, ideally in the Application subclass like so:

public class MyApplication extends Application {
  public void onCreate() {
    // Other logic.

  private void initializeOmsdk() {
    boolean activated = Omid.activate(applicationContext);
    if (!activated) {
      // SDK failed to activate. Handle appropriately.

Additionally, please notify the OM SDK when a user interacts with the app.

This includes launching the app (as seen in the above example) since that is a user activity but cannot be detected automatically by the OM SDK (subsequent foregrounds are automatically detected as long as the OM SDK has been activated).

Note, rather than instrument all user interactions, identify those key interactions leading up to the ad impression prior to starting an ad session. Some examples are navigating to the view which displays the ad, selecting content which includes the ad, video pause/resume interactions prior to displaying the ad, and user response to an “are you still watching?” prompt.

Note, avoid instrumenting ambiguous events that can also be triggered programatically. Consider the following example:

public void buttonTapped() {
    // Instrument here, if `buttonTapped` is exclusively triggered by the user tapping on the button.
private void doSomething() {
    // Don't instrument here as this method might also get triggered in other code paths.
public void anotherCodepath() {

Migrating Verification Scripts

Per the semantic versioning policy, verification scripts using only OMID 1.3 features do not need any modification to run on integrations using OM SDK 1.4. For a verification script, the changes in OM SDK 1.4 are purely additive — they will receive the same data as in 1.3, plus some additional data that 1.4 provides. Nonetheless, verification providers are encouraged to use OMID 1.4 data when present.

Verification scripts will be receiving a new signal for the device category on the Context object on sessionStart events, covering if the device is a mobile, desktop or CTV device. This will allow verification scripts to more easily determine if a device is an Android TV device compared to parsing the operating system information already included in 1.3.

Verification scripts should be aware that when the screen is detected as off, the reason for no viewability will be reported as no output device detected (‘noOutputDevice’), and as the app is backgrounded (‘backgrounded’). This is to align CTV reporting with the current behavior for mobile devices.

Additionally, the timestamp of last activity will be reported on sessionStart events as a singular timestamp.