FeedAd Web SDK Helper Functions

Helper functions cannot be used with the automatic drop-in integration.

Replacement Helper

Overview

The Replacement Helper takes care of detaching and re-attaching the ad player while the user scrolls through your content. All you have to do is to provide some container elements where the helper should move the player ad to.

DEPRECATED in 1.1.6

The replacement helper is deprecated as of FeedAd version 1.1.6 and will be removed in version 1.2.0.

  • If you are already using the helper, you can continue to do so until its removal. Its internal code was updated to use the new rendering system. However, we encurage you to update your code to use multiple ad containers instead.
  • If you are not using the helper and want to display an ad in multiple positions on your page, you should implement multiple ad containers.

Its functionality can be broken down as follows:

  1. Request the helper using a placement ID.
  2. If there is an ad, the helper is returned inside a callback.
  3. Register container elements on the helper that mark the positions where you want to display the ad inside your content.
  4. The helper will observe the positions of the container elements and add the ad player to the container which became visible most recently.

Check out the Replacement Helper example of the Web SDK example project to see it working in action.

Integration Guide

1. Request an Ad

Start an ad request. The request will return a Promise that will resolve with the helper instance.

feedad.helper.replacement.forPlacementId("your-placement-id")
      .then(function (helper) {

      });

2. Register your Ad Containers

You should now add container elements to your page where you want the FeedAd to be shown. Since this depends mostly on your layout and style the Web SDK cannot help you with this.

HTML5 videos can only be played on one element at once. You should take care that only one container can be seen by the user at all times when positioning your container elements. Otherwise there will be blank areas inside your website. You can take a look inside the Web SDK example project to see how this can be done on simple lists with items of the same height.

feedad.helper.replacement.forPlacementId("your-placement-id")
      .then(function (helper) {
          var adContainers = []; // fill with your ad containers
          adContainers.forEach(function (element) {
              helper.registerElement(element);
          });
      });

The helper will now observe the registered elements. Once a container becomes visible to the user it will receive the ad player.

3. Remove your Ad Containers (if required)

If you have a dynamic website where the content changes you might want to remove an ad from a position where it was previously shown.

// you can remove a previously registered container at any time: 
helper.unregisterElement(container);

If you remove the container in which the ad is currently being played, the helper will move the ad player to the container that was last visible before.

4. Listen for ad completion and errors

After all ads finish playing or if an error occurs, FeedAd will not request another ad automatically. To prevent empty views being displayed to the user, you should listen for those events.

feedad.helper.replacement.forPlacementId("your-placement-id")
      .then(function (helper) {
          // [...]

          var cleanup = function () {
              adContainers.forEach(function (element) {
                  helper.unregisterElement(element);
              })
          };

          helper.promise
                .then(function () {
                    // all ads are complete. You should unregister all your containers and remove them from your content.
                    cleanup();
                })
                .catch(function (e) {
                    // there was an error during ad playback. You should unregister all your containers and remove them from your content.
                    cleanup(); 
                });
      })
      .catch(function (e) {
          // there was no ad available or the request failed
      });

To learn more about the error responses, check out the FeedAd guide.

Full Code Example

feedad.helper.replacement.forPlacementId("your-placement-id")
      .then(function (helper) {
          var adContainers = []; // fill with your ad containers
          adContainers.forEach(function (element) {
              helper.registerElement(element);
          });

          var cleanup = function () {
              adContainers.forEach(function (element) {
                  helper.unregisterElement(element);
              })
          };

          helper.promise
                .then(function () {
                    // all ads are complete. You should unregister all your containers and remove them from your content.
                    cleanup();
                })
                .catch(function (e) {
                    // there was an error during ad playback. You should unregister all your containers and remove them from your content.
                    cleanup(); 
                });
      })
      .catch(function (e) {
          // there was no ad available or the request failed
      });