Video Intelligence (vi)

Video Intelligence component that built into Framework7 allows you to easily add video advertising to your Framework7 app, straight out-of-the-box.

vi's interstitial ads can be placed into your app experience at your discretion, showing full screen video ads. Advertisers pay a premium for these ad slots, and they will be directly connected to your app; you'll be able to monetise straight away.

Getting Started With vi

1. Sign up for Framework7 vi publisher account

First of all as a mobile publisher you need to create vi publisher account. To signup for Framework7 vi account go to vi.framework7.io and fill up the following form:

2. Setup your app at vi

After successful registration you will receive instructions with vi dashboard link and temporary password to the specified email.

When you log in to your vi dashboard you will see a list of your apps. If you don’t have apps create new one:

When you already have an app, you need to add placement for this app:

When you create place choose Placement Type: "Video Interstitial"

Ok, after we have placement created we need placement ID, choose just created placement:

Click “copy” near the placement id string to copy id to the clipboard

3. Configure vi in Framework7 app

After we set the things up at vi dashboard we will have:

  • App bundle id (e.g. io.framework7.testapp)
  • Placement id (e.g. pltd4o7ibb9rc653x14)

Now when we have our vi placement id we may set it up in Framework7 on the app initialization:

var app = new Framework7({
  /*
    common app bundle id must match the one
    you have specified when created app in vi dashboard:
  */
  id: 'io.framework7.testapp',

  /* add vi placement id under the vi module parameters */
  vi: {
    placementId: 'pltd4o7ibb9rc653x14',
  },
});

4. Show Ad

That is all, now we can use Framework7’s vi API to create and show ads. In simplest way just call the following method when you need to show an ad:

app.vi.createAd();

vi App Methods

Let's look at available vi app methods and properties:

app.vi.createAd(parameters)Create (and show) vi video ad.
  • parameters - object with vi ad parameters
  • Method returns vi ad instance
app.vi.loadSdk()Loads vi SDK. By default if vi is not disabled in app parameters then it will load it automatically
app.vi.sdkReadyBoolean property indicating whether the vi SDK is ready or not

vi Ad Parameters

Let's look at list of all available parameters when we create vi ad:

ParameterTypeDefaultDescription
enabledbooleanfalseGlobal app parameter which enables vi API and vi SDK to load. If you pass any vi parameters under vi app parameters then it will enable vi api as well
appIdstringApp bundle id, if not specified then equal to id app parameter
placementIdstringpltd4o7ibb9rc653x14vi placemenet ID, you can use this one for testing, and switch to yours real one for production
placementTypestringinterstitialAd type. Can be interstitial (when ad runs as full screen video) or instream (when ad video )
autoplaybooleantrueEnables video ad autoplay
startMutedbooleanDefines whether the ad must start muted or not. By default is true when app is running as a web app (not Cordova) under mobile device (iOS or Android). It is required because on mobile device video autoplay usually requires additional user interaction
fallbackOverlaybooleantrueEnables overlay layer that will be visible when ad can not autoplay (in case video autoplay requires user interaction)
fallbackOverlayTextstringPlease watch this adFallback overlay text
appVerstringApp version, if not specified then equal to version app parameter
languagebooleannullApp language, if not specified then equal to language app parameter
widthnumberApp width in px. If not specified then equal to app container width
heightnumberApp height in px. If not specified then equal to app container height
showProgressbooleantrueEnable ad interface progress bar
showBrandingbooleantrueEnable ad interface vi branding logo
showMutebooleantrueEnable ad interface mute button
osstringOperating system, if not specified then will be equal to app.device.os
osVersionstringOperating system version, if not specified then will be equal to app.device.osVersion
orientationstringDevice orientation, if not specified then will be detected based on window.orientation
agenumberUser age (optional)
genderstringUser gender (optional)
advertiserIdstringUnique advertiser identifier (optional)
latitudeintegerDevice location latitude (optional)
longitudeintegerDevice location longitude (optional)
storeIdstringApp store id (optional)
ipstringDevice IP address (optional)
manufacturerstringDevice manufacturer (optional)
modelstringDevice model
connectionTypestringDevice connection type (optional)
connectionProviderstringDevice connection provider (optional)
onobjectObject with events handlers. For example:
var viAd = app.vi.createAd({
  on: {
    stopped: function () {
      console.log('Ad video stopped')
    }
  }
})

All parameters can be used in global app parameters under vi property to set defaults for all vi ads. For example:

var app = new Framework7({
  /*
    common app bundle id must match the one
    you have specified when created app in vi dashboard:
  */
  id: 'io.framework7.testapp',

  /* global vi parameters */
  vi: {
    placementId: 'pltd4o7ibb9rc653x14',
  }
});

In this case when we create vi ad, we need to pass parameters that we want to override:

var viAd = app.vi.createAd({
  // disable autoplay for this ad
  autoplay: false,
})

vi Ad Methods & Properties

So to create vi ad we have to call:

var viAd = app.vi.create({ /* parameters */ })

After that we have its initialized instance (like viAd variable in example above) with useful methods and properties:

Properties
viAd.appLink to global app instance
viAd.adOriginal vi ad instance
viAd.paramsvi ad parameters
Methods
viAd.start()Start ad video. Useful in case of disabled autoplay
viAd.pause()Pause ad video
viAd.resume()Resume ad video
viAd.stop()Stop ad video, in this case ad will be closed and destroyed. It will be impossible to proceed with this video ad
viAd.on(event, handler)Add event handler
viAd.once(event, handler)Add event handler that will be removed after it was fired
viAd.off(event, handler)Remove event handler
viAd.off(event)Remove all handlers for specified event
viAd.emit(event, ...args)Fire event on instance

vi Ad Events

vi ad will fire the following events on vi ad instance:

EventTargetArgumentsDescription
readyviAdEvent will be triggered when ad created, requested and ready to be played. In case of disabled autplay, you to listen for this event and call viAd.start() when ad becomes ready
startedviAdEvent will be triggered when ad video started to play
clickviAdEvent will be triggered after click on ad video
clickviAdurlEvent will be triggered after click on ad video. As an argument it received click target URL. Use this url only in case if ad target url can not be opened by your device/app
impressionviAdEvent will be triggered on ad impression
stoppedviAdreasonEvent will be triggered when video ad stopped. As an argument it receives string reason, which can be, for example, userexit (when video was interrupted by user) or complete when ad video completed
completeviAdEvent will be triggered when video ad finished
userexitviAdEvent will be triggered when user closed the video ad
autoplayFailedviAdreasonEvent will be triggered in case of enabled autoplay and it failed to start an ad (for example when additional user interraction required)
errorviAderrorEvent will be triggered on ad error. As an argument it receives error message

App Events

vi component also fires events on app instance:

EventTargetArgumentsDescription
viSdkReadyappEvent will be triggered when vi SDK loaded and ready to be used

Examples

var app = new Framework7({
  id: 'io.framework7.testapp',
  vi: {
    placementId: 'pltd4o7ibb9rc653x14',
  }
});

var $$ = Dom7;

// Create prepaire ad
var prepairedAd;
if (!app.vi.sdkReady) {
  app.on('viSdkReady', function () {
    prepairedAd = app.vi.createAd({
      autoplay: false,
    });
  })
} else {
  prepairedAd = app.vi.createAd({
    autoplay: false,
  });
}

// Show prepaired ad
$$('.show-prepaired').on('click', function () {
  prepairedAd.start();
});

// Create and show ad
$$('.create-and-show').on('click', function () {
  app.vi.createAd();
});

// With custom autplay fallback
$$('.create-and-show-with-custom-callback').on('click', function () {
  app.vi.createAd({
    fallbackOverlay: false,
    on: {
      autoplayFailed: function() {
        const ad = this;
        app.dialog.alert('Check out this awesome ad', () => {
          ad.start();
        })
      }
    }
  });
});

// Create and show rewarded ad
$$('.create-and-show-rewarded').on('click', function () {
  app.vi.createAd({
    autoplay: false,
    on: {
      ready: function() {
        const ad = this;
        app.dialog.alert('Check out this awesome ad to get the reward', () => {
          ad.start();
        })
      },
      complete: function() {
        app.dialog.alert('Congrats! You got the reward!')
      },
      userexit: function() {
        app.dialog.alert('Sorry, no reward for you!')
      },
    }
  });
});