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:
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:
Window.postMessage()
method that safely enables cross-origin communication between Window objects, such as, between
a page and an iframe embedded within it.postMessage()
The Atlassian Connect JavaScript API provides the following features:
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.
Atlassian Connect provides a JavaScript client library called all.js
.
1 2https://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.
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.
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. |
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>
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 2AP._util.decodeQueryComponent(window.location.href);
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: