Troubleshooting

This page provides information to help diagnose and fix issues that may arise for your end users working with the App Catalog, or you and other Digital.ai App Management administrators working in the Admin Portal.

Issues for App Catalog Users

Before you Begin

If you are troubleshooting an App Catalog issue with a user or contacting Customer Support for assistance, it is helpful to know the version number of the catalog currently installed on the device. A user can check this by tapping on the Profile button at the top of the catalog to display the side menu; the version number is listed next to the organization name.

Once you know the version of the user's catalog, you can compare it with the version number of the catalog currently uploaded to your organization. Find the version number in the Admin Portal by hovering over the catalog icon on the Applications page.

Issue: User sees an Unable to Download App message when trying to install an app or an app update from the App Catalog.

Check for these possible issues:

• Entitlement Mismatch: There may be a mismatch between entitlements in the app and entitlements in the distribution provisioning profile with which the app was signed. It is important that you sign with a distribution provisioning profile that has entitlements that match the entitlements built into the app. If the app includes app extensions, each of those extensions must be signed with a different provisioning profile that has the correct entitlements. You can check for this by re-signing the app with the Admin Portal using "New Credentials." When you sign with new credentials, Digital.ai App Management compares the entitlements in the app and the provisioning profile(s) and highlight any issues. For instructions, see Sign an App (Admin Portal).
• Certificate/Provisioning Profile Mismatch: The app may be signed with a mismatched distribution certificate and distribution provisioning profile. When you upload signing credentials to Digital.ai App Management, you upload the .p12 file for your organization's enterprise distribution certificate and a distribution provisioning profile. When the provisioning profile was created in the Apple Developer Portal, it was associated with an distribution certificate. If you sign the app through the Admin Portal with a certificate that is not the one associated with the provisioning profile, then the user will not be able to install the app. Try re-signing the app with your enterprise distribution certificate and a matching distribution provisioning profile.

As a best practice, you should have only one enterprise distribution certificate for your organization and all provisioning profiles should be associated with that certificate. This avoids the situation where an app is signed with a certificate and provisioning profile that do not match. If you do create more than one certificate in the Apple Developer Portal (for example, when you create a new certificate because the current one is due to expire), give the certificates unique names so they can be easily distinguished. :::

• Ad Hoc Provisioning Profile: The app may be signed with an Ad Hoc distribution provisioning profile and the user may be trying to install it on a device that is not provisioned via that Ad Hoc profile. When an app is distributed "Ad Hoc," the app is listed in the App Catalog for all users with group access to the app—regardless of whether the user's device is in the list of provisioned UDIDs. If the user's device is not provisioned, however, when the user clicks the Install button, the app will download and start to install, but the operating system will terminate the installation and display the message to the left. This scenario is less likely since Ad Hoc certificates are not used when distributing apps throughout an enterprise, but the app may have been signed when it was first distributed to a limited user group (such as during a test phase) and has not yet been re-signed.
• App Store Provisioning Profile: The app may be signed with an App Store distribution provisioning profile. Applications built or signed with an App Store distribution provisioning profile will upload successfully to Digital.ai App Management, but will not install on a device until they are resigned with either an Ad Hoc or In House distribution provisioning profile. When the user taps the Install button, the app will download and start to install, but the operating system will terminate the installation and display the message to the left.
• Wrong Form Factor or OS: In Digital.ai App Management, the app may be set to run on a certain form factor only, or the user is on a device running an operating system that does not meet minimum OS requirements for the app. These conditions will block an app from being displayed in the App Catalog, but if the user tries to install via a Direct Install link, the user will see the "Unable to Download App" message.
• Different Distribution Provisioning Profile: The user is trying to install an update of an app that is signed with a different provisioning profile than the currently installed version. iOS will not overwrite an app with an app that has a different provisioning profile. This issue occurs when a provisioning profile has expired and an administrator in the Apple Developer Portal creates a new provisioning profile for the app rather than edits the expired profile to generate a new version. For instructions, see Editing a Distribution Provisioning Profile.

Issue: Installing an update from the App Catalog installs a second app rather than updating the existing app.

Check that the app was re-signed with the same signing credentials used to sign it previously. If you re-sign an app with different signing credentials, then the device will see it as a different app and install a new app rather than update the app that is already installed.

With iOS apps, note that if the App ID in the distribution provisioning profile you use for signing does not match the bundle ID of the app, Digital.ai App Management automatically modifies the bundle ID in the app to match the App ID in the provisioning profile. If you are not sure if you are signing with the correct provisioning profile, you can "Sign with New Credentials" so that Digital.ai App Management will highlight any App ID/bundle ID mismatches.

