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.sdkReady Boolean 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:

Parameter Type Default Description
enabled boolean false Global 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
appId string App bundle id, if not specified then equal to id app parameter
placementId string pltd4o7ibb9rc653x14 vi placemenet ID, you can use this one for testing, and switch to yours real one for production
placementType string interstitial Ad type. Can be interstitial (when ad runs as full screen video) or instream (when ad video )
autoplay boolean true Enables video ad autoplay
startMuted boolean Defines 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
fallbackOverlay boolean true Enables overlay layer that will be visible when ad can not autoplay (in case video autoplay requires user interaction)
fallbackOverlayText string Please watch this ad Fallback overlay text
appVer string App version, if not specified then equal to version app parameter
language boolean null App language, if not specified then equal to language app parameter
width number App width in px. If not specified then equal to app container width
height number App height in px. If not specified then equal to app container height
showProgress boolean true Enable ad interface progress bar
showBranding boolean true Enable ad interface vi branding logo
showMute boolean true Enable ad interface mute button
os string Operating system, if not specified then will be equal to app.device.os
osVersion string Operating system version, if not specified then will be equal to app.device.osVersion
orientation string Device orientation, if not specified then will be detected based on window.orientation
age number User age (optional)
gender string User gender (optional)
advertiserId string Unique advertiser identifier (optional)
latitude integer Device location latitude (optional)
longitude integer Device location longitude (optional)
storeId string App store id (optional)
ip string Device IP address (optional)
manufacturer string Device manufacturer (optional)
model string Device model
connectionType string Device connection type (optional)
connectionProvider string Device connection provider (optional)
on object Object 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.app Link to global app instance
viAd.ad Original vi ad instance
viAd.params vi 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:

Event Target Arguments Description
ready viAd Event 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
started viAd Event will be triggered when ad video started to play
click viAd Event will be triggered after click on ad video
click viAd url Event 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
impression viAd Event will be triggered on ad impression
stopped viAd reason Event 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
complete viAd Event will be triggered when video ad finished
userexit viAd Event will be triggered when user closed the video ad
autoplayFailed viAd reason Event will be triggered in case of enabled autoplay and it failed to start an ad (for example when additional user interraction required)
error viAd error Event will be triggered on ad error. As an argument it receives error message

App Events

vi component also fires events on app instance:

Event Target Arguments Description
viSdkReady app Event 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() {
        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() {
        const ad = this;
        app.dialog.alert('Check out this awesome ad to get the reward', () => {
          ad.start();
        })
      },
      complete() {
        app.dialog.alert('Congrats! You got the reward!')
      },
      userexit() {
        app.dialog.alert('Sorry, no reward for you!')
      },
    }
  });
});