Bitbucket install button

What is this?

This tiny JavaScript library is an easy way to embed an install button or link for your Bitbucket add-on on an external marketing site, documentation page, or blog.

It also handles the query parameters passed by Bitbucket back to your site after a successful or failed installation.

Here's an example button that installs a demo add-on in your account:

Install on Bitbucket


Add this script and its only dependency (jquery) to your page:

<script src=""></script>
<script src=""></script>

Button HTML

Add one or more install button links to your page:

<a class="aui-button aui-button-primary bitbucket-install-button" href="#">Install on Bitbucket</a>

The one above is styled to look like a button using AUI. Don't worry about the href, it will be replaced by the script.

Binding your button

You can specify your add-on's descriptorUri and a redirectUri to redirect the user to afterwards.

  descriptorUri: "https://path/to/your/descriptor.json",
  redirectUri: "https://addonBaseUrl/some/path.html"

Both URIs must be absolute and secured with HTTPS. The redirect_uri must start with the baseUrl.

The redirectUri defaults to the page the button is on if omitted.

The descriptorUri defaults to connect.json (relative to the page the button is on) if omitted.

So often you can bind your install button simply with:


Handling redirects

The library can also handle the parameters appended by Bitbucket to the redirectUri when an add-on installation succeeds or fails.

  always: function() {
    alert('An add-on installation was attempted...');
  success: function(params) {
    alert('...and it succeeded! The clientKey is ' + params.clientKey);
  error: function(params) {
    alert('...but it failed! The error was ' + params.error);

The always() function is invoked before success() or error().

There's also built in support for using standard AUI messages to display success and error messages.

  always: function() {
    $(".aui-page-panel-content").prepend("<div id='aui-message-bar'>");
  successMessage: function(params) {
    return "The add-on was successfully installed! It's clientKey is <strong>" + params.clientKey + "</strong>";
  errorMessage: function(params) {
    return "The add-on installation failed. Error: <strong>" + params.error + " (" + params.error_description + ")</strong>."

This is the code powering the Install on Bitbucket button at the top of this page if you want to see the AUI messages in action.

Advanced stuff

Check out the jsdoc for more information.

More info

Was this useful? Have a question or suggestion? @kannonboy.

The source code for this site is available on Bitbucket.