Setting up Ads in React Native

Ads can be configured statically in the player configuration or scheduled dynamically using using Player.scheduleAd.

The React Native SDK supports two advertising integrations:

  • Bitmovin Advertising Module (BAM): use AdSourceType.BITMOVIN. Available by default; no Google IMA dependency is required.
  • Google Interactive Media Ads (IMA): use AdSourceType.IMA. Starting with Bitmovin Player SDK version 1.30.0, Google IMA must be explicitly enabled in the native build.

Enabling Google IMA

For apps using Expo prebuild, add features.googleIMA: true to the existing Bitmovin plugin configuration in app.config.ts or app.json:

export default {
  // ...existing app configuration
  plugins: [
    [
      'bitmovin-player-react-native',
      {
        // ...existing Bitmovin options
        features: {
          // ...existing feature options
          googleIMA: true,
        },
      },
    ],
  ],
};

Rerun Expo prebuild, run pod install on iOS/tvOS, and rebuild the native app.

For projects maintained without Expo prebuild, follow the manual setup instructions.

Static Ad configuration

The easiest way to configure Ads is by adding the advertisingConfig property to the player configuration object. All that needs to be provided is a URL pointing to a target Ad tag along with the type of the tag.

const player = usePlayer({
  licenseKey: '<PLAYER_LICENSE_KEY>',
  advertisingConfig: {
    // Each object in `schedule` represents an `AdItem`.
    schedule: [
      // An `AdItem` represents a time slot within the streamed content dedicated to ads playback.
      {
        // Each item specifies a list of sources with a type and URL to the ad manifest in the ads
        // server. All but the first source act as fallback if the first one fails to load.
        // The start and end of an ad break are signaled via `AdBreakStartedEvent` and `AdBreakFinishedEvent`.
        sources: [
          {
            type: AdSourceType.IMA,
            tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
          },
          // Fallback sources...
        ],
        // Each item also specifies the position where it should appear during playback.
        // The possible position values are documented below.
        // The default value is `pre`.
        position: '20%',
      },
    ],
  },
});
const player = usePlayer({
  licenseKey: '<PLAYER_LICENSE_KEY>',
  advertisingConfig: {
    // Each object in `schedule` represents an `AdItem`.
    schedule: [
      // An `AdItem` represents a time slot within the streamed content dedicated to ads playback.
      {
        // Each item specifies a list of sources with a type and URL to the ad manifest in the ads
        // server. All but the first source act as fallback if the first one fails to load.
        // The start and end of an ad break are signaled via `AdBreakStartedEvent` and `AdBreakFinishedEvent`.
        sources: [
          {
            type: AdSourceType.BITMOVIN,
            tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
          },
          // Fallback sources...
        ],
        // Each item also specifies the position where it should appear during playback.
        // The possible position values are documented below.
        // The default value is `pre`.
        position: '20%',
      },
    ],
  },
});

The possible AdItem.position values are:

  • pre: pre-roll ad (for VoD and Live streaming; appears before playback starts)
  • post: post-roll ad (for VoD streaming only; appears after playback finishes)
  • Fractional seconds: e.g. 10, 12.5 (mid-roll ad, for VoD and Live streaming)
  • Percentage of the entire video duration: e.g. 25%, 50% (mid-roll ad, for VoD streaming only)
  • Timecode hh:mm:ss.mmm: e.g. 00:10:30.000, 01:00:00.000 (mid-roll ad, for VoD streaming only)

Dynamic Ad scheduling

To gain more flexibility, it is also possible to schedule an AdItem dynamically in code using the Player instance. To do this, you need to call the scheduleAd method.

// The object passed to `scheduleAd` must be an `AdItem`.
player.scheduleAd({
  // Ad source with fallbacks.
  sources: [
    {
      tag: '<AD-URL>',
      type: AdSourceType.IMA,
    },
  ],
});
// The object passed to `scheduleAd` must be an `AdItem`.
player.scheduleAd({
  // Ad source with fallbacks.
  sources: [
    {
      tag: '<AD-URL>',
      type: AdSourceType.BITMOVIN,
    },
  ],
});

An AdScheduledEvent is dispatched when the ad is successfully scheduled via scheduleAd.

Also, during playback, it's also possible to check whether an ad is being played with player.isAd() and skip the ad being currently played with player.skipAd() (see AdSkippedEvent).

Supported ad-related events

The supported PlayerView events for ads are:

  • onAdBreakFinished
  • onAdBreakStarted
  • onAdClicked
  • onAdError
  • onAdFinished
  • onAdManifestLoad
  • onAdManifestLoaded
  • onAdQuartile
  • onAdScheduled
  • onAdSkipped
  • onAdStarted

You can find a complete Ads example in the example app.

Troubleshooting

If Google IMA is disabled, AdSourceType.IMA ad sources are skipped. Setting advertisingConfig.ima does not enable the native Google IMA SDK. Its beforeInitialization callback is ignored, and a JavaScript warning is logged.

Enable Google IMA using the setup instructions above, then rebuild the native app.



Did this page help you?