Optimizely – Install the Quickchannel Plugin (Optimizely CMS 13)

This article covers how to install the Quickchannel plugin for Optimizely CMS 13.

For Optimizely CMS 12, see Optimizely – Install the Quickchannel Plugin (Optimizely CMS 12).

Plugin version	Optimizely CMS	Target framework
2.x	13	.NET 10
1.x	12	.NET 5 / .NET 6

Important: Plugin 2.x requires Optimizely CMS 13 and the .NET 10 SDK. It does not work with CMS 12, and plugin 1.x does not work with CMS 13. The CMS upgrade and plugin upgrade therefore need to happen together.

To install the plugin, you need administrator privileges on your Optimizely CMS and Quickchannel accounts.

1. Create a REST API access token

In the Quickchannel console, create a REST API access token with the following privileges:

• Read
• Write
• Upload

We recommend setting the access level to Public so that only approved media is displayed.

However, if editors are allowed to upload media from Optimizely, the token must have Full access. Otherwise, an uploaded video will not be visible afterwards.

See How do I create a REST API Access token? for more information.

You also need the account ID, which is six digits and is also known as the custid.

2. Install the NuGet package

Install version 2.x of:

Screen9.Optimizely.CMS.UI

This package automatically brings in:

• Screen9.Optimizely.CMS
• EPiServer.CMS.TinyMce

Do not add these packages separately.

Using the .NET CLI

dotnet add package Screen9.Optimizely.CMS.UI --version 2.0.0

Using Visual Studio

Right-click your Optimizely project and choose Manage NuGet Packages….

Set the package source to nuget.org, search for Screen9.Optimizely.CMS.UI, and install the latest 2.x version.

Your project must target net10.0 and reference CMS 13. For example:

<TargetFramework>net10.0</TargetFramework>

...

<PackageReference Include="EPiServer.CMS" Version="13.0.0" />
<PackageReference Include="Screen9.Optimizely.CMS.UI" Version="2.0.0" />

Note: In CMS 13, the EPiServer.CMS metapackage no longer pulls in EPiServer.Cms.UI.AspNetIdentity. If your site uses ASP.NET Identity, reference it explicitly.

Restoring CMS 13 packages also requires the Optimizely NuGet feed in addition to nuget.org:

<add key="optimizely" value="https://api.nuget.optimizely.com/v3/index.json" />

3. Add the Quickchannel configuration

Add the following configuration to appsettings.json:

{
  "Screen9Settings": {
    "AccountId": "123456",
    "RestApiToken": "Token_value",
    "Disabled": false
  }
}

Setting	Meaning
AccountId	The six-digit account identifier (custid).
RestApiToken	The Quickchannel REST API token created in step 1.
Disabled	Optional. Set to true to disable the Quickchannel content provider without removing the package.

If editors upload large files, you may also need to increase the CMS upload limit:

{
  "EPiServer": {
    "CmsUI": {
      "Upload": {
        "FileSizeLimit": 104857600
      }
    }
  }
}

Security: Do not store the REST API token in source control. For local development, use dotnet user-secrets. In hosted environments, use the platform's configuration or secret store.

4. Enable the Quickchannel integration

The Quickchannel extension methods are available through Screen9.Optimizely.Extensions.

In CMS 13, the CMS registration extensions are in the EPiServer.DependencyInjection namespace.

In your site's service configuration, add the Quickchannel integration after services.AddCms():

using EPiServer.DependencyInjection;
using Screen9.Optimizely.Extensions;

services
    .AddCmsAspNetIdentity<ApplicationUser>()
    .AddCms();

services.AddScreen9Integration(configuration);
services.AddScreen9TinyMCEIntegration();

AddScreen9Integration registers:

• the Quickchannel content provider
• the Quickchannel asset pane
• the plugin views

AddScreen9TinyMCEIntegration registers the TinyMCE plugin and adds the Quickchannel button to the default editor toolbar.

If you do not call AddScreen9TinyMCEIntegration(), the Quickchannel button will not appear in the editor.

Important: service registration order

The order matters in CMS 13. AddCms() registers TinyMCE, so both Quickchannel calls must be made after services.AddCms().

AddScreen9Integration requires an IConfiguration. If your project template does not inject one into Startup, add it to the Startup constructor:

public class Startup(
    IWebHostEnvironment webHostingEnvironment,
    IConfiguration configuration)

Rebuild the project

After installing the package, rebuild the project.

The build copies the frontend files into:

modules/_protected/Screen9.Optimizely.CMS.UI

Without a rebuild, the Quickchannel asset pane may remain empty.

5. Use Quickchannel videos

The Optimizely CMS 13 editorial interface is available at:

/Optimizely/CMS

On DXP installations using Opti ID, the address is:

/ui/CMS

The CMS 12 /episerver address no longer exists.

Videos from the Quickchannel platform appear in the Screen9 Video asset pane.

Disable uploading from the asset pane

You can disable uploading from the asset pane by changing the Create access rights for the Screen9 Video content folder.

Refresh interval

The media list is updated every 30 minutes by default.

You can change this interval under:

Admin → Scheduled Jobs → Screen9 Integration Job

Setting the interval to less than 5 minutes is not recommended.

You can also update the media list manually by selecting Start Manually.

Development environments: If your configuration contains services.Configure<SchedulerOptions>(options => options.Enabled = false);, the scheduled job will not run automatically.

6. The Quickchannel button in the TinyMCE toolbar

If you have added:

services.AddScreen9TinyMCEIntegration();

the Quickchannel button is added to the default TinyMCE toolbar automatically.