The following example shows a mismatch between the app's bundle ID and the provisioning profile App ID. If this app is signed with this provisioning profile, Digital.ai App Management will modify the app's bundle ID to match the App ID from the profile. While this is a convenient feature, it can cause a problem if the app had already been distributed to users with the original bundle ID. When a user installs the update that has a different bundle ID, iOS will install this update as a new app on the device.

Issue: App crashes when the user tries to run it.

Expired Signing Credentials

The app may be expired. When an app "expires," it means that the credentials used to sign the app have expired. This could mean something different depending on the type of app.

• With Android apps, an "expired app" means that the certificate used to sign the app has expired. With Android apps, this is rare since the the certificate's private key typically has a validity period of 25 years or more to ensure that an app can be used and updated for the lifespan of the app. Therefore, you will not typically need to re-sign an Android app because it has expired. When an app's certificate expires, the app will fail to run on the device.
• With iOS apps, an "expired app" means that either the certificate or the distribution provisioning profile used to sign the app has expired. If the app includes extensions and is therefore signed with multiple provisioning profiles, Digital.ai App Management bases the expiration date on the date of the certificate or provisioning profile due to expire the soonest. Apple distribution certificates expire after one to two years, and distribution provisioning profiles expire after one year. When an iOS app is signed with an expired certificate or profile, users cannot install the app from an App Catalog or run the app if it was already installed.

When an app expires, you need to re-sign it and deploy the newly signed version of the app to your users. When you re-sign an iOS app through Digital.ai App Management, you can select the "Notify users about the update" option to send a Push Notification to the devices of all users who have already installed the app.

For instructions on checking the expiration date of certificate used to sign an app, see Signing Prerequisites.

Problem with the Application

If the app's signing credentials have not expired, then there may be a problem with the application itself. When an application crashes, a crash report is stored on the device. This crash report is a useful tool for debugging issues with the application.

To collect a crash report from a device, ask the App Catalog user to follow these instructions:

1. Open Settings.
2. Go to Privacy->Diagnostics & Usage.
3. Tap Diagnostics & Usage Data.
4. Locate the report for the crashed app. The reports will be named in this format: <AppName>_<DateTime>_<DeviceName>
5. Tap the desired report to display it.
6. Using the text selection UI, select the entire text of the report. Once the text is selected, tap Copy.
7. Paste the copied text into an email and send it to your Digital.ai App Management administrator.

If you apply the Collect Crash Reports policy to your apps, you won't have to worry about collecting reports from your users: Digital.ai App Management will do it for you. When an app with the Collect Crash Reports policy crashes, Digital.ai App Management collects the crash report from the device. (With Android, this happens at the time of the crash; with iOS, it happens the next time the app is opened.) Digital.ai App Management lists all the reports it has collected for an app on the Crash Reports tab of the app’s details page. From that list, you can view reports and export reports to send to developers for further analysis. For instructions, see Apply Policies to an App. :::

For help understanding and analyzing iOS application crash reports, see the iOS Developer Library.

Issue: User sees an "Untrusted Enterprise Developer" message when they try to run an app installed from the App Catalog.

This is a standard iOS alert and does not indicate an issue. Before iOS runs any app that was not installed through the Apple App Store, it requires confirmation that a user trusts the source—the “Enterprise Developer”—of the app. The source of an app is determined by the enterprise distribution certificate used to sign the app. Once a user has trusted an Enterprise Developer, the user can then run any app that was signed with the same certificate—without having to trust the developer again.

For instruction on the steps required to trust an enterprise developer, see Apple's support article: Install custom enterprise apps on iOS

Because the App Catalog is typically the first of your apps that your users will download to their devices, Digital.ai App Management displays a note on the App Catalog download page. This note provides instructions for trusting the enterprise developer and displays an animated image that illustrates the steps.

As a best practice you should sign the App Catalog and all of the apps distributed through it using the same enterprise distribution certificate. Things will still work when apps are signed with different certs, but it adds extra steps for end users since they will need to trust multiple Enterprise Developers. :::

Issue: The spinner does not display when an app with policies is launched and I am not sure if policies are being evaluated.

By default, Digital.ai App Management evaluates most application's policies whenever the user opens the app, brings it to the foreground, or returns to it from a locked screen. (With some policies, Digital.ai App Management does not count multiple launches within a minute. These exceptions are described in the policy descriptions in Application Policies).

