{"id":8251,"date":"2017-09-07T14:15:35","date_gmt":"2017-09-07T21:15:35","guid":{"rendered":"http:\/\/blog.mozilla.org\/addons\/?p=8251"},"modified":"2017-09-08T08:45:29","modified_gmt":"2017-09-08T15:45:29","slug":"tell-users-expect-webextensions-version","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/","title":{"rendered":"Tell your users what to expect in your WebExtensions version"},"content":{"rendered":"

The migration to WebExtensions APIs<\/a> is picking up steam, with thousands of compatible add-ons now available on addons.mozilla.org<\/a> (AMO). To ensure a good experience for the growing number of users whose legacy add-ons have been updated to WebExtensions versions, we\u2019re encouraging developers to adopt the following best practices.<\/p>\n

(If your new version has the same features and settings as your legacy version, your users should get a seamless transition once you update your listing, and you can safely ignore the rest of this post.)<\/em><\/p>\n

If your new version has different features, is missing legacy features, or requires additional steps to recover custom settings, please do one or both of the following.<\/p>\n

Update your AMO listing description<\/h2>\n

If your new version did not migrate with all of its legacy features intact, or has different features, please let your users know in the “About this Add-on” section of your listing.<\/p>\n

If your add-on is losing some of its legacy features, let your users know if it\u2019s because they aren\u2019t possible with the WebExtensions API, or if you are waiting on bug fixes or new APIs to land before you can provide them. Include links to those bugs, and feel free to send people to the forum<\/a> to ask about the status of bug fixes and new APIs.<\/p>\n

Retaining your users’ settings after upgrade makes for a much better experience, and there\u2019s still time to do it using Embedded WebExtensions<\/a>.<\/strong> But if this is not possible for you and there is a way to recover them after upgrade, please include instructions on how to do that, and refer to them in the Version notes. Otherwise, let your users know which settings and preferences cannot be recovered.<\/p>\n

Add an announcement with your update<\/h2>\n

If your new version is vastly different from your legacy version, consider showing a new tab to your users when they first get the update. It can be the same information you provide in your listing, but it will be more noticeable if your users don\u2019t have to go to your listing page to see it. Be sure to show it only on the first update so it doesn\u2019t annoy your users.<\/strong><\/p>\n

To do this, you can use the runtime.onInstalled<\/a> API which can tell you when an update or install occurs:<\/p>\n

function update(details) {<\/code><\/p>\n

if (details.reason === 'install' || details.reason === 'update') {<\/code><\/p>\n

browser.tabs.create({url: 'update-notes.html'});<\/code><\/p>\n

}<\/code><\/p>\n

}<\/code><\/p>\n

browser.runtime.onInstalled.addListener(update);<\/code><\/p>\n

This will open the page update-notes.html in the extension when the install occurs. For example:<\/p>\n

\"\"<\/a>For greater control, the runtime.onInstalled<\/a> event also lets you know when the user updated and what their previous version was so you can tailor your release notes.<\/p>\n

Thank you<\/h2>\n

A big thanks to all the developers who have put in the effort to migrate to the WebExtensions API. We are here to support you, so please reach out<\/a> if you need help.<\/p>\n","protected":false},"excerpt":{"rendered":"

The migration to WebExtensions APIs is picking up steam, with thousands of compatible add-ons now available on addons.mozilla.org (AMO). To ensure a good experience for the growing number of users … Read more<\/a><\/p>\n","protected":false},"author":377,"featured_media":1995,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[44,278886],"tags":[],"yoast_head":"\nTell your users what to expect in your WebExtensions version - Mozilla Add-ons Community Blog<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Amy Tsay\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"2 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/\",\"url\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/\",\"name\":\"Tell your users what to expect in your WebExtensions version - Mozilla Add-ons Community Blog\",\"isPartOf\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/blog.mozilla.org\/addons\/files\/2010\/10\/addons.png\",\"datePublished\":\"2017-09-07T21:15:35+00:00\",\"dateModified\":\"2017-09-08T15:45:29+00:00\",\"author\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/becbc6e5c1f9ed8217c36233bc1a7bec\"},\"breadcrumb\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#primaryimage\",\"url\":\"https:\/\/blog.mozilla.org\/addons\/files\/2010\/10\/addons.png\",\"contentUrl\":\"https:\/\/blog.mozilla.org\/addons\/files\/2010\/10\/addons.png\",\"width\":\"217\",\"height\":\"188\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/blog.mozilla.org\/addons\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Tell your users what to expect in your WebExtensions version\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#website\",\"url\":\"https:\/\/blog.mozilla.org\/addons\/\",\"name\":\"Mozilla Add-ons Community Blog\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/blog.mozilla.org\/addons\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/becbc6e5c1f9ed8217c36233bc1a7bec\",\"name\":\"Amy Tsay\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/db8d681801f2c6406fb3e53d48db2909?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/db8d681801f2c6406fb3e53d48db2909?s=96&d=mm&r=g\",\"caption\":\"Amy Tsay\"},\"description\":\"Lead for Firefox Add-ons at Mozilla.\",\"sameAs\":[\"https:\/\/x.com\/catchingamy\"],\"url\":\"https:\/\/blog.mozilla.org\/addons\/author\/atsaymozilla-com\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Tell your users what to expect in your WebExtensions version - Mozilla Add-ons Community Blog","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/","twitter_misc":{"Written by":"Amy Tsay","Est. reading time":"2 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/","url":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/","name":"Tell your users what to expect in your WebExtensions version - Mozilla Add-ons Community Blog","isPartOf":{"@id":"https:\/\/blog.mozilla.org\/addons\/#website"},"primaryImageOfPage":{"@id":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#primaryimage"},"image":{"@id":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#primaryimage"},"thumbnailUrl":"https:\/\/blog.mozilla.org\/addons\/files\/2010\/10\/addons.png","datePublished":"2017-09-07T21:15:35+00:00","dateModified":"2017-09-08T15:45:29+00:00","author":{"@id":"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/becbc6e5c1f9ed8217c36233bc1a7bec"},"breadcrumb":{"@id":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#primaryimage","url":"https:\/\/blog.mozilla.org\/addons\/files\/2010\/10\/addons.png","contentUrl":"https:\/\/blog.mozilla.org\/addons\/files\/2010\/10\/addons.png","width":"217","height":"188"},{"@type":"BreadcrumbList","@id":"https:\/\/blog.mozilla.org\/addons\/2017\/09\/07\/tell-users-expect-webextensions-version\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/blog.mozilla.org\/addons\/"},{"@type":"ListItem","position":2,"name":"Tell your users what to expect in your WebExtensions version"}]},{"@type":"WebSite","@id":"https:\/\/blog.mozilla.org\/addons\/#website","url":"https:\/\/blog.mozilla.org\/addons\/","name":"Mozilla Add-ons Community Blog","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/blog.mozilla.org\/addons\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/becbc6e5c1f9ed8217c36233bc1a7bec","name":"Amy Tsay","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/db8d681801f2c6406fb3e53d48db2909?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/db8d681801f2c6406fb3e53d48db2909?s=96&d=mm&r=g","caption":"Amy Tsay"},"description":"Lead for Firefox Add-ons at Mozilla.","sameAs":["https:\/\/x.com\/catchingamy"],"url":"https:\/\/blog.mozilla.org\/addons\/author\/atsaymozilla-com\/"}]}},"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/posts\/8251"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/users\/377"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/comments?post=8251"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/posts\/8251\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/media\/1995"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/media?parent=8251"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/categories?post=8251"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/tags?post=8251"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}