Forensic Watermarking with the Native SDKs

In this topic, you will learn how to use the Brightcove Native SDKs to deliver videos protected with Forensic Watermarking.


With Forensic Watermarking, you can protect your premium content from piracy and unauthorized content sharing. This feature adds an invisible watermark to your videos, allowing you to track any content leaks.

For more information, see the Overview: Forensic Watermarking document.


The following requirements are needed to support this feature:


There are setup requirements in addition to configuring your player. For details, see the Overview: Forensic Watermarking document.

Device OS version

  • Android 6.0 and newer
  • iOS 11.0 and newer

Brightcove SDK version

  • Native SDK for Android 6.16.3 and newer
  • Native SDK for iOS 6.9.0 and newer

Android Implementation

Configuration for Forensic Watermarking is performed at the Video level.

  1. The player must be integrated with your registration system so that a Viewer ID is passed on the analytics web beacon (in the user field).

    For example:

    HashMap<String, String> baseParams = new HashMap<>();
      baseParams.put(Analytics.Fields.USER, "viewer id");
      baseParams.put(Analytics.Fields.APPLICATION_ID, "application id");
      HashMap<String, Object> eventParams = new HashMap<>();
      eventParams.put(Analytics.Fields.BASE_PARAMS, baseParams);
      eventEmitter.emit(EventType.ADD_ANALYTICS_BASE_PARAMS, eventParams);          
  2. In the Catalog.findVideo or Catalog.findPlaylist method calls, add the VideoUtil method to add your watermarking token.

    In the onVideo callback

    public void onVideo(Video video) {
        VideoUtil.addWatermarkingToken(video, yourWatermarkingToken);

    In the onPlaylist callback

    public void onPlaylist(Playlist playlist) {
      for (Video video : testPlaylist.getVideos()) {
          VideoUtil.addWatermarkingToken(video, yourWatermarkingToken);
  3. With this call in place, when the Catalog retrieves the Video or Playlist metadata from the Playback API, the VideoUtil class will replace the watermarking token placeholder {WMT} with the token value, wherever it may occur in the Video’s source URLs. This token can be replaced for each video in a playlist that may be watermarked.


To cast a watermarked video, you need to supply your application ID, watermarking token, and user ID when building your BrightcoveCastCustomData object with the Cast plugin.

In your code to set up the BrightcoveCastCustomData object, add this line:

public static void setupGoogleCast() {
GoogleCastComponent.Builder castPluginBuilder = new GoogleCastComponent.Builder(eventEmitter, context)

    BrightcoveCastCustomData.Builder customDataBuilder = new BrightcoveCastCustomData.Builder(context)
        // Add the custom data elements to the castPluginBuilder

When you open a cast connection with a watermarked video, you should see a customData object formatted like this:

      "accountId": "yourAccountId",
      "analyticsParams": {
          "application": "yourApplicationId",
          "user": "yourUserId"
      "catalogParams": {
          "type": "video",
          "id": "videoId",
          "policyKey": "yourPolicyKey",
          "watermarkingToken": "yourWatermarkingToken"

Offline Playback

The process for downloading a video can involve more than one Catalog call to retrieve the current Video metadata. Brightcove recommends adding the onVideo callback code above to your callbacks that may be present when acquiring purchase or rental licenses and when downloading the video.

Once the video has been downloaded, offline playback should work as usual.

For details, see the Offline Playback sample app.

iOS Implementation

To configure a player to use Forensic Watermarking, follow these steps:

  1. The player must be integrated with your registration system so that a Viewer ID is passed on the analytics web beacon (in the user field).

    Here, you'll provide values for user ID and application ID:

        [BCOVGlobalConfiguration.sharedConfig setValue:@{
          @"privateUser": @"your user id",
          @"privateApplication": @"your application id"
      @catch (NSException *e)
        NSLog(@"%@", e.description);
  2. As part of the Brightcove catalog request for a single video or a playlist, you will provide your NAGRA watermark token. This is done using the watermarkingToken property.

    Add your watermarking token to the playback service.

    * The watermarking token for use with Forensic Watermarking
    @property (nonatomic, copy) NSString *watermarkingToken;
    playbackService.watermarkingToken = self.watermarkingToken;     
  3. Make your request to the Brightcove catalog for a single video or a playlist.

    For a video request:

    - (void)findVideoWithVideoID:(NSString *)videoID parameters:
      (NSDictionary *)parameters completion:(void (^)
      (BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

    For a playlist request:

    - (void)findPlaylistWithPlaylistID:(NSString *)playlistID parameters:
      (NSDictionary *)parameters completion:(void (^)
      (BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;


For casting you’ll need to provide the watermarking token and the userId fields.

In your code to set up the BrightcoveCastCustomData object, add this line:

BCOVReceiverAppConfig *appConfig = [BCOVReceiverAppConfig new];
appConfig.userId = @"";
appConfig.watermarkingToken = watermarkingToken;

In the debugging console you can see the configuration values that will be used for your Chromecast session.

Google Cast Custom Data: {
  accountId = <your_account_id>;
  analyticsParams =     {
      application = "";
      user = "";
  catalogParams =     {
      adConfigId = "";
      bcovAuthToken = "";
      id = <your_video_id>;
      policyKey = "<your_policy_key";
      type = video;
      watermarkingToken = "<your_watermark_token";

Offline Playback

Offline playback should work as usual once the video is downloaded.

To get started with this feature, see the iOS App Developer's Guide to Offline Playback reference.


For details about the limitations for this feature, see the Overview: Forensic Watermarking document.