If you’re the developer of a Chrome extension, after a user installs your extension from the Chrome Web Store, you may want to redirect the user to a particular website. For example, if you make a Gmail extension, you may want to redirect the user to Gmail immediately after they install the extension so they can begin using it.

Why is this necessary?

Recently, Google disabled inline installations of Chrome extensions. When inline installation was allowed, developers of Chrome extensions like myself had more control over what happens when a user installed an extension from our website. From the GMass website, you could install the Chrome extension without going to the Chrome Web Store, and then right after installation, I could redirect the user to gmail.com. It was an easy, seamlessess experience.

Now, however, since inline installation has been deprecated, some creativity is required to create that same seamless experience. Now, all Chrome extensions have to be installed from the Chrome Web Store, and by default, when the extension is installed, nothing happens. The user remains on the Chrome Web Store. The user isn’t taken to the website that the extension applies to, in my case, Gmail, automatically.

The developer has a couple of choices of how to redirect the user to the desired website, and in this article, I’ll discuss those options.

The super simple option to load Gmail after an extension install

If you’re developing a Chrome extension for Gmail, after the user installs the extension from the Chrome Web Store, you probably want the redirect the user to gmail.com. The easiest way to do this is to use the chrome.runtime.oninstall event in a background.js file, and this is also how I do it for GMass.

Designate a background script in your manifest.json file, and this code will do the trick:

chrome.runtime.onInstalled.addListener(function() {
  alert('You just made the best decision of today, by installing GMass!\n\nWe will now redirect you to your Gmail account so you can get started sending email campaigns inside Gmail.');

  chrome.tabs.create({
    url: 'https://mail.google.com',
    active: true
  });

  return false;
});

You can even throw in that JavaScript alert, but that could also get annoying, so consider carefully before you do that.

Notice that I’m using the chrome.tabs API to create a new tab which will load Gmail and now the be the focused tab in the browser. I could have also used:

window.open("https://mail.google.com");

…but doing so has a couple of disadvantages:

1. window.open could be stopped by a popup blocker
2. Depending on a user’s individual browser settings, this may open up a new window rather than a new tab in the existing window, which wouldn’t be as nice of a user experience

Note that you don’t need to add any additional “permissions” to your manifest to do this. I’m always wary of adding “permissions” because doing so forces a new warning message to pop up when a user’s browser updates your extension with the latest version.

A smarter option that detects what tabs are already open

The super simple option works for most cases, but if you want to give your users a really slick experience, it has a couple of flaws:

1. If the user already has Gmail opened in a browser tab, it might annoy the user to now open up a second tab with Gmail in it. And you want happy users, not annoyed users.
2. Many people have multiple Gmail accounts and are logged into them at the same time. Gmail “numbers” the logged-in Gmail accounts and creates URLs to those accounts in the format of https://mail.google.com/mail/u/0, https://mail.google.com/mail/u/1 and so on and so forth. If a user has an existing tab open to https://mail.google.com/u/1, and that’s the account he wishes to use with your extension, the super simple method will launch https://mail.google.com which will always redirect to https://mail.google.com/u/0, so now the user is on a different Gmail account than the one on which they want to use your extension.

It would be ideal to be able to detect if the user already has a Gmail browser tab open, and reload just that tab and bring the focus to it, or, if the user does not already have a Gmail browser tab open, then open one for them, and just assume it’s the 0-numbered user they want to open. Of course the user can obviously navigate to any Gmail account he wishes.

Note that regardless of how the webpage is reloaded, reloading is necessary after the installation of a Chrome extension in order for it to run and appear as part of that webpage, whether it’s for Gmail or something else.

One of my least favorite Chrome extensions is Mixmax. Perhaps I’ll dive into why I dislike it so much in a future article, but I do bestow praise upon their developer for doing something smart. He wrote a routine in background.js that detects if any Gmail tabs are already open, and if so, the focus is brought to that tab, and the tab is reloaded. If not, a new tab is opened. This kind of seamless experience, however, comes at a cost.

