Introduction

When attempting to play client side ads (CSAI) via Bitmovin Player, it may happen that they don't play as expected. In cases like this, it's important to determine whether the issue is originating on the environment, on the ad tag, on the IMA SDK, on the player, or it's simply an unsupported case.

Initial troubleshooting

Gather details

Make sure you know what player SDKs are affected (Web, iOS, Android...), what ad tag types are affected (VAST, VPAID, VMAP...) and what player module is being used to load the ads (default IMA module, or custom Bitmovin Advertising Module)

Confirm support status

Check whether your use case is actually supported or not

Discard any environment issues

• If the issue only happens on Web, ensure no ad blocker, browser extension or firewall/proxy/VPN is blocking the ads, and that the issue is reproducible across multiple machines/networks (not just isolated users)
• If the issue also happens on mobile native SDKs, still check whether any firewall/proxy/VPN might be blocking the ads

Discard any issues on your ad tag

Take your ad tag URL and test it on independent validators:

• Official Google IMA validator
• External validators like this one, which supports VMAP besides VAST

If it doesn't play there (and sample ad tags similar to yours do), the issue is on the ad tag itself and has nothing to do with Bitmovin Player. You should reach out to your ad provider to fix it.

Review player implementation

If you have reached this point, it means you've already verified that your use case is supported and the ad tag is valid and plays in external validators. Hence, it's time to review the implementation at player level.

Verify that right configuration has been applied

Compare your player implementation with our documentation to ensure everything has been configured as expected.

• Web SDK
• Android/AndroidTV SDK
• iOS/tvOS SDK
• React Native SDK

Discard advertising module issues

By default our player handles advertisement via IMA module which relies on Google IMA SDK, but it's also possible to override that behaviour and let our own module (BAM - Bitmovin Advertising Module) handle ads instead. This could have a noticeable impact on the playback experience, so, as a quick temporary test:

• If you're using default IMA module, switch to BAM and check whether the issue still happens with this module or not
• Vice-versa, if you're using BAM, switch to default IMA module and check whether the issue still happens with this module or not

Discard custom app issues

Due to the complexity, custom code and 3rd party libraries typically used by custom apps, it's common to see that any of those components could be introducing problems or having a negative impact on the issue. As such, it's a recommended best practice to attempt replicating the issue by loading your specific ad tag via any of our sample apps:

• Web player
• Android/AndroidTV player
• iOS/tvOS player
• React Native player

Deeper investigation

Listen to ad error callbacks

Besides the high level error that might be fired by the player, Bitmovin Player also fires a dedicated adError event when an ad fails to play, whose response contains further details about what might be going wrong. It's recommended to listen to them and inspect the response body.

Web:

• AdError event
• Event handler

Android/AndroidTV:

• AdError event
• Event subscriber

iOS/tvOS:

• AdError event
• Event listener

React Native:

• AdError event
• Event listener

It's important to note that the error message and error code returned by these AdError events is typically coming from IMA SDK directly (unless BAM is used) or from the ad spec (eg. VAST), so for explanations about those errors please refer to Google's official documentation:

• VAST error codes
• IMA SDK error codes (for Web; similar pages available for iOS, Android...)

Inspect Observability sessions

If you have Observability enabled, you could navigate to Bitmovin Dashboard Ad Debugging section to get a filtered view about what's failing and where, and what's the real impact across your audience.

Ask Bitmovin Support

If you're still unable to resolve the issue after exhausting investigation on your end as per above steps, it's time to raise a support ticket via your Bitmovin Dashboard, so our team can help you out.