Developing for Jira Cloud mobile and desktop clients

Jira Cloud is available on iOS and Android 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:

• Issue glances
• Issue context
• Right context web panel

The supported module will be visible from the issue view on Jira for iOS version 165 or later and Jira for Android version 103 or later.

The new issue context module will be available by default in the iOS and Android apps. If you don't add the appropriate flag to the issue context module, users will automatically see the content of your marketplace app when they select it from within a Jira issue.

This page explains how to add the appropriate flag to the module descriptor so that users will NOT be able to see your marketplace app.

Use OAuth 2.0 for authentication

Use the OAuth 2.0 (3LO) context path for API calls. Jira mobile 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).

To prevent issue context module from showing

Add flag and set to false

Issue context modules are shown by default. To prevent issue context modules from appearing in Jira mobile clients, add the jiraNativeAppsEnabled property to the issue module descriptor with the value false. If the issue context module is left blank, the issue context module will appear in the apps.

For more information, see the Issue context module documentation.

To show glance or right context web panel

Add flag and set to true

Glance panels and right context web panels are hidden by default.

To show an issue glance in Jira mobile 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 web panel in Jira mobile clients, 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 clients, leave the flag blank (for issue context modules) or set the flag as described above and then install it on your developer instance of Jira(for right context web panels). 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 (for right context web panels), or with the flag blank (for issue context modules), and all users with Jira for iOS and Android 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 issue context modules, 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 Android Jira Cloud mobile client and check whether your marketplace app renders and behaves as expected on a mobile 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 on smaller screens. Then hide parts of the marketplace app when you detect that it's running on mobile..

Use external links

Links that interact with other elements within Jira don’t work in marketplace apps running in the mobile 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 issue context module.

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 method 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.