Open a "Help" page after Chrome extension is installed first time

Question

I am new to Chrome extension. I have a question about how to make the extension to open a "Help" page automatically after installation. Currently, I am able to check whether the extension is running the first time or not by saving a value into localStorage. But this checking is only carried out when using click the icon on the tool bar. Just wondering if there is a way that likes FF extension which uses the javascript in to open a help page after the installation. Thanks.

Edit: Thanks for the answer from davgothic. I have solved this problem. I have another question about the popup. My extension checks the url of current tab,

if OK(url){
    //open a tab and do something
}
else{
    //display popup
}

Is it possible to show the popup in this way?

possible duplicate of [Detect Chrome extension first run / update](http://stackoverflow.com/questions/2399389/detect-chrome-extension-first-run-update) — Alvin Wong, Nov 20 '13 at 12:50

score 94 · Answer 1 · edited Feb 18 '22 at 06:55

94

Check this updated and most reliable solution provided by Chrome: chrome.runtime Event

chrome.runtime.onInstalled.addListener(function (object) {
    let externalUrl = "http://yoursite.com/";
    let internalUrl = chrome.runtime.getURL("views/onboarding.html");

    if (object.reason === chrome.runtime.OnInstalledReason.INSTALL) {
        chrome.tabs.create({ url: externalUrl }, function (tab) {
            console.log("New tab launched with http://yoursite.com/");
        });
    }
});

Add this to your background.js I mean the the page you defined on manifest like following,

....
"background": {
      "scripts": ["background.js"],
      "persistent": false
  }
...

edited Feb 18 '22 at 06:55

philipp

4,133
1
36
35

answered Jun 26 '14 at 11:37

Nuhil Mehdy

2,424
1
21
23

15

Don't forget to check `if(object.reason === 'install')` in the callback or else this will fire for updates too. – kspearrin Nov 17 '16 at 05:40
2

or even `if (chrome.runtime.OnInstalledReason.INSTALL === object.reason)` – mhgbrown Feb 07 '17 at 23:43
6

Good solution. To open a local file you should add the 'tab part' it like this: `chrome.tabs.create({url:chrome.extension.getURL("help.html")}, function (tab) { console.log("New tab launched with local file"); });` – TheLD Oct 26 '17 at 09:43
simple one-liner: `chrome.runtime.onInstalled.addListener(({reason}) => { if (reason === 'install') chrome.tabs.create({ url: 'onboarding.html'}); });` – chale_brown May 30 '22 at 22:44
How to test this locally? – abyesilyurt Nov 27 '22 at 08:31
@abyesilyurt install it locally. – thdoan Mar 11 '23 at 01:17

David Hancock · Accepted Answer · 2017-06-13T16:15:24.987

30

UPDATE: This method is no longer recommended. Please see Nuhil's more recent answer below.

I believe what you need to do is put something like this into a script in the <head> section of your extension's background page, e.g. background.html

function install_notice() {
    if (localStorage.getItem('install_time'))
        return;

    var now = new Date().getTime();
    localStorage.setItem('install_time', now);
    chrome.tabs.create({url: "installed.html"});
}
install_notice();

edited Jun 13 '17 at 16:15

answered Apr 21 '11 at 15:14

David Hancock

14,861
4
41
44

Thanks, I moved my isFirstRun() script from my options.html to background.html and it works. I also have another question, FDF extension has "gBrowser.getNotificationBox()" to display a notification box. Has chrome the same thing. I had a look the Desk notification already, but i think it is too much (permission ...) for a simple displaying server message/warning. I am looking at the popup at the moment, i do not know if it is easy to use in my case, because i need the popup to display just under the address bar of the browser. Any better ideas ? – user200340 Apr 21 '11 at 15:33

Andreas Riedmüller · Answer 3 · 2022-08-05T08:18:00.777

As of now (Aug 2022) the right way to execute code on first install or update of an extension using Manifest V3 is by using the runtime.onInstalled event.

This event is documented here: https://developer.chrome.com/extensions/runtime#event-onInstalled

There is one example for this exact case in the docs now: https://developer.chrome.com/docs/extensions/reference/tabs/#opening-an-extension-page-in-a-new-tab

Note: This example above is wrong as the callback function parameter is Object with the key reason and not reason directly.

And another example here (this one is correct but does not open a tab): https://developer.chrome.com/docs/extensions/reference/runtime/#example-uninstall-url

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    // Code to be executed on first install
    // eg. open a tab with a url
    chrome.tabs.create({
      url: "https://google.com"
    });
  } else if (details.reason === chrome.runtime.OnInstalledReason.UPDATE) {
    // When extension is updated
  } else if (details.reason === chrome.runtime.OnInstalledReason.CHROME_UPDATE) {
    // When browser is updated
  } else if (details.reason === chrome.runtime.OnInstalledReason.SHARED_MODULE_UPDATE) {
    // When a shared module is updated
  }
});

This code can be added to a background service worker: https://developer.chrome.com/docs/extensions/mv3/migrating_to_service_workers/

Looks like the example was fixed since now parameter is an object with key `reason`: `chrome.runtime.onInstalled.addListener(({reason}) => {...` — izogfif, Mar 28 '23 at 12:56

score 5 · Answer 4 · edited May 23 '17 at 12:34

5

It would be better to place a "version" number so you can know when an extension is updated or installed.

It has been answered here: Detect Chrome extension first run / update

edited May 23 '17 at 12:34

Community

1
1

answered Apr 26 '11 at 03:28

Mohamed Mansour

39,445
10
116
90

score 2 · Answer 5 · answered Aug 21 '20 at 03:22

All you need to do is adding the snippet below to your background.js file

chrome.runtime.onInstalled.addListener(function (object) {
    chrome.tabs.create({url: `chrome-extension://${chrome.runtime.id}/options.html`}, function (tab) {
        console.log("options page opened");
    });
});

Open a "Help" page after Chrome extension is installed first time

5 Answers5