Transition checklist: from Modern Widget to Widget 2.0

Here's a list of key considerations if you're considering or planning to upgrade from using the Modern Widget to Widget 2.0:

 Update Widget Settings to use Widget 2.0 (Settings > Widget, select Widget 2.0 rather than Modern Widget. Click Save.)

 Copy the new embed script into your test environment or application. The Modern Widget in your live environment should continue to work while you do this testing. If you'd prefer, we're happy to provide a sandbox copy of your live knowledge base so you can test Widget 2.0 settings without any potential impact to your current widget usage; contact us to request a sandbox copy and let us know how long you think you'll need it. We recommend using a sandbox if you're switching authentication types, etc., during this process.

 Choose display settings and tweak colors to match your branding. You can use Custom CSS to change fonts, styles, etc. We also no longer do the tab + label display automatically--default display options are a ? icon or attach to element. See Widget configuration & installation for more details.

 Customize tab labels, text, and headers: Modern Widget had all content in a single scrolling tab. Widget 2.0 has three different tabs (Knowledge, Recommended, and Contact), so it may take some time for you to decide on tweaks to the tab labels, headers, contact form, etc.

As of August 2021, the Widget 2.0 Contact Form does not incorporate Custom Fields or ZenDesk fields in the main Knowledge Base > Contact Form settings. Contact us if you'd like to be added to the feature request for any of these fields.

 Update Outer Widget Styles and Contact Form CSS: Styles included in Outer Widget Styles and Contact Form CSS of Modern Widget should be reviewed before being included in Widget 2.0's Custom Widget styles, as containers and styles have changed.

 Update Javascript: If you have custom JS in your website/application or included in the Custom Body Content of your Modern Widget, add that to Widget 2.0's Custom Widget Javascript. This entire section gets wrapped in <script> tags, so you don't need to include them.

 Update your authentication: If you previously used an authenticated widget, you can now choose between JWT and OAuth2 authentication. Some authorization used to be partially included in our embed script in the  _ko16_p.push(['_setToken', 'OAUTH2 TOKEN']); section; it is no longer included and you'll need to handle that code yourself.

 Review your existing implementation for uses of _ko16 functions and methods: These will no longer work in Widget 2.0 and need to be transitioned to their _ko19 equivalents. See Widget methods and functions dictionary for all options available in Widget 2.0.

  • _ko16.openArticle('article-permalink'); would open the widget to a specific article; in Widget 2.0, _ko19.OpenArticle('article-permalink'); needs to be used followed by _ko19.open();
    • To open Modern Widget to a specific tab, several different methods might have been used; in Widget 2.0, you can choose several different load methods and choose them onOpen (end-user still must click to open the widget) or onLoad (widget will open and display that tab on full page load, no interaction required.
    • For Single Page Application behavior, Modern Widget used __ko16.updatePageLoc('currentUrl'); whereas Widget 2.0 uses _ko19.updateRecommended('currentUrl');
    • Using a _ko16 method not referenced here, and unsure how to update it? Contact us with a sample of the code and behavior and we'll get you what you need.

 Replace the existing embed script in your website or application with the new embed script.