Migration guide#

Plugin-related configurations (modules) now require the word Plugin at the end of their respective property names (e.g., adblocker is now adblockPlugin, podcast is now podcastPlugin). This change ensures consistency across the API and better reflects their modular structure.

Design studio#

The design studio configuration has been enhanced for better organization and functionality. The logo options are now part of the designStudio group, allowing for more customization, including an optional link. Additionally, color options have been consolidated into a colors object for clarity and easier management. These changes improve maintainability and streamline customization.

Before update

  window.initPlayer('my-video', {
    logo: {
      file: string,
      hide: boolean,
      position: 'top-right',
      margin: string,
    },
    designStudio: {
      primary: string,
      highlight: string,
      background: string,
      thumbContainerBG: string,
      playProgressColor: string,
      loadProgressColor: string,
      progressHolderColor: string,
    }
  })

After update

  window.initPlayer('my-video', {
    designStudio: {
      logo: {
        src: string,
        hide: boolean,
        link: string,
        position: 'top-right',
        margin: 2,
      },
      colors: {
        primary: string,
        highlight: string,
        background: string,
        thumbContainerBg: string,
        playProgress: string,
        loadProgress: string,
        progressHolder: string,
      }
    }
  })

Podcast#

The podcast plugin has been streamlined by consolidating and reorganizing options. Some redundant or unnecessary options have been removed, and the skip controls now support dynamic text via a function that returns the current skip button value.

Before update

  window.initPlayer('my-video', {
    podcast: {
      title: string,
      titleWrapperClass: string,

      subtitle: string,
      subtitleWrapperClass: string,

      image: string,
      imageWrapperClass: string,

      // powered by
      poweredByLink: string,
      poweredByLogo: string,
      poweredByTitle: string,
      poweredByWrapperClass: string,

      // design studio
      background: string,
      progressHolderColor: string,
      playProgressColor: string,

      // podcast design studio
      themeColor: string,
      themeColor: string,
      direction: string,
      controlsColor: string,
      textColor: string,
      tooltipBgColor: string,
      tooltipTextColor: string,

      // download control
      enableDownload: boolean,
      downloadButtonText: string,
      audioDownloadName: string,
      downloadButtonWrapperClass: string,

      // share control
      enableShare: boolean,
      shareButtonText: string,
      shareButtonWrapperClass: string,

      // speed control
      enableSpeed: boolean,
      speedButtonText: string,
      defaultPlaybackRate: number
      playbackRates: number[],
      speedButtonWrapperClass: string,

      // volume control
      volumeControl: boolean,
      volumeControlWrapperClass: string,
      volumeControlDirection: string,

      // skip controls
      plusSkipControl: boolean,
      plusSkip: number,
      plusSkipText: string,
      plusSkipControlWrapperClass: string,
      minusSkipControl: boolean,
      minusSkip: number,
      minusSkipText: string,
      minusSkipControlWrapperClass: string,

      // progress bar
      wave: 'rounded',
      waveBasedOnAudioBuffer: boolean,

      // time displays
      currentTimeDisplay: boolean,
      currentTimeDisplayWrapperClass: string,
      durationDisplay: boolean,
      durationDisplayWrapperClass: string,
      remainingTimeDisplay: boolean,
      remainingTimeDisplayWrapperClass: string,
    }
  })

After update

  window.initPlayer('my-video', {
    podcastPlugin: {
      title: string,
      titleWrapperClass: string,

      subtitle: string,
      subtitleWrapperClass: string,

      image: string,
      imageWrapperClass: string,

      poweredBy: {
        link: string,
        logo: string,
        title: string,
        wrapperClass: string,
      },

      podcastDesignStudio: {
        themeColor: string,
        background: string,
        progressHolderColor: string,
        playProgressColor: string,
        controlsColor: string,
        textColor: string,
        tooltipBgColor: string,
        tooltipTextColor: string,
      },

      download: {
        enable: boolean,
        text: string,
        downloadName: string,
        wrapperClass: string,
      },

      share: {
        enable: boolean,
        text: string,
        wrapperClass: string,
      },

      speed: {
        enable: boolean,
        text: string,
        wrapperClass: string,
        defaultPlaybackRate: number,
      },

      volume: {
        enable: boolean,
        wrapperClass: string,
      },

      skipControls: {
        forward: {
          enable: boolean,
          text: string | ((value: number) => `skip ${value} seconds`),
          wrapperClass: string,
        },

        backward: {
          enable: boolean,
          text: string | ((value: number) => `rewind ${value} seconds`),
          wrapperClass: string,
        },
      },

      progressBar: {
        wave: 'rounded',
        waveBasedOnAudioBuffer: boolean,
      },

      timeDisplays: {
        currentTimeDisplay: boolean,
        currentTimeDisplayWrapperClass: string,
        durationDisplay: boolean,
        durationDisplayWrapperClass: string,
        remainingTimeDisplay: boolean,
        remainingTimeDisplayWrapperClass: string,
      },

      file: string,
    }
  })

The share functionality has been updated to allow greater md:flexibility and customization. You can now control whether to add the share button to the control bar, place it elsewhere, and include a broader range of customization options.

Before update

  window.initPlayer('my-video', {
    sharingSocials: [
      'fbButton',
      'linkedin',
      'mail'
      'messenger',
      'ok',
      'telegram',
      'tw',
      'viber',
      'vk',
      'whatsapp',
    ],
    sharing: string,
  })

After update

  window.initPlayer('my-video', {
    socials: [
      'facebook',
      'linkedin',
      'email',
      'messenger',
      'telegram',
      'twitter',
      'viber',
      'whatsapp',
      'pinterest',
      'reddit',
    ],
    addButtonToControlBar: boolean,
    buttonPositionIndex: number,
    description: string,
    embedCode: string,
    fbAppId: string,
    image: string,
    mobileVerification: boolean,
    redirectUri: string,
    showEmbedCode: boolean,
    title: string,
    url: string,
  })

Adblocker module#

The adblocker module has been improved to allow for an optional errorMessage. This message will be displayed when ad blockers are detected, providing a more user-friendly way to handle such scenarios.

Before update

  window.initPlayer('my-video', {
    adblocker: boolean,
  })

After update

  window.initPlayer('my-video', {
    adblockPlugin: {
      errorMessage: string,
    }
  })

Playlist module#

The playlist module has been updated and renamed to playlistPlugin. While adschedule is not yet supported, the new structure introduces improved options for better md:flexibility . Playlists are now configured under items, with enhanced properties such as poster and tracks. Additional settings like autoplay, autoplayDelay, and playlistElementId provide more control over playlist behavior.

Before update

  window.initPlayer('my-video', {
    playlist: [{
      image: string,
      sources: [{...}],
      title: string,
      mediaid: string,
      adschedule: {...}
    }]
  })

After update

  window.initPlayer('my-video', {
    playlistPlugin: {
      items: [{
        poster: string,
        sources: [{...}],
        title: string, // Item title
        duration: string,
        tracks: [{...}]
      }],
      autoplay: boolean,
      autoplayDelay: number, // delay in seconds
      playlistElementId: string,
      title: string, // Playlist title
    }
  })

Google VR (Panorama) module#

In KWIKplayer v9, the panorama module has been greatly enhanced. Unlike KWIKplayer v8, which required the 'monoscopic' stereomode, the new configuration now allows more control over the camera settings, giving you the ability to adjust various parameters to suit your needs.

The new panoramaPlugin offers additional customization for user interaction (such as mobile support), video zooming, and VR mode toggling. You also have control over the field of view (FOV), initial position, and the ability to fine-tune the panorama behavior with parameters like clickAndDrag, autoMobileOrientation, and more.

The default settings are provided in this example, and if no changes are needed, you can simply pass an empty object.

Before update

  window.initPlayer('my-video', {
    stereomode: 'monoscopic',
  })

After update

  window.initPlayer('my-video', {
    panoramaPlugin: {
      clickAndDrag: isMobile, // boolean
      showNotice: true,
      NoticeMessage: isMobile // boolean
        ? 'Please drag and drop the video'
        : 'Please use your mouse drag and drop the video',
      autoHideNotice: 3000,

      // limit the video size when user scroll.
      scrollable: true,
      initFov: 75,
      maxFov: 105,
      minFov: 51,

      // initial position for the video
      initLat: 0,
      initLon: -180,

      // A float value back to center when mouse out the canvas. The higher, the faster.
      returnStepLat: 0.5,
      returnStepLon: 2,
      backToVerticalCenter: !isMobile, // boolean
      backToHorizonCenter: !isMobile, // boolean
      clickToToggle: false,

      // limit viewable zoom
      minLat: -85,
      maxLat: 85,

      minLon: -Infinity,
      maxLon: Infinity,

      videoType: 'equirectangular',

      rotateX: 0,
      rotateY: 0,
      rotateZ: 0,

      autoMobileOrientation: false,
      mobileVibrationValue: mobile ? 0.022 : 1,

      VREnable: true,
      VRGapDegree: 2.5,

      closePanorama: false,

      helperCanvas: {},

      dualFish: {
        width: 1920,
        height: 1080,
        circle1: {
          x: 0.240625,
          y: 0.553704,
          rx: 0.23333,
          ry: 0.43148,
          coverX: 0.913,
          coverY: 0.9,
        },
        circle2: {
          x: 0.757292,
          y: 0.553704,
          rx: 0.232292,
          ry: 0.4296296,
          coverX: 0.913,
          coverY: 0.9308,
        },
      },
    }
  })

