Downloads and Installs API¶
Use the Downloads API to download and install native applications from the Apperian server onto a user’s device.
With this API, you can download and install:
- A specific native application
- All applications available to the user
- All mandatory applications available to the user
- All application updates available to the user
An application is available to the user if the application is assigned to a group to which the user belongs.
Note
After you send a request to any of the Downloads and Installs API resources, you should send a POST /catalog/applications/installed request to ensure that Apperian has an up-to-date inventory of what is installed on a user’s device. If Apperian does not have an accurate inventory of what is installed on a user’s device, certain features will not work properly; for example, Apperian will not send a push notification to the user’s device when there is an update available for an app it does not know is installed.
Apperian assigns a unique ID to each application you add. With the Publishing API, this ID is returned as an appID. With other API resources, it is returned as either an app_psk or app_id (or both). When you send a request to any REST API resources where you need to specify an ID for an application, you can send the appID, app_id, or app_psk; Apperian accepts the value of any of these parameters.
Providing the X-UDID¶
When sending a request to any of the resources in this API, you will provide the X-UDID for the user’s device onto which you want to install the application. From the X-UDID, Apperian determines the type of device (iOS, Android, etc).
For an iOS device, Apperian responds with a plist (property list) containing all the essential information for the bundled executable(s). The device can then parse the plist to download the file(s).
For an Android device, Apperian responds with download URLs that points to the APK or JAD files.
For the UDID, provide the unique Device ID assigned by Apperian to the user’s device. A Device ID associates a user with an App Catalog on a particular device. Because a user can run the App Catalog on multiple devices, there may be multiple Device IDs per user. You can view a list of all a user’s devices on the user’s Details page in the Admin Portal. You can also run the Device Details report to list Device IDs for all users in your organization. For more information on Device IDs, see Device Details. For more information on the Device Details report, see Running Reports.
Resources¶
-
GET/v1/downloads/install/applications/(application)¶ Install a Specific Native Application
Requires user context. Use session token returned from POST /catalog/authenticate.
Installs a native application onto a device. Specify the app with application. The application for each app in your organization is included as the id parameter in the data returned by the GET /applications resource.
URLs
Environment URL North America https://na01ws.apperian.com/v1/downloads/install/applications/<application> Europe https://eu01ws.apperian.eu/v1/downloads/install/applications/<application> URL Parameters
- application
- (Required) Unique ID of the app to be installed. DATA TYPE: string
- token
- (Required) User token returned by POST /catalog/authenticate. For more information, see Authentication. DATA TYPE: string
- udid
- (Required) UDID for the device. DATA TYPE: string
Header Parameter
None
Data Parameters
None
Installing onto iOS Devices
Example Request
- curl -X GET “https://na01ws.apperian.com/v1/downloads/install/applications/14080?token=AGWAvCVASEmlqAthdppnAA&udid=
- FFFFFFFF6383EEF5B7D849DE877EF31444491423”
Example Response
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>items</key> <array> <dict> <key>assets</key> <array> <dict> <key>kind</key> <string>software-package</string> <key>url</key> <string>https://qafdownload.qa.apperian.com/?download_token=6ixG5MReTVyOK6DlAY8JnQ</string> </dict> <dict> <key>kind</key> <string>full-size-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://na01ws.apperian.com/data/org_11/iphone_14080/icon_0efe88c.png</string> </dict> <dict> <key>kind</key> <string>display-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://na01ws.apperian.com/data/org_11/iphone_14080/icon_0edff80.png</string> </dict> </array> <key>metadata</key> <dict> <key>bundle-identifier</key> <string>com.apperian.Actions</string> <key>bundle-version</key> <string>2.0</string> <key>kind</key> <string>software</string> <key>subtitle</key> <string></string> <key>title</key> <string>App (2.0)</string> </dict> </dict> </array> </dict> </plist>Installing onto Android Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v1/downloads/install/applications/10016?token=MVHo-UTlR7S8o8AX5_585Q& udid=18:46:17:E0:02:E8"
Example Response
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>Redirecting...</title> <h1>Redirecting...</h1> <p>You should be redirected automatically to target URL: <a href="https://qafdownload.qa.apperian.com/? download_token=KjbREzcbTYmcxolePWn87Q">https://qafdownload.qa.apperian.com/?download_token=KjbRPWn87Q</a>. If not click the link.
-
GET/v2/downloads/install/applications/all¶ Install All Native Applications
Requires user context. Use session token returned from POST /catalog/authenticate.
Installs all applicable native applications onto the specified device. An applicable application is one that is both available to the authenticated user and is an appropriate application type for the specified device.
URLs
Environment URL North America https://na01ws.apperian.com/v2/downloads/install/applications/all Europe https://eu01ws.apperian.eu/v2/downloads/install/applications/all URL Parameters
- token
- (Required) User token returned by POST /catalog/authenticate. For more information, see Authentication. DATA TYPE: string
- udid
- (Required) UDID for the device. DATA TYPE: string
Header Parameter
None
Data Parameters
None
Installing onto iOS Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v2/downloads/install/applications/all?token=AGWAvCVASEmlqAthdppnAA& udid=FFFFFFFF6383EEF5B7D849DE877EF31444491423"
Example Response
This example installs one application only.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>items</key> <array> <dict> <key>assets</key> <array> <dict> <key>kind</key> <string>software-package</string> <key>url</key> <string>https://qafdownload.qa.apperian.com/?download_token=6ixG5MReTVyOK6DlAY8JnQ</string> </dict> <dict> <key>kind</key> <string>full-size-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://na01ws.apperian.com/data/org_11/iphone_14080/icon_0e88c5.png</string> </dict> <dict> <key>kind</key> <string>display-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://na01ws.apperian.com/data/org_11/iphone_14080/icon_0e88c5.png</string> </dict> </array> <key>metadata</key> <dict> <key>bundle-identifier</key> <string>com.apperian.Actions</string> <key>bundle-version</key> <string>2.0</string> <key>kind</key> <string>software</string> <key>subtitle</key> <string></string> <key>title</key> <string>App (2.0)</string> </dict> </dict> </array> </dict> </plist>Installing onto Android Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v1/downloads/install/applications/all?token=MVHo-UTlR7S8o8AX5_585Q& udid=18:46:17:E0:02:E8"
Example Response
This example installs one application only.
{ "applications": [ { "operating_system": 102, "url_scheme": "", "id": "1a6JFJL5Ta6NqqA1EXw-rA", "is_adhoc": false, "is_hybrid": false, "required_by": "3099-12-31T00:00:00+00:00", "is_app_catalog": false, "latest_version_id": "1a6JFJL5Ta6NqqA1EXw-rA", "version": { "version_note": "asdf", "version_num": "2.5.2", "release_date": "2016-03-25T17:40:27.631494+00:00", "latest_install_file_id": "6c2SvtZqQlucRLZgBOla6w", "required": false, "required_by": "9999-12-31T23:59:59.999999", "app_id": "1a6JFJL5Ta6NqqA1EXw-rA", "wrap_status": 0, "sign_status": 0, "kryptowire_verification_status": 0, "notify_users": false, "binary_version": "ShapeWriter 3.0.9", "app_name": Actions, "icon_path": "org_11/android_81/folder_a1_3d.png", "short_description": "Manage your TO DO list", "long_description": "Come on. Get organized today with the Actions app", "author": "Example Company", "id": "1a6JFJL5Ta6NqqA1EXw-rA", "custom_metadata": null, "min_os_version": "3", "form_factor": 3, "install_file": { "apperian_wrapper_version": null, "app_id": "1a6JFJL5Ta6NqqA1EXw-rA", "id": "6c2SvtZqQlucRLZgBOla6w", "kryptowire_verification_id": null, "version_id": "1a6JFJL5Ta6NqqA1EXw-rA", "size": 2295504, "expires": "9999-12-31T23:59:59.999999", "mime": "application/vnd.android.package-archive", "path": "org_11/android_81/Actions.apk", "created": "2016-03-25T17:40:14.875549+00:00", "checksum": "e16f266dcdbf600acd53f7a2bf55babe1d36c896a7c8e4c687a2d012bf6dd297", "sign_credentials_id": null, "action": "upload", "binary_metadata": null } }, "reviews_enabled": true, "type": 3, "status": 1, "sort_weight": 1000, "no_auth_delivery_enabled": true, "add_to_start": false, "bundle_id": "com.example.actions", "banner_image_url": null, "install_uri": "https://na01ws.apperian.com/downloads/install/applications/81? token=QRNyq3ctRM-RsGaaUs22aQ&udid=14:7D:C5:B8:52:0B", "required": false, "push_enabled": false } ] }
-
GET/v2/downloads/mandatory/applications/all¶ Install All Mandatory Applications
Requires user context. Use token returned from POST /catalog/authenticate.
Installs all mandatory native apps that are available to the authenticated user onto the specified device. A user cannot continue to use the App Catalog until the user installs all mandatory apps.
Note
You can mark an app as mandatory when you add or edit it through the Admin Portal. Currently, you cannot mark an app as mandatory when you add it via the Publishing API. For instructions on adding applications through the Admin Portal and marking them as mandatory, see the Apperian Help Center.
URLs
Environment URL North America https://na01ws.apperian.com/v2/downloads/mandatory/applications/all Europe https://eu01ws.apperian.eu/v2/downloads/mandatory/applications/all URL Parameters
- token
- (Required) User token returned by POST /catalog/authenticate. For more information, see Authentication. DATA TYPE: string
- udid
- (Required) UDID for the device. DATA TYPE: string
Header Parameter
None
Data Parameters
None
Installing onto iOS Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v2/downloads/mandatory/applications/all?token=AGWAvCVASEmlqAthdppnAA& udid=FFFFFFFF6383EEF5B7D849DE877EF31444491423"
Example Response
In this example, the plist file does not list any items because the user does not have any mandatory apps to install. If the user did have mandatory apps, the response would look similar to the example shown for the GET /downloads/update/applications/all resource.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>items</key> <array> </array> </dict> </plist>
Installing onto Android Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v1/downloads/mandatory/applications/all?token=MVHo-UTlR7S8o8AX5_585Q& udid=18:46:17:E0:02:E8"
Example Response
In this example, the response indicates that there are no applications to install because the user does not have any mandatory apps to install. If the user did have mandatory apps, the response would look similar to the example shown for the GET /downloads/update/applications/all resource.
{ "error": { "code": 20, "message": "No applications to install on device", "guid": "736565c7-5c88-4583-b0e4-e14c9d4a437d", "error_details": null } }
-
GET/v2/downloads/update/applications/all¶ Install All Application Updates
Requires user context. Use session token returned from POST /catalog/authenticate.
Installs updates for all applicable native applications on the device. An applicable application is one that is both an appropriate application type for the device and an application that the user has previously installed on the device.
URLs
Environment URL North America https://na01ws.apperian.com/v2/downloads/update/applications/all Europe https://eu01ws.apperian.eu/v2/downloads/update/applications/all URL Parameters
- token
- (Required) User token returned by POST /catalog/authenticate. For more information, see Authentication. DATA TYPE: string
- udid
- (Required) UDID for the device. DATA TYPE: string
Header Parameter
None
Data Parameters
None
Installing onto iOS Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v2/downloads/update/applications/all?token=AGWAvCVASEmlqAthdppnAA& udid=FFFFFFFF6383EEF5B7D849DE877EF31444491423"
Example Response
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>items</key> <array> <dict> <key>assets</key> <array> <dict> <key>kind</key> <string>software-package</string> <key>url</key> <string> https://qafdownload.qa.apperian.com/?download_token=6ixG5MReTVyOK6DlAY8JnQ </string> </dict> <dict> <key>kind</key> <string>full-size-image</string> <key>needs-shine</key> <true/> <key>url</key> <string> https://na01ws.apperian.com/data/org_1111/iphone_14080/icon.png </string> </dict> <dict> <key>kind</key> <string>display-image</string> <key>needs-shine</key> <true/> <key>url</key> <string> https://na01ws.apperian.com/data/org_1111/iphone_14080/icon.png </string> </dict> </array> <key>metadata</key> <dict> <key>bundle-identifier</key> <string>com.apperian.Actions</string> <key>bundle-version</key> <string>2.0</string> <key>kind</key> <string>software</string> <key>subtitle</key> <string></string> <key>title</key> <string>App (2.0)</string> </dict> </dict> </array> </dict> </plist>Installing onto Android Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v2/downloads/update/applications/all?token=MVHo-UTlR7S8o8AX5_585Q& udid=18:46:17:E0:02:E8"
Example Response
{ "applications": [ { "operating_system": 102, "url_scheme": "", "id": "xKPzL5lY2vN_WuI0EyxcVQ", "is_adhoc": false, "is_hybrid": false, "required_by": "9999-12-31T23:59:59.999999", "is_app_catalog": false, "latest_version_id": "vL7tb9OSM4rokuECMfN4Sw", "version": { "version_note": "asdf", "version_num": "2.5.2", "latest_install_file_id": "KqY780ZNWxkjdi61HkslGg", "app_id": "xKPzL5lY2vN_WuI0EyxcVQ", "release_date": "2016-03-25T17:58:49.474231+00:00", "required": false, "required_by": "9999-12-31T23:59:59.999999", "id": "vL7tb9OSM4rokuECMfN4Sw", "wrap_status": 0, "sign_status": 0, "kryptowire_verification_status": 0, "notify_users": true, "app_name": "Actions", "icon_path": "org_11/android_81/folder_a1_3d.png", "short_description": "Manage Your TO DO List", "long_description": "Come on. Get organized today!", "custom_metadata": null, "min_os_version": "3", "form_factor": 3, "install_file": { "apperian_wrapper_version": null, "kryptowire_verification_id": null, "app_id": "xKPzL5lY2vN_WuI0EyxcVQ", "size": 2295504, "id": "KqY780ZNWxkjdi61HkslGg", "expires": "9999-12-31T23:59:59.999999", "mime": "application/vnd.android.package-archive", "path": "org_11/android_81/Actions.apk", "created": "2016-03-25T17:58:45.048234+00:00", "checksum": "e16f266dcdbf600acd53f7a2bf55babe1d36c896a7c8e4c687a2d012bf6dd297", "sign_credentials_id": null, "action": "upload", "binary_metadata": null } }, "reviews_enabled": true, "type": 3, "status": 1, "sort_weight": 1000, "no_auth_delivery_enabled": true, "add_to_start": false, "bundle_id": "com.example.actions", "banner_image_url": null, "install_uri": "https://na01ws.apperian.com/downloads/install/applications/81? token=QRNyq3ctRM-RsGaaUs22aQ&udid=14:7D:C5:B8:52:0B", "required": false, "push_enabled": false } ] }
-
GET/v1/downloads/install/versions/(version)¶ Install a Specific Version of a Native Application
Requires user context. Use session token returned from POST /catalog/authenticate.
Installs a specific version of a native application onto a device. To specify the version you want to install, include the
version(the version’s unique indentifier) at the end of the resource URL. Theversionfor each app in your organization is the id included in the data returned by the GET /applications resource.URLs
Environment URL North America https://na01ws.apperian.com/v1/downloads/install/versions/<version> Europe https://eu01ws.apperian.eu/v1/downloads/install/versions/<version> URL Parameters
- version
- (Required) Unique ID of the specific version of the app to be installed. DATA TYPE: integer
- token
- (Required) User token returned by POST /catalog/authenticate. For more information, see Authentication. DATA TYPE: string
- udid
- (Required) UDID for the device. DATA TYPE: string
Header Parameter
None
Data Parameters
None
Installing onto iOS Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v1/downloads/install/versions/14080?token=AGWAvCVASEmlqAthdppnAA&udid= FFFFFFFF6383EEF5B7D849DE877EF31444491423"
Example Response
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>items</key> <array> <dict> <key>assets</key> <array> <dict> <key>kind</key> <string>software-package</string> <key>url</key> <string>https://qafdownload.qa.apperian.com/?download_token=6ixG5MReTVyOK6DlAY8JnQ</string> </dict> <dict> <key>kind</key> <string>full-size-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://na01ws.apperian.com/data/org_11/iphone_14080/icon_0efe88c.png</string> </dict> <dict> <key>kind</key> <string>display-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://na01ws.apperian.com/data/org_11/iphone_14080/icon_0edff80.png</string> </dict> </array> <key>metadata</key> <dict> <key>bundle-identifier</key> <string>com.apperian.Actions</string> <key>bundle-version</key> <string>2.0</string> <key>kind</key> <string>software</string> <key>subtitle</key> <string></string> <key>title</key> <string>App (2.0)</string> </dict> </dict> </array> </dict> </plist>Installing onto Android Devices
Example Request
curl -X GET "https://na01ws.apperian.com/v1/downloads/install/versions/10016?token=MVHo-UTlR7S8o8AX5_585Q& udid=18:46:17:E0:02:E8"
Example Response
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>Redirecting...</title> <h1>Redirecting...</h1> <p>You should be redirected automatically to target URL: <a href="https://qafdownload.qa.apperian.com/? download_token=KjbREzcbTYmcxolePWn87Q">https://qafdownload.qa.apperian.com/?download_token=KjbRPWn87Q</a>. If not click the link.