When evaluating policies, Digital.ai App Management blurs the app screen and displays a spinner. To the user, this looks like part of the process of starting the app, and it is typically quite fast—sometimes the user will not even notice the spinner. Evaluation speed, however, can be influenced by the device's network connection speed.

If you are never seeing the spinner and are not sure if policies are being evaluated, you should check the Policy Evaluation Frequency for your organization. This setting can be customized from the Admin Portal Settings page under Policy Evaluation Frequency. If the policy evaluation frequency is changed to anything but Always and a user launches an app or brings it to the foreground before the set time has passed, then the app will not be evaluated and there will be no spinning wheel. Once the amount of time you set has passed, the app will again be evaluated when it is launched or brought to the foreground. To ensure an app is evaluated and a spinning wheel displays every time an app with policies is launched or brought to the foreground, make sure that Always is selected.

For instructions on checking the Policy Evaluation Frequency, see Manage Policy Settings.

Issue: User is not able to see an app listed in the App Catalog.

There are a few reasons why an app may not show up in the App Catalog:

• App is disabled: If you add a new application to the Admin Portal from the Add New Application page and the Enabled checkbox is not checked, the newly added application will remain disabled until you enable it. This may also occur if you sign the app from the Signing tab on the Admin Portal without selecting the Enable app checkbox to automatically enable the app to users after it is signed. You can enable the app from the Edit Applicationpage at any time. For instructions, see Disable or Enable an Application.
• User does not have permission to access the app: The user may not belong to a group to which the app is assigned. To edit a group to modify its membership, see Edit a Group.
• User's device does not meet system requirements: If any of the following conditions are true, then the app will not display in the catalog:
  • The user is on a device of a different platform type than the app. For example, the user is on an iPhone and the app is an Android app. If possible, ensure that you have versions of a application for all device platforms you support within your organization.
  • The user is on a device running an operating system that does not meet minimum OS requirements for the app. If possible, the user should upgrade to a more recent version of the OS.
  • The app is an Android multidex app and the user is on a device running Android 4.x. Digital.ai App Management supports multidex apps on Android 5.x and higher only.

Issue: User sees the App Catalog listed as an app in the App Catalog.

If there is more than one App Catalog of the same OS type uploaded to the same organization and both are enabled, then the App Catalog that was uploaded second will be seen as a normal application and will be displayed in the All tab of the App Catalog.

To remove the second App Catalog you can either delete or disable the app. You can delete the app by clicking the Delete button under the specific app on the Applications page of the Admin Portal. You can disable the app by clicking the Edit button under the specific app on the Applications page of the Admin Portal, expanding the Application section, and unchecking the box labeled Enable.

Issue: Users see a "No Featured Apps" message on the Popular page of the App Catalog.

At the top of the Popular apps page in the App Catalog, users can browse a collection of featured applications selected by you or another administrator. If you don't select any applications to feature in the App Catalog, users will see a "No Features Apps" message at the top of the page.

For instructions on featuring apps in the App Catalog, see Select Featured Apps for the App Catalog.

Issue: iOS device user is not receiving push notifications

Check for the following:

• Is Push Notification enabled for the App Catalog and is a valid Production Push SSL Certificate uploaded to Digital.ai App Management? For more information, see Enable Push Notification for an iOS App Catalog.
• Was the Provisioning Profile for the App Catalog created after the Production Push SSL Certificate? Steps must be followed as listed in iOS Signing Requirements.
• Is the App Catalog bundled with an Ad Hoc distribution provisioning profile? If so, push notifications are not supported. For a description of the difference between Ad Hoc and In House distribution, see iOS Signing Requirements.
• Has the App Catalog user already logged in to the App Catalog and installed the app that was updated? Users receive push notifications only for updates of apps that they already installed.
• Did the user choose to allow the App Catalog to send notifications? When a user first launches the App Catalog, he/she is prompted to allow the app to send notifications. Unless the user taps Allow, the user will not receive any push notifications from the App Catalog.
• (With application update notifications) Did the VAR::COMPANYNAME App Management administrator specify that users should be notified about the update? This can be done when uploading a new version on the Edit Application page or when signing a new version on the Signing tab. If a new version of an application needs to be signed before it is distributed and it is being signed through Digital.ai App Management, then typically an administrator _will not choose to notify users when editing the app but will choose to notify users when signing the app.

Issue: Android device user is not receiving push notifications

Check for the following:

