Developing for Jira Cloud mobile and desktop clients

Jira Cloud is available on iOS, Android, and Mac with modules available for marketplace app developers.

Show your modules on the mobile and desktop clients

The modules supported by the mobile and desktop clients are:

The supported module will be visible from the issue view on Jira for iOS/Mac version 109 or later and Jira for Android version 55 or later.

NOTE: If you don't add the appropriate flags to the module descriptors (as described below), users will NOT be able to see the content of your marketplace app's glance or right context panel when they select it from within a Jira issue; instead, they will be prompted to send feedback to you (the marketplace app developer) directly, letting you know that glances/right context panels are not yet enabled for the Jira mobile and desktop clients.

This page explains how to add the appropriate flag to the module descriptor so that users will be able to interact with your marketplace app. This flag allows you to test your marketplace app locally, to ensure it behaves as intended within the Jira mobile and desktop clients before making it available to your users.

Use OAuth 2.0 for authentication

Use the OAuth 2.0 (3LO) context path for API calls. The Jira mobile and desktop clients use OAuth 2.0 (3LO). OAuth 2.0 (3LO) uses a context path, capturing all HTTP requests using api.atlassian.com/ex/jira/{cloudid}. This process ensures that your marketplace app accesses the correct Jira site on mobile. Don’t force your requests or resources through the root of the URL (that is, by querying “/” directly).

Add the flag to the module descriptor

To show issue glances in the Jira mobile and desktop clients, add the jiraNativeAppsEnabled property to the issue glance module descriptor with the value true. For more information, see the Issue glance module documentation.

To show a right context panel, add the supportsNative property to the web panel module descriptor with the value true. Note that the web panel needs to have the location property set to atl.jira.view.issue.right.context. For more information, see the Web panel module documentation.

Testing your changes

To test your marketplace app within the Jira mobile and desktop clients, set the flag as described above and then install it on your developer instance of Jira. Open an issue and view your marketplace app. See the following section for some suggested guidelines on tailoring your marketplace app's experience for smaller form factors (on mobile).

Once you are satisfied with your marketplace app's user experience, you can publish your marketplace app with the flag set, and all users with Jira for iOS, Android, and/or Mac will be able to use your marketplace app within Jira.

Design and testing guidelines

Here are some design guidelines for your marketplace apps:

A responsive mobile UI

Ensure that your glance panel, right-context-panels, pop-ups, and modals adapt to large panel sizes and smaller screen sizes. Ensure that your marketplace app’s pop-ups, flags, and dialogs are dismissible. The marketplace app’s pop-ups, flags, and dialogs must also fit on the screen without obstructing anything underneath.

When using the Atlassian UI components, such as AP.dialog or AP.flag, these components automatically resize to adapt to a mobile form factor. However, you need to ensure the content inside these dialogs looks and functions as you expect. When using custom UI components, use the CSS flexbox property to make sure content resizes and stretches to fit.

Test your marketplace app by downloading the iOS or AndroidJira Cloud mobile client and check whether your marketplace app renders and behaves as expected on a mobile screen.

A responsive desktop UI

If your marketplace app’s UI is mobile responsive, then it should work well on the desktop client. Your marketplace app on the glance panel and right-context-panels should automatically fill the glance space in the desktop marketplace app.

Test your marketplace app, download the Mac Jira Cloud desktop client and check whether your marketplace app renders and behaves as expected on a desktop screen.

Hide or show content depending on screen size

Typically, Jira Cloud mobile user use cases involve quick actions: users want to get in, do something quickly, and get back to work. Duplicating complex interactions on diagrams, charts, or graphs from the web may not be appropriate.

Think about mobile use cases and consider turning off features or tweaking features to make them easier to use in smaller screens. Then hide parts of the marketplace app when you detect that it is running on a mobile form factor.

Use external links

Links that interact with other elements within Jira don’t work in an marketplace app running in the mobile or desktop clients because these clients do not support all the plugin points available on the web. We recommend using external web links instead:

Normal hyperlinks are supported and open a new browser window on the user’s device.
iOS universal links and Android app links are supported. Some marketplace apps may want to open other mobile clients, and this is supported.

Tip: To promote your marketplace app and encourage downloads, include links to Apple App Store or Google Play Store within your glance.

Customize the experience based on the device

For control over the marketplace app experience by devices use:

the Jira Cloud Developer JS API: The Jira AP.Jira.isNativeApp returns true if a Jira Cloud user is using a native app.
a library to detect user device: Web frameworks may have libraries that enable detection of the device a user is using, such as OS and device type, not only on mobile but on all devices.