Skip to main content

Migrating to Web SDK v4.0.0

Web SDK v4.0.0 introduced some breaking changes for DeepAR SDK. This document aims to ease the transition from previous versions of Web SDK.

Don't be intimidated! Changes are not big.

👉 Migrating to new version takes about 5-10 minutes.

All the changes are made to help developers with an easier and more standard/modern integration.


Yeah, you heard that right - DeepAR Web SDK is now available on NPM.

npm install deepar

However, you can still download the standard SDK package from our developer portal.


Web SDK is now written in Typescript. This means that javascript files are accompanied by appropriate Typescript declaration .d.ts files.

Declaration files contain all the classes, methods and types so you can always be 100% sure what methods receive what parameters and of what type. This will also help your IDE with auto-complete, suggestions and inline documentation.

For you plain Javascript developers, don't worry - this benefits you also. You don't have to write in Typescript for your IDE to pick up help from .d.ts files.

Javascript files

New SDK comes with two DeepAR javascript files:

  • deepar.js
  • deepar.esm.js

Which one should you use?

They both encapsulate DeepAR SDK entirely, so you should just use one or the other.


This file is meant to be used when you include the SDK with a <script> tag inside your HTML.

<script type="text/javascript" src="deepar.js"></script>

This will emit DeepAR class into the global javascript namespace. You can use it in a straightforward way.

let deepAR = new DeepAR({ ... });

This file uses UMD export and only exports DeepAR class.


This file is meant to be used when you include the SDK with bundlers like Webpack and Rollup.

import { DeepAR } from 'deepar.esm'

The extension esm.js stands for ES module - meaning this file puts the SDK as an ES module. This file is used when you install the SDK with NPM. You can also use it like this:

<script type="module">
import { DeepAR } from './lib/js/deepar.esm.js';
let deepAR = new DeepAR({ ... });

DeepAR is now a class

In previous SDKs you called DeepAR without the new keyword because it was not a class.

let deepAR = DeepAR({ ... });

Now DeepAR is an actual class, and you must call it with a new keyword.

let deepAR = new DeepAR({ ... });

Constructor parameters

In previous versions of SDK the parameters looked like this:

let deepAR = DeepAR({
licenseKey: 'your_license_key_here',
canvas: document.getElementById('deepar-canvas'),
canvasWidth: 1280,
canvasHeight: 720,
numberOfFaces: 1,
segmentationInfoZip: 'path/to/',
onInitialize: function() {
// DeepAR is initialized.
// Other callbacks here

In the new version the initialization looks like this:

var deepAR = new DeepAR({
licenseKey: 'your_license_key_here',
canvas: document.getElementById('deepar-canvas'),
segmentationConfig: {
modelPath: "path/to/segmentation-160x160-opt.bin"
deeparWasmPath: 'path/to/deepar.wasm',
callbacks: {
onInitialize: function() {
// DeepAR is initialized.
// Other callbacks here

Let's go through all the changes:

  • licenseKey - No Changes.
  • canvas - No changes.
  • canvasWidth and canvasHeight - Passing these parameters has no effect anymore. In previous versions of SDK, these parameters would resize the canvas. You could change the canvas size with setCanvasSize() method. In new SDK, DeepAR will adapt to the canvas size. So you just need to set the size of the canvas. If canvas is resized, DeepAR will pick it up automatically.
  • numberOfFaces - This parameter has no effect anymore. DeepAR will track minimum number of faces according to the current configuration of loaded effects.
  • segmentationInfoZip - Path to the segmentation (background removal) model. This parameter is now changed to segmentationConfig.modelPath.
  • deeparWasmPath - Path to the deepar.wasm file.


You can provide callbacks in the constructor of the DeepAR class in the callbacks parameter.

let deepAR = new DeepAR({
callbacks: {
onInitialize: function() {
// This is wher you start camera preview and start loading effects
onScreenshotTaken: function(imageUrl) {
// Show and/or save the screenshot
onFaceTracked: function(faceData) {
// Inspect the face tracking features
// other parameters ...

Add or change callbacks via DeepAR.callbacks property.

deepAR.callbacks.onScreenshotTaken = (url) => {
// download or show the image from url

To remove certain callback:

deepAR.callbacks.onScreenshotTaken = undefined;