• Is Push Notification enabled for the App Catalog? For more information, see Enable Push Notification for an iOS App Catalog.
• Has the App Catalog user already logged in to the App Catalog and installed the app? Users receive push notifications only for updates of apps that they already installed.
• Did the user choose to allow the App Catalog to send notifications? Unlike on iOS where the user has to choose to allow the App Catalog to send notifications, on Android this happens by default. The user can, however, choose to hide notifications on the device or block them for a specific app. If a user is not seeing push notifications on an Android device, ask the user to check the notification settings.
• (With application update notifications) Did the VAR::COMPANYNAME App Management administrator specify that users should be notified about the update? This can be done when uploading a new version on the Edit Application page or when signing a new version on the Signing tab. If a new version of an application needs to be signed before it is distributed and it is being signed through Digital.ai App Management, then typically the administrator _will not choose to notify users when editing the app but will choose to notify users when signing the app.

Issues for Administrators

Issue: AppID: The team identifier doesn't match the value in the embedded.mobileprovision. This app may not install.

The team Identifier in the application you are attempting to upload does not match the team identifier defined in the embedded``.mobileprovision file bundled with the app. Digital.ai App Management will still sign the application, but it is unlikely that users will be able to install the application on their devices from the App Catalog.

To solve this issue, you should use Digital.ai App Management to re-sign the application. When you re-sign the application, Digital.ai App Management will automatically modify both the team ID and bundle ID of the app to match the App ID associated with the distribution provisioning profile used to sign the app.

Re-signing the app will fix a mismatch between the team ID/bundle ID and the provisioning profile, but if there are entitlements in the app that do not match the entitlements in the provisioning profile, the app will not install on a user's device. You can check for this by re-signing the app with in the Admin Portal using new credentials. When you sign with new credentials, Digital.ai App Management compares the entitlements in the app and the provisioning profile(s) and highlights any issues.

For instructions, see Sign an App (Admin Portal). For more information on entitlements, see App Extensions and Entitlements. :::

Issue: Distribution: development profile found

The application you are attempting to upload to the Admin Portal is signed with a development provisioning profile instead of a distribution provisioning profile. An app signed with a development provisioning profile can still be uploaded to Digital.ai App Management without issue, but should be signed with a distribution certificate and distribution provisioning profile before it is distributed to your users.

For information on the difference between development and distribution provisioning profiles, see iOS Signing Requirements.

Issue: "App type" File: this application is expired

The certificate used to sign the application you are attempting to upload is expired. An expired application can still be uploaded to Digital.ai App Management with no issue, but before it can be distributed to your users, the app must be re-signed with a valid distribution certificate and distribution provisioning profile.

For instructions on generating distribution certificates and provisioning profiles, see iOS Signing Requirements. For instructions on signing an app through Digital.ai App Management, see Sign an App (Admin Portal).

Issue: When uploading a native application to the Admin Portal, the app is not associated with an app icon.

Typically, a native application has an icon image file bundled with the application binary. When you upload a native app to Digital.ai App Management, that image file is added as the Icon Image for that app, and it will appear in both the Admin Portal Applications list and app lists in the App Catalog.

If you upload a native app and nothing is uploaded for the Icon Image, then it means the app was built without an icon or there is something wrong with the icon it was built with (for example, the size or format may be incompatible). If this is the case, you need to ask the app developer for a new version of the app that includes a valid icon. Once you get this version, attempt to add the app to Digital.ai App Management again.

Even when an icon is extracted from the app, you can upload a different icon to Digital.ai App Management. The icon you upload will be displayed in the Admin Portal and the App Catalog, but the icon bundled with the application file will still be used to display the app on the Home screen of the user's mobile device once the app is installed.

Any icon you upload manually must be in PNG format and should be at least 114 x 114 pixels. Be sure the image was saved in PNG format and not saved in another format and then simply renamed with a .png extension.

If you want to change the icon of a previously added application, click the Edit button under the app and expand the Icon Image section of the page.

Issue: Distribution: not enterprise and no provisioned devices

The application you are attempting to upload to the Admin Portal is signed with an App Store distribution provisioning profile instead of an Ad Hoc or In House distribution provisioning profile. An app signed with an App Store distribution provisioning profile can still be uploaded to Digital.ai App Management without issue, but should be signed with a distribution certificate and distribution provisioning profile before it is distributed to your users. Any app signed with an App Store distribution provisioning profile will not install on a device until it is resigned with a correct distribution provisioning profile.

For more information on creating the correct distribution provisioning profile for an iOS application, see Distribution Provisioning Profiles.

