Connect JavaScript API

Overview

Connect apps extend Jira and Confluence by adding a custom iframe into the products' web pages. This iframe instance is on a different domain or hostname from the parent page and so is a sandboxed environment. The browser's same origin policy applies to this sandboxed environment, meaning that:

  • Stylesheet properties from the page don't cascade to the iframe
  • The iframe has no access to its parent's DOM and JavaScript properties
  • The page has no access to the iframe's DOM or JavaScript properties

As a result, for example, a Jira Connect app would be unable to make any changes to a ticket or a Confluence Connect app made any changes to a Confluence page.

The Atlassian connect JavaScript API is designed to overcome this limitation. It enables JavaScript code in a Connect app's iframe to interact with the underlying platform APIs. To do this, it makes use of three technologies:

Features

The Atlassian Connect JavaScript API provides the following features:

  • Context—retrieve the product context as an object or JWT token
  • Confluence (Confluence only)—interact with Confluence features
  • Cookie—save, retrieve, and delete cookies
  • Custom content (Confluence only)—interact with the custom content
  • Dialog—create and manipulate dialogues
  • Events—create listeners for and emit events to communicate within and between apps
  • Flag—provide system feedback in the product UI
  • History—navigate and manipulate a page's browsing history stack
  • Host—retrieve selected text from the host page
  • iframe—resize the app's iframe
  • Inline dialog—hide an inline dialog
  • Jira (Jira only)—interact with Jira features
  • Navigator—get webpage location, and navigate to a and reload a webpage
  • Request—make an XMLHttpRequest to the host product
  • User—obtain the user's Atlassian account ID, time zone, and locale

Limited mobile support

Most of these APIs are unsupported by the Jira and Confluence mobile apps. The APIs that have mobile app support are openIssueDialog and setDashboardItemTitle.

Sharing data between iframes

An app can generate multiple iframes in a page in the target application. These iframes may need to share information.

The Atlassian Connect JavaScript client library, all.js, provides a publish/subscribe mechanism to exchange data between iframes.

A common scenario where an app presents multiple iframes in a page is where a web panel or other page element spawns a dialog box.

The only restriction on the data shared in this manner is that it must be serializable using the structured clone algorithm.

For more information see the event API.

JavaScript client library

Atlassian Connect provides a JavaScript client library called all.js.

1
2
https://connect-cdn.atl-paas.net/all.js

This library establishes the cross-domain messaging bridge with its parent. It also provides several methods and objects that you use in your pages without making a trip back to your app server.

You add the all.js script to your pages to establish the cross-domain messaging bridge with the following script:

1
2
<script src="https://connect-cdn.atl-paas.net/all.js"></script>

If you're using the atlassian-connect-express client library to build your app, this script is inserted into your pages at run time.

Note:

Don't download the all.js file and serve it up from your app server directly. The all.js file must be served up by Atlassian for the cross-domain messaging bridge to be established.

The all.js file is only intended for use in an iframe inside an Atlassian product and does not work for standalone web pages.

Options

The JavaScript client library has configuration options for customizing its behavior. The options are passed using the data-options attribute.

1
2
<script src="https://connect-cdn.atl-paas.net/all.js" data-options="option1:value;option2:value"></script>

If you're using requirejs or another dynamic script loader, use an element with an ID of ac-iframe-options in place of a script tag.

1
2
<div id="ac-iframe-options" data-options="option1:value;option2:value"></div>

The following options are supported:

OptionValuesDefaultDescription
resizetrue or falsetrueYou can deactivate the automatic resizing by setting resize=false.
sizeToParenttrue or falsefalseWith sizeToParent:true, the iframe takes up its parent's space (instead of being sized to its internal content).
margintrue or falsetrueIf true, the margin option sets the body element's top, right, and left margin to 10px for dialogs and to 0 for non-dialog pages.
basetrue or falsefalseWith base:true, a base tag pointing to the host page is injected: <base href="{host}" target="_parent" />. This is useful for embedded links to product pages.

Debugging all.js

You can view an uncompressed version of the all.js JavaScript by replacing all.js with all-debug.js, for example:

1
2
<script src="https://connect-cdn.atl-paas.net/all.js"></script>
<!-- replace with -->
<script src="https://connect-cdn.atl-paas.net/all-debug.js"></script>

This can be helpful when tracing errors or debugging the app JavaScript.

To make all.js errors available to scripts running in your iframe (for example, front end monitoring such as Sentry or New Relic), make a CORS request:

1
2
<script src="https://connect-cdn.atl-paas.net/all.js" crossorigin="anonymous"></script>

Note on URL encoding

URL query parameters are encoded as application/x-www-form-urlencoded. This converts spaces to + which can cause issues when using JavaScript functions such as decodeURIComponent. A simple way to handle this is to convert + to %20 before decoding. A utility function decodeQueryComponent is provided for this purpose. For example:

1
2
AP._util.decodeQueryComponent(window.location.href);

Product cookbooks

For product-specific examples of what you can do through the front end JavaScript API that Connect provides, check out the Product cookbook.

Rate this page: