App versioning allows you to add, change, or remove parts of your app's functionality without impacting users. Our versioning mechanism enables you to create new draft versions to make changes to the app.

Every change (e.g., updating permissions, adding or deprecating a feature, fixing a bug, etc.) can be done in one type of version, so there is no need for major or minor versions.

Once your draft version is ready for release, you can promote it to live and it will automatically push the updates to app users. Most changes will automatically be implemented, but some, like updated scopes or permissions, may require user approval. In these instances, users will maintain access to the app but it may not work properly until the changes are approved. These updates will be communicated through app view and integration store banners to encourage users to accept them.

Managing versions

We currently support just one type of app version that enables you to make any changes without disrupting user workflows. You can create a new version, promote a draft version to live, or delete a draft version in your app's App Versions tab.

Create a new version

You can create a new version when you need to make changes to your app. The draft version takes all of the configurations from your app's current live version (e.g., scopes, OAuth, features, app name, etc.), so you must manually update them if you want to make any changes.

The version number follows your app's most recent version (draft or live). If your app's live version is v1, but the highest version in your drafts is v3, the new version number will be v4.

You can create a new version from two different places:

1. Open the App Versions tab > click New version
2. Click the New version button under your app's name (this button only appears if you don't already have a draft version)

Promote a draft version to live

You can also promote a draft version to live from two different locations:

1. Open the App Versions tab > select the three-dots in the Actions column > click Publish
2. Click the Promote to live button under your app's name (this button only appears when you have a draft version)

Delete a draft version

The app version list can easily become cluttered after creating multiple versions, so you can delete draft versions to keep your app organized. To ensure continuity for your users, you cannot delete live or deprecated versions. Follow these quick steps to delete a draft version:

1. In the App versions tab, click the three-dots on the far right
2. Select Delete this version
3. Click Delete

Supporting past versions

Even though new versions are automatically pushed to users, some changes (e.g., permissions and scope changes) require manual approval. As a result, accounts may be using your app with various scopes and permissions. Your app’s backend must support the logic of your old versions to account for this. If your app utilized our versioning mechanism prior to January 2024, you must support the logic of your old major versions.

This could mean having endpoints to support old integration recipes or fallback logic in your app’s code if a particular setting or field doesn’t exist. Generally speaking, you should build your backend to support all previous app versions.

If you decide to fully deprecate an old version, you can send the user notifications or show them a screen prompting them to reinstall the app's newest version.

Versioning capabilities

Create an app feature

Using app versioning, you can always add new app features without disrupting existing app users. Once you've created a new draft app version, follow these steps to add a new app feature!

Remove an app feature

When you create a new version, you have the option to either deprecate (recommended) or delete an app feature. Deprecating a feature allows you to set a deprecation date to alert users of the feature removal while deleting the app immediately removes the feature. We recommend deprecating the feature before deleting it to give users time to adjust to the update.

Deprecate a feature (recommended)

Deprecating an app feature enables you to remove an app feature while simultaneously providing users time to adjust to the updates. You can select a deprecation date that will be communicated to users through in-app banners that alert them of the deprecation. The date is solely used for communication purposes, so you must manually remove the app feature on the deprecation date.

To deprecate an app feature:

1. Open your app in the developer center.
2. Navigate to the App Versions tab and create a new version. You can skip this step if you already have a draft version.
3. In the Features tab, locate the app feature you'd like to deprecate.
4. Click the three dots next to the app feature and select Deprecate feature.
5. Check the box on the pop-up, and input a deprecation date.
6. Click Save. Once the new version is promoted to live, users will see in-app banners alerting them of the deprecation.
7. On the deprecation date, you must come back to your app and follow the steps to delete the app feature.

Un-deprecate a feature

If you deprecate an app feature but later change your mind, you can always un-deprecate it.

To un-deprecate an app feature:

1. Follow steps 1-4 above.
2. Uncheck the box to deprecate the feature and click Save.

Delete a feature

Unlike deprecating an app feature, deleting a feature immediately removes it from the version once it is promoted to live. We do not recommend this as users who rely on that feature will be blocked from accessing the app.

If you must delete an app feature, follow these steps:

1. Open your app in the developer center.
2. Navigate to the App Versions tab and create a new version. You can skip this step if you already have a draft version.
3. In the Features tab, locate the app feature you'd like to delete.
4. Click the three dots next to the app feature and select Delete feature.

Update permissions or scopes

You can always update your app's permissions or scopes by creating a new version. Even though the version is automatically pushed to users after making it live, these changes require manual user approval.

Once the new version is promoted to live, we alert users through an in-app banner of any updates to scopes or permissions. The banner contains a call to action prompting them to approve the updates. Users can still access the app without approving the updates, but it may not function properly. Your app must handle failed requests to the API with the missing permission(s) as it is unlikely that all users will immediately approve the updates.

For view apps, you can check which permissions the user has approved in the permissions property in your app's context.

permissions:{
  approvedScopes:[“board:read”],
  requiredScopes:[“board:read”,”board:write”]
}

📘

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