Signing Apps with Digital.ai App Management

For instructions on signing an app through the Admin portal, see Sign an App (Admin Portal).

Issue: Administrator receives an App Expiration Notice email indicating that an app(s) signing certificate is due to expire in X days.

Digital.ai App Management sends an email to the Administrators in your organization to warn that an iOS app's Apple signing certificate (distribution certificate) is due to expire. Notification emails are sent 60 days before an app expires, 45 days before, 30 days before, and then every day until the app either expires or is re-signed with current signing credentials.

When an application's signing certificate expires, the app is disabled. Users cannot install disabled apps from an App Catalog, and cannot run a disabled app that was already installed.

To avoid any loss of service for an app's users, you should be sure to re-sign the app and redistribute it to users BEFORE the certificate expires. Follow these steps:

1. In the Apple Developer Portal, log in with your Enterprise account and create a new distribution certificate. You cannot renew or extend the life of an existing certificate that is due to expire. For instructions on creating a certificate, see Manage Distribution Certificates.
2. In the Apple Developer Portal, edit any distribution provisioning profiles that are associated with the certificate that is due to expire, and then generate and download the updated .mobileprovision files. For instructions, see Edit a Distribution Certificate.
3. In Digital.ai App Management, upload the new certificate and new provisioning profiles and then re-sign apps that are currently signed with those credentials. When you re-sign an app, it will create a new version of that app that will need to be distributed to your users.

Android applications don't typically expire because they are signed with certificates with long life spans (25+ years). :::

Issue: My certificate is expired and I cannot sign applications with it.

iOS distribution certificates expire after one or two years. When a certificate has expired, you can no longer sign any apps with it.

For instructions on creating a new certificate, see Manage Distribution Certificates.

You should try to re-sign and redistribute an app before its associated certificate expires. See the procedure in the previous section.

Issue: When trying to sign an application, the entitlements of the app do not match the entitlements of the distribution provisioning profile.

When you sign an app, you need to sign it with a distribution provisioning profile that has entitlements (app services) that match the entitlements (capabilities) built into the app. If the entitlements don't match, users will not be able to install the app on their devices. If the app includes app extensions, each extension must be signed with a different provisioning profile that has the correct entitlements.

It is best practice to obtain the list of an app's entitlements from the app developer before attempting to sign the application so that you can ensure that you have a suitable distribution provisioning profile(s), but if you don't have this information, Digital.ai App Management can help. When you upload a provisioning profile in the Sign with New Credentials section of the Signing tab, Digital.ai App Management compares the entitlements in the profile with the app/extension. If the entitlements don't match, Digital.ai App Management warns you and clearly identifies what doesn't match. Once you have this level of information, you can follow up on your own or with the appropriate member of your team to generate the necessary provisioning profile(s) from the Apple Dev Portal.

For more information on entitlements, see App Extensions and Entitlements.

For instructions on signing with new credentials, see Sign an App (Admin Portal).

Issue: The app does not have a ProvisionedDevices (ad hoc) or ProvisionsAllDevices (enterprise) key

You attempted to sign an application with an App Store distribution provisioning profile. Applications in Digital.ai App Management must be signed with either an Ad Hoc or In House distribution provisioning profile. Signing with an App Store distribution provisioning profile will fail and Digital.ai App Management will display the message to the left.

For more information on signing requirements, see Signing Prerequisites.

For more information on creating the correct distribution provisioning profile for an iOS application, see Manage Distribution Provisioning Profiles.

Signing Apps with the Signing Package

For instructions on downloading a signing package to sign an app outside of Digital.ai App Management, see Sign an App (Signing Package).

Signing iOS Apps with the signApp Script

The signApp script returns an error when signing an iOS app.

Check for the following issues:

• The distribution certificate and private key are not installed properly in your Login Keychain. Use Keychain Access to verify that both the certificate and private key are listed in your Login Keychain.
• The app contains extensions and you are signing the app with multiple distribution provisioning profiles, but you edited the signables_manifest.txt file incorrectly or did not edit it at all. See step 3 in the procedure above.
• You have more than one distribution certificate with the same name in your Keychain. The certificate name that you specify when you execute the script must be unique across all Keychains. For example, you cannot have a certificate with the same name in both the Login and System Keychains. If you have the certificate in more than one Keychain, you should delete it from all Keychains other than the Login Keychain, but first you should make sure that there are no other apps using the certificate in the other Keychain. |

Signing Apps through the API

For a list of messages and errors related to the Signing API, see Signing Status Messages.