Chromecast#

In KWIKplayer v9, the Chromecast module is no longer enabled by default. To activate it, you must now pass the chromecastPlugin options. This provides greater control over when and how Chromecast is used within the player. You can specify the receiverAppID, choose to add the Chromecast button to the control bar, and control its position by setting buttonPositionIndex. These updates offer more customization and md:flexibility in the user experience.

  window.initPlayer('my-video', {
    chromecastPlugin: {
      receiverAppID: string,
      addButtonToControlBar: boolean,
      buttonPositionIndex: 16,
    }
  })

Airplay#

Similar to the Chromecast module, the Airplay functionality in KWIKplayer v9 now requires explicit activation. You need to use the airplayPlugin options to enable it. This allows you to manage whether the Airplay button is displayed in the control bar (addButtonToControlBar) and determine its position using buttonPositionIndex. This change improves the modularity and customization of the player

  window.initPlayer('my-video', {
    airplayPlugin: {
      addButtonToControlBar: boolean,
      buttonPositionIndex: 16,
    }
  })

Hotspots#

In KWIKplayer v9, the options structure for Hotspots module undergone minor changes. The options such as size, radius, left, top, width, and height have been updated to accept number values instead of string.

Before update

  window.initPlayer('my-video', {
    hotspots: [{...}]
  })

After update

  window.initPlayer('my-video', {
    hotspotsPlugin: [{...}]
  })

Hotspots editor#

In KWIKplayer v9, the options structure for the Hotspots Editor plugin has been updated with the addition of Plugin at the end of its name, becoming hotspotsEditorPlugin.

Before update

  window.initPlayer('my-video', {
    hotspotEditor: {
      valuehandler: string | ((hotspots) => void),
      controls: ['hotspot' | 'image' | 'text'],
    }
  })

After update

  window.initPlayer('my-video', {
    hotspotsEditorPlugin: {
      valuehandler: string | ((hotspots: ModuleHotspotsEditor.Options[]) => void),
      controls: ['hotspot' | 'image' | 'text'],
    }
  })

Custom button#

In KWIKplayer v9, the ccbutton configuration has been streamlined. The redundant css and style options have been removed. The new enabled boolean option is used to control whether the button is visible or hidden. The controlText option has been added to specify the text displayed when hovering over the button.

Before update

  window.initPlayer('my-video', {
    ccbutton: {
      enabled: boolean,
      css: string,
      className: string,
      style: string,
      eventName: string,
      menuItems: [],
    }
  })

After update

  window.initPlayer('my-video', {
    ccbutton: {
      enabled: boolean,
      className: string,
      controlText: string,
      eventName: string,
      menuItems: [],
    },
  })

Google analytics#

In KWIKplayer v9, the Google Analytics configuration has been updated to use the googleAnalyticsPlugin instead of ga. The new structure introduces an assetName option to specify the asset being tracked. The events array now includes more detailed information, allowing you to define the name, label, action, and enabled status for each event.

Before update

  window.initPlayer('my-video', {
    ga: {
      mode: 'GTAG',
      events: ['ended'],
      debug: boolean,
    },
  })

After update

  window.initPlayer('my-video', {
    googleAnalyticsPlugin: {
      mode: 'GTAG',
      assetName: string,
      events: [{
        name: 'ended',
        label: string,
        action: 'ended',
        enabled: boolean,
      }],
      debug: boolean,
    },
  })

Kwik analytics#

In KWIKplayer v9, the kwikAnalyticsPlugin has replaced the stat configuration. The plugin now includes a new category option to specify the category of the analytics data, as well as a siteId option to differentiate between various platforms (such as js, lbci android, or lbci ios). The other options, such as url, events, title, interval, mediaId, and userId, remain the same, providing continuity in tracking analytics data.

Before update

  window.initPlayer('my-video', {
    stat: {
      url: string,
      events: string[],
      title: string,
      interval: 5,
    },
    mediaid: string,
    userid: string,
  })

After update

  window.initPlayer('my-video', {
    kwikAnalyticsPlugin: {
      url: string,
      events: string[],
      title: string,
      interval: 5,
      category: string,
      mediaId: string,
      userId: string,
      siteId: '0' | '1' | '2', // 0 - js, 1 - lbci android, 2 - lbci ios
    }
  })

Npaw analytics#

In KWIKplayer v9, the npaw configuration is now npawAnalyticsPlugin. The plugin now uses more concise naming for custom dimensions and other content properties. The mediaid and userid options have been removed, and custom dimensions are now handled with content.customDimension.1 and content.customDimension.2. The rest of the options for tracking content-related data remain largely the same.

