Geo-Filtering Messaging

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Task(s)
Protect Videos
Topic(s)
Geo Restriction
Troubleshooting/Error Handling

In this topic, you will learn how to display appropriate error messages when a video is not allowed to play because of geo-restrictions. By default, Brightcove Player does not inform the user that a video is geo-filtered.

Overview

It is possible to restrict where a video can be viewed via geo-filtering. The Geo-filtering your Videos document shows you how to use Video Cloud to apply geographic restrictions. The document you are now reading instructs you how to implement code to inform users that a video is geo-filtered.

By default, Brightcove Player does not inform the user that a video is geo-filtered. It simply does not play. If you view the console you will see the following.

GET https://edge.api.brightcove.com/v1/accounts/1486906377/videos/3930525483001 403 (Forbidden)

This is not terribly helpful as you cannot be guaranteed from this error that the reason the video is forbidden to view is geo-filtering.

This document implements a strategy to let the user know the video they are trying to watch is geo-filtered.

Player catalog's error object

The key to creating a user friendly message is the error object contained in Brightcove Player's catalog. An example of a geo-filtering error is shown below in a screenshot from a browser's console. Notice that the object contains a data property, which itself contains an array. The array will hold the last error the catalog encountered loading a video. In the example you see the element in the array is reporting a geo-filtering access issue.

catalog error object

Handle bc-catalog-error

It is possible that handling errors in the normal ready() section in the script block can cause issues. For instance, it can happen that the bc-catalog-error event could be dispatched before the player is ready, and if you listen for the error in the ready() section, you will not be able to handle the error. You may find that there is not a problem in your code, but the issue can browser dependent, so use caution. For this reason, the error handling code in this document will use the one() event handling method to listen for the bc-catalog-error in a separate code block rather than inside the ready() section.

Message in HTML

Once you understand the structure of the error that is produced, and where it is located, you can use JavaScript to display a descriptive error for the user. The basic implementation steps are:

  • Create a target element in which to display the message.
  • Be sure the player is ready to act upon.
  • Check to see if any error has occurred.
  • If yes, check to see if the error is a geo-filtering issue.
  • If yes, display message to user.

The following code implements these steps.

  • Line 12: Insert an HTML element, in this case a paragraph, in which to inject text; give the element an id for targeting purposes.
  • Line 17: Use the one() method add an event listener for the bc-catalog-error event only once.
  • Line 20: Use an if statement to be sure some error has occurred.
  • Line 21: Assign a variable the specific error information from Brightcove Player catalog's error object.
  • Line 22: Use an if statement to be sure the specific error information exists AND the type of error is from geo-filtering.
  • Line 23: Inject an appropriate text message into the HTML element created at line 12.
  <video-js id="myPlayerID"
    data-account="1486906377"
    data-player="77a8e8b7-e8d1-4a3c-8a1b-292ba8233006"
    data-embed="default"
    data-video-id="4040394419001"
    class="video-js" controls></video-js>

  <p id="textTarget"></p>

  <script src="https://players.brightcove.net/1486906377/77a8e8b7-e8d1-4a3c-8a1b-292ba8233006_default/index.min.js"></script>

  <script type="text/javascript">
    videojs.getPlayer('myPlayerID').one('bc-catalog-error', function(){
      var myPlayer = this,
        specificError;
      if (myPlayer.catalog.error !== undefined) {
        specificError = myPlayer.catalog.error.data[0];
        if (specificError !== undefined & specificError.error_subcode == "CLIENT_GEO") {
          document.getElementById("textTarget").innerHTML = "The video you are trying to watch cannot be viewed from your current country or location.";
        };
      };
    });

    videojs.getPlayer('myPlayerID').ready(function() {
      var myPlayer = this;
      console.log('in ready');
    });
  </script>

The following screenshot shows the message displayed below the player. (Note the image in the player is the poster, which is not geo-restricted.)

geo filtering message

Message via errors plugin

You may wish to have the message displayed in the player and/or not have even the poster appear if the video is geo-filtered. You can do this utilizing the errors plugin. The errors plugin is automatically loaded into the player, so you do not need to explicitly perform that operation. For details on the errors plugin beyond what will be mentioned here, see the Display Error Messages Plugin document.

  • Line 48: Use the one() method add an event listener for the bc-catalog-error event only once.
  • Lines 51-58: Call the player's error() method, passing in as an argument JSON that defines the errors information to display. Note that the choice of -3 for the error code is arbitrary, and the only guidance is not to use a standard error code (currently 1-5).
  • Line 62: Call the error() method to display the custom error information. The logic used to determine when the geo-filtering error has occurred is the same as above. The object passed as an argument defines which error message to display.
  <script type="text/javascript">
    videojs.getPlayer('myPlayerID').one('bc-catalog-error', function(){
      var myPlayer = this,
        specificError;
      myPlayer.errors({
        'errors': {
          '-3': {
            'headline': 'The video you are trying to watch cannot be viewed from your current country or location.',
            'type': 'CLIENT_GEO'
          }
        }
      });
      if (typeof(myPlayer.catalog.error) !== 'undefined') {
        specificError = myPlayer.catalog.error.data[0];
        if (specificError !== 'undefined' & specificError.error_subcode == "CLIENT_GEO") {
          myPlayer.error({code:'-3'});
        };
      };
    });

    videojs.getPlayer('myPlayerID').ready(function() {
      var myPlayer = this;
    });
  </script>

The following screenshot shows the error plugin's display of the defined error.

custom error message

General error display

The two sections above deal specifically with displaying the error generated when a geo-restricted video is viewed from a restricted locale. Some errors do not provide the level of detail the geo-filtering restriction does. An example error object of this type is shown here. Notice that the data field is empty, whereas with the geo-filtering error it contained key error information.

general error message

The following code shows how to display information from catalog.error no matter the level of detail. At a high-level, the code performs the following:

  • Checks if a catalog error has occurred.
  • Checks if in the error object the data field contains specific error information. If it does NOT, the general error message is injected into the HTML.
  • If there is specific error information AND it is geo-filtering related an appropriate message is injected into the HTML.
  • If there is specific error information, and it is not geo-filtering related, the specific error's message is injected into the HTML.
  <script type="text/javascript">
    videojs.getPlayer('myPlayerID').one('bc-catalog-error', function(){
      var myPlayer = this,
        specificError;
      if (myPlayer.catalog.error != undefined) {
        specificError = myPlayer.catalog.error.data[0];
        if (specificError == undefined) {
          document.getElementById("textTarget").innerHTML = "The following error has occurred: <strong>" + myPlayer.catalog.error.message + "</strong>";
        } else if (specificError.error_subcode == "CLIENT_GEO") {
          document.getElementById("textTarget").innerHTML = "The video you are trying to watch cannot be viewed from your current country or location.";
        } else {
          document.getElementById("textTarget").innerHTML = "The following error has occurred: " + specificError.message;
        };
      };
    });

    videojs.getPlayer('myPlayerID').ready(function() {
      var myPlayer = this;
    });
  </script>

The following screenshot shows the general error message being displayed in HTML. Of course you could also use the errors plugin to display the message, as shown previous section of this document.

geo filtering general message