---
url: https://plugin.stripo.email/getting-started/v2-migration-guide.md
---
# Stripo Editor v2 Migration Guide

This guide is primarily for users with prior experience using Stripo Editor v1, and it aims to clarify the changes and improvements introduced in v2. The guide will help you seamlessly transition from v1 to v2 by explaining the key differences in syntax, initialization, and functionality.

## Editor Space

**v1 Syntax**

In Stripo Editor v1, two containers were required for the settings panel and the preview area:

```html
<div id="stripoSettingsContainer"></div>
<div id="stripoPreviewContainer"></div>
```

**v2 Syntax**

In Stripo Editor v2, this has been simplified to a single container for the entire editor:

```html
<div id="stripoEditorContainer"></div>
```

This change reduces the complexity of the HTML structure and streamlines the initialization process.

## Editor Script

**v1 Syntax**

For the latest version:

```
https://plugins.stripo.email/static/latest/stripo.js
```

For a specific version:

```
https://plugins.stripo.email/static/rev/[version]/stripo.js
```

**v2 Syntax**

For the latest version:

```
https://plugins.stripo.email/resources/uieditor/latest/UIEditor.js
```

For a specific version:

```
https://plugins.stripo.email/resources/uieditor/rev/[version]/UIEditor.js
```

## Editor Initialization

**v1 Syntax**

Initialization required specifying the IDs of the settings and preview containers, along with calling the `window.Stripo.init` function:

```js
const stripoConfig = {
    settingsId: '[put here ID of your settings container]',
    previewId: '[put here ID of your preview container]',
    [put here your plugin JSON configuration]
}

window.Stripo.init(stripoConfig);
```

**v2 Syntax**

Initialization now involves directly passing the DOM element of the editor container to the `window.UIEditor.initEditor` function:

```js
const domContainer = document.querySelector('#stripoEditorContainer');
const stripoConfig = {...};

window.UIEditor.initEditor(domContainer, stripoConfig);
```

This change simplifies the initialization process and provides more flexibility by allowing the direct use of DOM elements.

## Initialization Parameters

**v1 Syntax**

The v1 initialization required multiple specific parameters:

* `settingsId`
* `previewId`
* `html`
* `css`
* `apiRequestData -> emailId`
* `getAuthToken`

```js
const stripoConfig = {
    settingsId: '[put here ID of your settings container]',
    previewId: '[put here ID of your preview container]',
    html: '[put here HTML code of your email]',
    css: '[put here CSS code of your email]',
    apiRequestData: {
        emailId: '[put here ID of email in your external application]'
    },
    getAuthToken: function(callback) {
        const token = // get token from backend
        callback(token);
    }
}
```

**v2 Syntax**

In v2, the initialization is more streamlined with fewer required parameters and additional optional ones for enhanced functionality:

* `html` (only for new emails opened for the first time)
* `css` (only for new emails opened for the first time)
* `metadata -> emailId`
* `onTokenRefreshRequest`

Optional, but recommended for co-editing mode:

* `username`
* `avatarUrl`
* `onUserListChange`

```js
const stripoConfig = {
    metadata: {
        emailId: '[put here ID of email in your external application]',
        username: '[put here full user name]',
        avatarUrl: '[put here URL of user avatar image]',
    },
    html: '...',
    css: '...',
    ​​onTokenRefreshRequest: function(callback) {
        const token = // get token from backend
        callback(token);
    },
    onUserListChange: function(usersList) {
        // Update user avatars in custom header logic
    }
}
```

These changes provide greater flexibility and support new features like real-time co-editing.

## Editor Termination

**v1 Syntax**

To stop all processes when the editor is closed:

```js
window.StripoApi.stop();
```

**v2 Syntax**

This has been updated in v2 to:

```js
window.UIEditor.removeEditor();
```

The new method ensures that all editor resources are properly released, improving overall application performance.

## Authentication

**v1 Syntax**

The POST request body for authentication in v1:

```json
{
    "pluginId": "YOUR_PLUGIN_ID",
    "secretKey": "YOUR_SECRET_KEY",
    "role" : "PLUGIN_EDITOR_USER_ROLE"
}
```

**v2 Syntax**

In v2, an additional `userId` parameter is required to enhance security and user-specific interactions:

```json
{
    "pluginId": "YOUR_PLUGIN_ID",
    "secretKey": "YOUR_SECRET_KEY",
    "role" : "PLUGIN_EDITOR_USER_ROLE",
    "userId": "ID_OF_CURRENT_USER"
}
```

This update provides better tracking and management of individual users within the editor.

## External Header Panel

**v1 Syntax**

Initialization parameters used to configure external header panels:

* `codeEditorButtonId`
* `undoButtonId`
* `redoButtonId`

**v2 Syntax**

IDs were replaced with CSS selectors for more flexibility, and additional button selectors were introduced:

* `codeEditorButtonSelector`
* `undoButtonSelector`
* `redoButtonSelector`
* `mobileViewButtonSelector`
* `desktopViewButtonSelector`
* `versionHistoryButtonSelector`

The `onUserListChange` callback was also added to update user avatars during co-editing sessions.

## Initialization Parameters

* Some initialization parameters changed their names or were replaced with new ones with extended meaning.
* All parameters that are responsible for external application notification about something and require functions to be provided are now started from the “on” prefix. Example: `onSaveStarted()`
* All parameters that are responsible for external decisions and require functions to be provided are now started from the “should” prefix. Example: `shouldBeSavedToLibrary()`

```js
metadata: {
    username
}
```

```js
draft: {
  showAutoSaveLoader: function() {
    console.log('Auto save in process')
  },
  hideAutoSaveLoader: function(error) {
    console.log('Auto save completed')
  }
}
```

```js
onSaveStarted: function() {
    console.log('Auto save in process');
},
onSaveCompleted: function(error) {
    console.log('Auto save completed');
}
```

```
https://plugins.stripo.email/static/latest/assets/i18n/en.json
```

```
https://github.com/stripoinc/stripo-plugin-releases/blob/main/static/assets/i18n/en.json
```

```js
blocks: { 
    moveBlockAvailability: true 
}
```

```js
modules: {
    syncModulesEnabled: true
}
```

```js
imageLibrary: {
    needHideImageUrlFunc: function(url) {
        return url.includes('test.com');
    }
}
```

```js
shouldHideImagePath: function(url) {
    return url.includes('test.com');
}
```

## JavaScript API

**v1 Syntax**

```js
const stripoEditorApi = window.StripoApi;
```

**v2 Syntax**

```js
const stripoEditorApi = window.StripoEditorApi;
```