You only need to configure the toolbar manually if your site defines a custom TinyMCE toolbar for a property.

To configure a custom toolbar:

1. Log in to the Optimizely CMS.
2. Open Admin.
3. Go to Content Type.
4. Select the relevant page type.
5. Select the relevant property, such as MainBody.
6. Open Custom Settings.
7. Select Use custom settings under TinyMCE Editor.
8. Under Miscellaneous, locate the Quickchannel icon.
9. Drag it into the desired location in the editor toolbar.
10. Save the configuration.

The Quickchannel Video button will then be available in the customized TinyMCE toolbar.

7. Verify the installation

After installing and configuring the plugin, verify the following:

• The startup log contains Adding module Screen9.Optimizely.CMS.UI.
• The Screen9 Video folder is available in the asset pane and displays media with thumbnails.
• Admin → Scheduled Jobs contains Screen9 Integration Job.
• Running the integration job manually reports how many folders and media items were processed.
• The Quickchannel button is available in the TinyMCE toolbar and inserts a working embed.
• Uploading a file from Optimizely succeeds and the video appears in the asset pane.

8. Upgrading from plugin 1.x (CMS 12)

Because the CMS major upgrade and Quickchannel plugin upgrade must happen together, perform both upgrades as part of the same upgrade.

Back up before upgrading

Starting the site on CMS 13 upgrades the database schema irreversibly.

Back up both:

• the database
• the blob storage, for example App_Data/blobs

Make sure you can restore both before proceeding.

8.1 Update the package references

Retarget the project to net10.0, move the CMS packages to 13.x, and replace the 1.x Quickchannel references with a single 2.x reference to:

Screen9.Optimizely.CMS.UI

If the project file contains Compile Remove or None Remove entries pointing into the 1.x package cache, such as:

.nuget/packages/screen9.optimizely.cms.ui/1.0.x/contentFiles/any/net5.0/…

delete them. They are not required with plugin 2.x.

8.2 Remove the old frontend module

Delete:

modules/_protected/Screen9.Optimizely.CMS.UI

before restoring packages.

The directory is not cleaned automatically, and a leftover 1.x layout can shadow the new frontend module.

After rebuilding, the directory should contain only:

Screen9.Optimizely.CMS.UI.zip
Views

8.3 Raise the database compatibility level

CMS 13 requires a database compatibility level of at least 140 (SQL Server 2017).

Older databases may fail to start with an error indicating that the compatibility level is unsupported.

You can allow CMS to raise the compatibility level on startup by adding:

{
  "EPiServer": {
    "Cms": {
      "DataAccess": {
        "UpdateDatabaseCompatibilityLevel": true
      }
    }
  }
}

Alternatively, raise it manually using the highest compatibility level supported by your SQL Server:

ALTER DATABASE [YourDatabase] SET COMPATIBILITY_LEVEL = 150;

8.4 Update the service configuration

The Quickchannel extension methods and Screen9Settings keys are unchanged.

Add:

using EPiServer.DependencyInjection;

and make sure the Quickchannel registration occurs after:

services.AddCms();

For example:

services.AddScreen9Integration(configuration);
services.AddScreen9TinyMCEIntegration();

Also be aware of CMS 13 breaking changes that may affect sites based on the Alloy template, including:

• The generic IContentTypeRepository<T> overload was removed. Use the non-generic IContentTypeRepository and cast the result.
• IContentRouteHelper.Page was removed. Use PageContext.Content.
• If your site links to the editorial interface, resolve module paths through EPiServer.Shell.Paths.ToClientResource() instead of hard-coding /episerver or /Optimizely.

8.5 Run the Screen9 Integration Job once

After upgrading from plugin 1.x, run the Screen9 Integration Job manually once.

Plugin 1.x and 2.x store cached media data differently in the Dynamic Data Store. Although plugin 2.x can read rows written by 1.x, their blob references may deserialize as empty. The plugin can then prefer the cached row instead of retrieving fresh information from Quickchannel.

This can result in missing thumbnails in the asset pane.

To repair the cache:

1. Go to Admin → Scheduled Jobs.
2. Open Screen9 Integration Job.
3. Select Start Manually.

The job rewrites the cached rows and restores the thumbnails.

If the scheduler is enabled, the next scheduled run will also repair the cache within the configured job interval.

Blobs written by plugin 1.x are left in blob storage. They are harmless and can be removed manually if you want to reclaim storage space.

9. Troubleshooting

The asset pane is empty or the Screen9 Video folder is missing

1. Rebuild the project and confirm that:

   modules/_protected/Screen9.Optimizely.CMS.UI
   

   exists.

2. Check the application log. A missing or incomplete configuration is reported as:

   Screen9: … The content provider was not registered.
   

3. Verify:
   • AccountId
   • RestApiToken
   • Disabled is not set to true
4. Clear the browser cache because client-side modules are cached aggressively.

Media is listed but thumbnails are missing

If you have just upgraded from plugin 1.x, run the Screen9 Integration Job once as described in section 8.5.

The Quickchannel button is missing from the editor

Confirm that:

services.AddScreen9TinyMCEIntegration();

is registered and that it runs after:

services.AddCms();

If the property uses a custom TinyMCE toolbar, make sure the Quickchannel icon has been added to that toolbar manually.

/episerver returns 404

This is expected on CMS 13.

The editorial interface has moved to:

/Optimizely/CMS

On DXP with Opti ID, use:

/ui/CMS

An uploaded video is not visible

The REST API token must have Full access when uploading media from Optimizely.

For more information about using the plugin, see How do I use the Quickchannel Optimizely plugin