# Best Practices for Disabling OM SDK ## Objective This document provides "kill switch" guidance for integrators of Open Measurement SDK. The integration partner should include a mechanism to disable execution of OM SDK for two situations: if the partner finds that OMID measurement is interfering with their apps, or if there is a bug in the partner's integration that generates bad OMID data. This document describes two possible ways to implement a kill switch: through remote configuration of OM in their app/SDK; or by having ads include metadata for enabling/disabling OM. ## Background Open Measurement SDK provides a mechanism for ad verification. Integration partners (application publishers and ad SDK implementers) add OM SDK native code to applications, and they provide a JavaScript environment to run the OM SDK JavaScript service (omsdk-v1.js). OM SDK provides the OMID API for verification scripts running inside the creative or loaded from verification resources (such as from VAST 4.1). An application or ad SDK causes OM SDK code to run in two key lifecycles: * The app initializes OM SDK with Omid.activate() once before making any OMID-capable ad requests. The initialization sets up internal OM SDK data structures and installs application lifecycle listeners. * For each ad it displays, the app creates an OMID ad session, which will be active until the app calls session.finish(). While the session is active, OM SDK periodically traverses the app's view hierarchy to determine the visibility of the ad view and sends that information to the OM SDK JavaScript service. To meet MRC requirements, the view traversal occurs every 200ms during the ad session. OM SDK also relays ad events (impressions and video events) to the OM SDK JS service during the ad session. There are two situations where an integration partner should disable running OM SDK. 1. Although the Open Measurement Working Group has made strong efforts to ensure that OM SDK should not affect application behavior or ad performance, there is a possibility that running its code causes a problem for some apps or ad traffic. Having a mechanism to disable OMID ad sessions for certain versions of OM SDK is one way to mitigate that risk. 1. The partner's OM integration may have bugs that cause some ad placements or creative types to produce incorrect OMID data. Erroneous OMID data prevents verification services from trusting the integration, and it can cause the partner to lose certification for its measurements. Integration bugs may be found after the app is in the field, and it takes time for the integrator to fix issues and for users to download new versions of the app. Having a mechanism to disable OMID ad sessions for buggy integrations lets the partner use OMID for non-buggy integrations while waiting for users to download new versions. Note that when an OM integration disables an OMID ad session, verification scripts included in the HTML creative will not receive events, and verification resources provided in VAST or native ads will not even run. The integration must signal that OMID is disabled through other means, such as the VAST 4.1 "verificationNotExecuted" event. ### Terms used in this document * Integration partner: The application publisher or ad SDK implementer adding OM SDK support to their app/SDK. * OM integration: The code written by the integration partner that calls OM SDK. * Ad system: Back end service providing ads to an app or ad SDK, including ad serving, managing creatives, and RTB transactions. * Ad server: The component of the ad system which receives ad requests from the app or ad SDK and returns creatives. ## Suggested Practices OM integration should implement a "kill switch" that disables OM sessions on a per-impression basis. Two possible techniques are described here. An integration can one or both of them, or it can implement a different technique. ### Technique 1: Disable OM through remote configuration Some apps and ad SDKs have a remote configuration capability, where the app/SDK periodically gets new configurations from a server. The OM integrator could use such remote configuration to disable OM when the app/SDK runs. How it might work in the app: * When the app starts, it reads the remote configuration. * If the configuration says "enable OM", it activates OM SDK and creates an OMID ad session for each of the ads it shows. * In its ad requests, it signals OM capability (such as through the OpenRTB "api" field and VAST "[APIFRAMEWORKS]" macro). * If the configuration says "disable OM", it makes no calls to OM SDK. * In its ad requests, it does not include OM among the API capabilities it passes to OpenRTB or VAST macros. * If it gets verification resources, it triggers events to signal that the scripts will not run (such as the VAST "verificationNotExecuted" event). How the integration partner would support it: * They must be able provide remote configurations to different versions of their app/SDK. * They must monitor the performance of the different versions of their app/SDK, both user-visible issues (like crashes) and ad behavior (such as click rate changes). * They must have a support channel to process reports from verification services about bad OM data. * When monitoring or support channels indicate a problem, they isolate which versions of their app/SDK have the problem. Then they use the remote configuration system to disable OM on the affected versions. The other versions of their app/SDK can continue to enable (run) OM. * They should notify customer support channels when OMID ad sessions are disabled for a significant amount of traffic. A variation of the approach: * The configuration options could enable OM on a per creative-type basis. * In this variation, the integration would still activate OM SDK, but it would only enable/disable OM for specific creative types. For example, it could enable OM for display ads and disable it for video ads. * Note that the integration still must propagate the correct OpenRTB flags and VAST macros for the different creative types. In the example, when the app/SDK disables OM for video but enables it for display, it would not indicate OM support in the VAST "[APIFRAMEWORKS]" macro, or OpenRTB Video.api field, but it would signal OM support in the OpenRTB Display.api field. When to use Technique 1: * This a largely client-side technique — the app/SDK changes its behavior for all requests based on the configuration flag(s). * It affects all ads for a version of the app, placement, or high-level creative type (video or display). It can't disable OM only for particular formats that might issues. ### Technique 2: Disable OM on an ad session basis Some apps and ad SDKs configure how they render ads based on the data in ad responses. The OM integration could use data in the ad response to enable or disable the OMID ad session for that ad. How it might work in the app: * When the app/SDK starts, it activates OM SDK. * When the app/SDK makes an ad request to its ad server, it includes version information. * Code in the ad server decides whether to enable or disable OM based on the version information in the ad request. * If the ad server decides to enable OM, it signals OM capability (such as through the OpenRTB "api" field and VAST "[APIFRAMEWORKS]" macro). * If the ad server decides to disable OM, it does not include OM among the API capabilities it passes to OpenRTB or VAST macros. * The server includes data in the ad response about enabling/disabling OM, and the app/SDK checks that data. * If the data says "enable OM", it starts an OMID ad session. * If the data says "disable OM", it does not start an OMID ad session. If it received verification resources, it triggers events to signal that the scripts will not run (such as the VAST "verificationNotExecuted" event). How the integration partner would support it: * They must run code on the ad server when processing an ad request, so they can recognize versions of the app/SDK, enable/disable OM, and modify the ad response to include the enablement data. * They must monitor performance so that they can recognize problems that may be caused by particular versions of of the app/SDK or types of ads. * They must have a support channel to process reports from verification services about bad OM data. * When monitoring or support channels indicate a problem, they isolate which versions of their app/SDK have the problem. Then they use configure the ad server to disable OM on the affected versions or ad formats. The other versions of their app/SDK and formats can continue to enable (run) OM. * They should notify customer support channels when OMID ad sessions are disabled for a significant amount of traffic. When to use Technique 2: * This a largely server-side technique — the ad server runs much of the decision-making code. It can't be used if the app/SDK doesn't control its ad serving. * It can support disabling OM for a fine slice of traffic, such as one particular buggy format. ## Implementing the practices ### Monitoring app performance Many applications and ad SDKs send information about performance back to the application publisher and ad system. The performance data can include things like error counts, memory usage, ad statistics, etc. If possible, the version of OM SDK should be included in such performance reports. This could be included as an explicit OM SDK version parameter (described below). Alternatively, the app or ad SDK publisher can keep track of the version numbers of the OM SDK they build into the app/SDK, and include the version of the app or ad SDK with performance reports. ### Monitoring OMID events An OM integration partner can include their own verification scripts in OMID ad sessions, in addition to the verification scripts that might be included in the creative itself. They can use such scripts for monitoring the OM behavior of their app/SDK — how often it run scripts, ad visibility, etc. Data from monitoring can help identify and diagnose problems in measurement. The monitoring scripts would send HTTP pings to the integration partner's monitoring service. They should not send a ping for every OMID event — instead, they should send pings for significant events, such as start of session or end of session. The monitoring scripts could also run a bit of code to accumulate visible time (much like viewability detection) and include that in the pings. Monitoring pings should also include the native OM SDK version ("libraryVersion"), OM JavaScript service version ("serviceVersion"), the integration version ("partnerVersion"), the app ID ("appId"), OS type ("os"), OS version ("osVersion"), and device type ("deviceType"). Depending on the ad volume, the integration partner can choose to include monitoring scripts in all ads or just a fraction. ### Maintaining records of OM SDK versions Different releases of OM SDK native library could have varying effects on an application. For example, an issue triggered by OM SDK version 1.1.4 could be resolved in version 1.1.5. Since OM SDK is deployed in the app binary, the app developer or ad SDK should define a new version for each release, and they should maintain records of which OM SDK release is included in each of their app/SDK releases. That way they can use their app/SDK version to determine the OM SDK version. ### Sending partner name and version in ad requests If an ad SDK sends its version when it makes ad requests, its ad service can log the version for analyzing performance issues, and the service can choose to enable or disable OM SDK ad sessions for that ad request based on the client build. New standards for ad requests include parameters for the OM integration partner ID and version. In AdCOM (OpenRTB 3.0), it is the "omidpn" and "omidpv" fields; in VAST 4.1 it is the "[OMIDPARTNER]" macro. If the ad service is not using those standards, it should accept similar parameters. ### Data in ads for enabling/disabling OMID ad session In Technique 2 above, the ad service includes data to enable or disable the OMID ad session. There are two ways to represent that enablement data. One way is for the integration's client-side code to scan the creative for the presence of verification scripts or resources. When the ad service wants to disable OMID, it simply does not insert any verification resources into the ad. However, it is tricky to be comprehensive in this detection, especially for display ads. Also, if the ad service allows redirects, a redirect VAST could include verification resources, overriding a decision made by the main ad service. A more robust way to disable OMID ad sessions is to include metadata with the creative sent from the ad service to the ad SDK. The metadata could be sent within the ad format (e.g. a VAST extension for video, a JSON element for native ads), or as a custom HTTP header. When the ad SDK sees the metadata, it could decide to not create the OMID ad session. Some formats allow verification data to include non-script tracking events for cases when verification resources are not loaded. When the ad SDK disables an OMID ad session, it should emit those tracking events. For example, VAST 4.1 includes a "verificationNotExecuted" event that should be triggered in this case. ### Customer support When an ad service disables OMID ad sessions for a significant amount of time or traffic, it should indicate that to customer support channels. For example, if ad requests from a particular version of OM SDK are consistently disabled, the release notes for the version of the ad SDK which incorporated that build of OM SDK could say that it doesn't support OMID measurement.