chrome.runtime.onInstalled.addListener(function(details) {
  if ((details.reason === 'install') || (details.reason === 'update')) 
  { 
    refreshBrowser('gmail-inbox', true); 
  } 
}); 

function refreshBrowser(target, bringToForeground) {
  if (target !== 'gmail-inbox') return; 
  chrome.windows.getAll({ populate: true }, function(windows) 
  { 
    var foundExisting = false; 
    windows.forEach(function(win) 
    {
      win.tabs.forEach(function(tab) 
      { 
        // Ignore tabs not matching the target. 
        if (target === 'gmail-inbox') { 
          if (!/https:\/\/(mail|inbox)\.google\.com/.test(tab.url)) return; 
        } 
        else 
        { 
          return; // Unknown target. 
        } 
        // Reload the matching tab.  
        chrome.tabs.reload(tab.id); // If this is the first one found, activate it. 
        if (bringToForeground && !foundExisting) 
        {
          chrome.tabs.update(tab.id, { active: true }); } 
          foundExisting = true; 
        }); 
      }); 
      // If no gmail tab found, just open a new one. 
      if (bringToForeground && !foundExisting) 
      { 
        chrome.tabs.create({ url: (target === 'gmail-inbox') ? 'https://mail.google.com' : 'https://www.mixmax.com', active: true 
      });
    } 
  });
}

Analyzing the code

Looking at the code, it loops through each tab in the window checking if its URL is either mail.google.com or inbox.google.com. If so, then that tab is reloaded. If no tab is found with Gmail, then a tab is created and its focus is set.

What is the cost that it comes with? You must add the “tabs” permission to your manifest.json, and doing so triggers a warning that will scare off some users:

Ouch. In today’s age of privacy and security, that warning is enough to scare off most would-be new users. And in fact, that could be why their user installs have been dropping, according to Chrome Compete. Technically if you only had the “tabs” permission declared in manifest.json, the warning would say: “Read your browsing history”, but in the case of Mixmax, they request a bunch of other permissions as well, and “Read and change all your data…” supersedes the “Read your browsing history” statement so that warning is used instead.

The reason you have to add the “tabs” permission to manifest.json to begin with in this scenario but not the super simple scenario I’m using with GMass above is that is explained by Google:

The majority of the chrome.tabs API can be used without declaring any permission. However, the "tabs"permission is required in order to populate the url, title, and favIconUrl properties of Tab.

Meaning, if you want to read the URL of the tab, in order to detect that the user is already on a certain webpage, as the Mixmax example does, then you need to request the “tabs” permission. But if you just want to create a tab, as I do in the super simple example, then you don’t need the “tabs” permission.

To compare this is the warning you get when you install the GMass Chrome extension:

See the difference? Hopefully this warning is a lot less scarier than the prior one.

One day I hope GMass ranks among the most popular Chrome extensions for Gmail, but for now, I have the utmost respect for the currently most popular Gmail Chrome extensions, including Streak, Boomerang, Yesware, Gmelius, and Sortd. I often examine how these other Chrome extensions handle an issue when I’m trying to solve an issue of my own. In researching these other extensions for this article, I was curious how each of them handles the post-install experience for the user. Here are the results:

1. Boomerang: Creates a new tab that loads up a “welcome” page on their website, boomeranggmail.com, which then quickly redirects to gmail.com.
2. Yesware: doesn’t redirect the user at all after install
3. Gmelius: launches a new tab that loads gmail.com, regardless of what other tabs are open
4. Sortd: detects what tabs already have Gmail loaded and reloads just those, and therefore requires a stricter warning upon install, similar to Mixmax
5. Streak: doesn’t redirect the user at all after install

Summary

So to summarize, even though Google has deprecated inline installation for Chrome extensions, you can still control the experience of the user after they install an extension by redirecting them to the website of your choice. How sophisticated you want to get with that redirect, meaning whether you want to launch a new tab regardless of what tabs are already open, or whether you want to detect whether the website is already open, dictates which approach you take and what warnings the user sees when installing.

Ajay Goel

Ajay is the founder of GMass and has been developing email sending software for 20 years.