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:

The Web API Window.postMessage() method that safely enables cross-origin communication between Window objects, such as, between a page and an iframe embedded within it.
Simple XDM that exposes an API for cross-origin communication using postMessage()
The JavaScript methods that enable JavaScript within the app iframe to interact with the platform APIs in the page.

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.

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:

Option	Values	Default	Description
`resize`	`true` or `false`	`true`	You can deactivate the automatic resizing by setting `resize=false`.
`sizeToParent`	`true` or `false`	`false`	With `sizeToParent:true`, the iframe takes up its parent's space (instead of being sized to its internal content).
`margin`	`true` or `false`	`true`	If `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.
`base`	`true` or `false`	`false`	With `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.