Tool Name: airdroid_business_get_device_app_by_name
Risk Level: 🟢 Low Risk
Execution Mode: âš¡ Synchronous
Category: Device Management
Quick Start (Copy & Use)
Summary: Query information about a specific app on a device by its display name.
Prerequisites: DeviceId (device ID) + AppName (app display name).
Success Criteria: StatusCode == 200 and ErrorMessage is empty string, DeviceApp is a non-empty object.
What to Do Next: Use the app's pkg_id for subsequent operations (e.g., uninstall, update).
Minimal Request Example:
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "Chrome"
}
Minimal Response Example:
{
"DeviceApp": {
"app_name": "Chrome",
"device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
"pkg_id": "com.android.chrome"
},
"StatusCode": 200,
"ErrorMessage": ""
}
Recipes (Common Recipes)
Recipe 1: Check if Chrome Browser is Installed
When to use: Verify whether Chrome is installed on the device.
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "Chrome"
}
Decision logic: If DeviceApp returns an empty object {}, the app is not installed.
Recipe 2: Get System Settings App Package Name
When to use: You need the Settings app's package name for subsequent operations.
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "Settings"
}
Recipe 3: Find Bluetooth App
When to use: Check if a Bluetooth-related app exists.
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "Bluetooth"
}
1. Overview
1.1 Description
Query detailed information about a specific app on a device by its display name, including the package name (pkg_id) and device ID.
1.2 When to Use
- You know the app name and need to get its package name (pkg_id)
- Verify whether a specific app is installed on a device
- Precisely find a single app rather than getting the full app list
1.3 Execution Mode and Response
This operation is synchronous and returns results immediately.
Return data includes:
- DeviceApp: App information object (if found) or empty object (if not found)
1.4 Prerequisites
| Condition | Description | How to Check |
|---|---|---|
| Device exists | Device must be registered in AirDroid Business | Use Get All Devices to confirm |
| Accurate app name | Must use the app's exact display name (case-sensitive) | Use Get All Device Apps to view all app names |
1.5 Prerequisite Tools
| Dependency Tool | Purpose | Necessity |
|---|---|---|
| Get All Devices | Get DeviceId | If you only know the device name |
| Get a Device by Name | Get DeviceId by device name | If you only know the device name |
| Get All Device Apps | Confirm the exact app name | If unsure of the app name |
1.6 Differences from Similar Tools
| Tool Name | Use Case | Difference |
|---|---|---|
| Get a Device App by Name | Query a specific app | Exact match by name, returns a single app |
| Get All Device Apps | Get all apps | Returns full app list with pagination |
2. Inputs
2.1 Parameter List
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| DeviceId | string | Yes | - | Device unique identifier |
| AppName | string | Yes | - | App display name (case-sensitive) |
2.2 Parameter Details
`DeviceId`
Device unique identifier.
- Type: string
- Format: Non-empty string
- Source:
How to obtain:
- Via Get All Devices tool - use the device_id field from the response
- Via Get a Device by Name tool - exact name query
The device_id field from the output can be used directly as this parameter.
- Example:
"fa6edcff65ab444e8b5e0eb08df4175d"
`AppName`
The app display name to query.
- Type: string
- Format: Non-empty string, case-sensitive, must match exactly
- Notes:
- Use the app's display name, not the package name
- Case-sensitive: Chrome and chrome are different
- If unsure of the exact name, use Get All Device Apps to check first
- Example:
"Chrome"
"Bluetooth"
"Settings"
2.3 Parameter Combination Logic
- Both parameters are required
- AppName must exactly match the app's display name on the device
3. Outputs
3.1 Response Example
Success response (app found):
{
"DeviceApp": {
"app_name": "Chrome",
"device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
"pkg_id": "com.android.chrome"
},
"StatusCode": 200,
"ErrorMessage": ""
}
Success response (app not found):
{
"DeviceApp": {},
"StatusCode": 200,
"ErrorMessage": ""
}
Error response:
{
"DeviceApp": {
"device_id": "",
"pkg_id": "",
"app_name": ""
},
"StatusCode": -1,
"ErrorMessage": "device_id is required. Obtain via 'Get All Devices' or 'Get A Device By Name' tool."
}
3.2 Field Descriptions
| Field Path | Type | Description |
|---|---|---|
| StatusCode | number | Status code. 200=success, -1=parameter error, 500=network exception |
| ErrorMessage | string | Error message. Empty string on success |
| DeviceApp | object | App information object. Returns empty object {} when app is not found |
| DeviceApp.app_name | string | App display name |
| DeviceApp.pkg_id | string | App package name (Package ID), e.g., com.android.chrome |
| DeviceApp.device_id | string | Device ID |
3.3 Special Return Value Notes
- When the app is not found, DeviceApp returns an empty object {}, but StatusCode remains 200 and ErrorMessage is empty
- Agents should check whether DeviceApp is empty to determine if the app exists
4. Examples
4.1 Basic Example: Query Chrome App
Request Parameters:
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "Chrome"
}
Response:
{
"DeviceApp": {
"app_name": "Chrome",
"device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
"pkg_id": "com.android.chrome"
},
"StatusCode": 200,
"ErrorMessage": ""
}
4.2 Advanced Example: Query Bluetooth App
Request Parameters:
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "Bluetooth"
}
Response:
{
"DeviceApp": {
"app_name": "Bluetooth",
"device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
"pkg_id": "com.android.bluetooth"
},
"StatusCode": 200,
"ErrorMessage": ""
}
4.3 Error Example: Incorrect Case in App Name
Request Parameters:
{
"DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
"AppName": "chrome"
}
Response (not found, because case does not match):
{
"DeviceApp": {},
"StatusCode": 200,
"ErrorMessage": ""
}
Note: The app name chrome (lowercase) does not match the actual name Chrome (capitalized), so an empty object is returned.
5. Error Handling
5.1 AB Three-Layer Error Codes
| StatusCode | Meaning | Use Case | Agent Response |
|---|---|---|---|
| -1 | Parameter validation error | Local validation failure (missing required params, format errors) | Do not retry, fix parameters and retry |
| 200 | Business success or business error | HTTP request succeeded, check ErrorMessage | Empty ErrorMessage = success; non-empty = business error |
| 500 | Network/request exception | Timeout, connection failure, DNS resolution failure | May retry (max 2 times, 5-second interval) |
5.2 Common Errors
| StatusCode | ErrorMessage Example | Cause | Fix |
|---|---|---|---|
| -1 | device_id is required. | Device ID is empty | Use Get All Devices to get a valid device ID |
| -1 | app_name is required. | App name is empty | Provide the correct app display name |
| 200 | Empty string (DeviceApp is empty object) | App not installed or name mismatch | Check app name case, or use Get All Device Apps to confirm |
| 500 | Request timeout after 60 seconds. | Request timeout | Retry later |
5.3 Agent Self-Healing Decision Table
| StatusCode | Auto Retry | Retry Strategy | Manual Intervention Needed |
|---|---|---|---|
| -1 | No | - | Check parameters and retry |
| 200 (DeviceApp is empty) | No | - | Confirm app name is correct |
| 500 | Yes | Max 2 retries, 5-second interval | If persistent, manual |
6. Best Practices
6.1 Performance Optimization
- Exact match: Ensure AppName is completely correct (including case) to avoid unnecessary query failures
- Single app query: If you only need one app, this tool is more efficient than Get All Device Apps
- Verify name first: If unsure of the app name, use Get All Device Apps to get the exact name first
6.2 Security Considerations
🟢 Read operation: No special security requirements.
7. Related Tools
7.1 Prerequisite Tools
| Tool Name | Purpose |
|---|---|
| Get All Devices | Get DeviceId |
| Get a Device by Name | Get DeviceId by device name |
| Get All Device Apps | Confirm the exact app name |
7.2 Follow-up Tools
| Tool Name | Purpose |
|---|---|
| - | Use the obtained pkg_id for subsequent app management operations |
7.3 Similar Tool Comparison
| Tool Name | Use Case | Difference |
|---|---|---|
| Get a Device App by Name | Query a specific app | Exact match by name, returns single app |
| Get All Device Apps | Get all apps | Returns full list with pagination |
8. Tool Chains
8.1 Check if an App is Installed
Scenario: Verify whether a specific app is installed on a device.
Tool Chain:
Get a Device by Name → Get a Device App by Name
Steps:
- Call Get a Device by Name to get DeviceId
- Call Get a Device App by Name to query the app
- Check if DeviceApp is an empty object to determine if the app exists
8.2 Get App Package Name
Scenario: You know the app name and need its package name for subsequent operations.
Tool Chain:
Get a Device App by Name → [Subsequent App Management Operations]
Steps:
- Call Get a Device App by Name to get app information
- Get the package name from DeviceApp.pkg_id
- Use the package name for subsequent operations (e.g., uninstall, update)
Appendix Reference:
- Field Reference: https://www.goinsight.ai/tools/field-reference/
- Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/
Leave a Reply.