Before update

  window.initPlayer('my-video', {
    npaw: {
      debug: boolean,
      options: {
        'content.channel': string,
        'content.customDimensions': {
          monetization: string
        },
        'content.episodeTitle': string,
        'content.genre': string,
        'content.id': string,
        'content.season': string,
        'content.title': string,
        'content.tvShow': string,
        'content.type': string,
        'content.contractedResolution': string,
        'content.cost': string,
        'content.price': string,
        'user.name': 0,
      },
      mediaid: 'development',
      userid: 0,
    },
  })

After update

  window.initPlayer('my-video', {
    npawAnalyticsPlugin: {
      debug: boolean,
      'content.channel': string,
      'content.contractedResolution': string,
      'content.cost': string,
      'content.customDimension.1': string,
      'content.customDimension.2': string,
      'content.episodeTitle': string,
      'content.genre': string,
      'content.id': string,
      'content.price': string,
      'content.season': string,
      'content.title': string,
      'content.tvShow': string,
      'content.type': string,
      'user.name': '0',
    }
  })

IMA#

In KWIKplayer v9, the advertising module is now imaPlugin. The admessage has been replaced by adLabel and adLabelNofN. The schedule structure has been updated to adsSchedule with more specific controls for preroll, midroll, and postroll. Additionally, new options such as autoPlayAdBreaks, disableAdControls, and featureFlags have been introduced for more granular control over ads.

Before update

  window.initPlayer('my-video', {
    advertising: {
      debug: boolean,
      contribAdsSettings: {...},
      omniMode: {...},
      omidVendorAccess: {...}
      admessage: string,
      vpaidMode: 'ENABLED',
      schedule: {
        [string]: {
          offset: string,
          tag: string,
        }
      }
    }
  })

After update

  window.initPlayer('my-video', {
    imaPlugin: {
      debug: boolean,
      contribAdsSettings: {...},
      omidVendorAccess: {...},
      vpaidMode: 'ENABLED',
      adLabel: string,
      adLabelNofN: string,
      adTagUrl: string,
      adsRenderingSettings: {...},
      adsResponse: string,
      adsSchedule: {
        preroll: string[],
        [midroll: number]: string[],
        postroll: string[],
      },
      adsRequest: {...}
      autoPlayAdBreaks: boolean,
      disableAdControls: boolean,
      disableCustomPlaybackForIOS10Plus: boolean,
      disableFlashAds: boolean,
      featureFlags: {...}
      forceNonLinearFullSlot: boolean,
      locale: string,
      nonLinearHeight: 0,
      nonLinearWidth: 0,
      numRedirects: 0,
      ppid: string,
      preventLateAdStart: boolean,
      sessionId: string,
      showControlsForJSAds: boolean,
      showCountdown: boolean,
      vastLoadTimeout: 0,
    }
  })

IMA DAI#

In KWIKplayer v9, the imadai module is now imaDaiPlugin. The options have been expanded with more detailed settings like assetKey, streamFormat, adTagParameters, and authToken. The live option is replaced by isLiveStream, and the backupStream becomes fallbackStreamUrl. New options for stream monitoring and localization have also been added.

Before update

  window.initPlayer('my-video', {
    imadai: {
      live: boolean,
      mode: string,
      backupStream: string,
      apiKey: string,
      cmsId: string,
      videoId: string,
      urlJump: boolean,
    },
    videoId: string,
  })

After update

  window.initPlayer('my-video', {
    imaDaiPlugin: {
      isLiveStream: boolean,
      fallbackStreamUrl: string,
      apiKey: string,
      cmsId: string,
      videoId: string,
      assetKey: string,
      streamFormat: string,
      adTagParameters: {
        someParameter: string,
      },
      authToken: string,
      bookmarkTime: string,
      locale: string,
      streamActivityMonitorId: string,
    }
  })

Soap#

Before update

  window.initPlayer('my-video', {
    series: string,
  })

After update

  window.initPlayer('my-video', {
    soapButton: {
      xml: string,
    }
  })

Resume#

In KWIKplayer v9, the resume option for *Resume component has been replaced by the resumeModal setting. This simplifies the configuration by directly enabling or disabling the resume modal functionality.

Before update

  window.initPlayer('my-video', {
    mediaid: string,
    resume: boolean,
  })

After update

  window.initPlayer('my-video', {
    resumeModal: boolean
  })

Event changes#

In KWIKplayer v9, several events have been renamed (e.g., playlistsorted is now playlist:changed), and new event types such as share:opened have been added. If you rely on specific event listeners, reviewing these changes is strongly recommended.

Tip: Use this.player.on('*', (event) => console.log(event)) to monitor all triggered custom events.

Migration guide#

Design studio#

Podcast#

Share component#

Adblocker module#

Playlist module#

Google VR (Panorama) module#

Chromecast#

Airplay#

Hotspots#

Hotspots editor#

Custom button#

Google analytics#

Kwik analytics#

Npaw analytics#

IMA#

IMA DAI#

Soap#

Resume#

Event changes#