Open app to foreground

Tool Name: airdroid_business_open_app_to_foreground

Risk Level: 🟠 Medium Risk

Execution Mode: ⏳ Asynchronous

Category: Remote Commands

Quick Start (Copy & Use)

One-liner: Remotely open a specified app to the foreground on a device

What you need: DeviceId (device ID), PkgId (app package name), AppName (app display name)

Success criteria: StatusCode = 200 and ErrorMessage is an empty string; returns Pid for tracking

What to do next: Use Get an Activity Log with the Pid to poll execution status

Minimal request example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "PkgId": "com.example.app",
  "AppName": "Example App"
}

Minimal response example:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Open a company app

Scenario: Remotely open a company business app on the device

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "PkgId": "com.company.workapp",
  "AppName": "Work App"
}

Recipe 2: Open the Settings app

Scenario: Remotely open device settings for configuration

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "PkgId": "com.android.settings",
  "AppName": "Settings"
}

Recipe 3: Track operation status with Pid

Scenario: After opening the app, confirm whether the operation succeeded

1. Call Open App to Foreground to get the Pid
2. Use the Get an Activity Log tool to query status:

{
  "Pid": "1770854462319857000"
}

Polling logic:

• Progress = "Executing" → continue polling (interval 5 seconds)
• Progress = "Success" → app opened successfully
• Progress = "Failure" → check the FailReason field (app may not be installed)

1. Overview

1.1 Description

Remotely open a specified app to the foreground on a device managed by AirDroid Business. Applicable to scenarios such as remote demonstrations, app testing, or guiding users to a specific app.

1.2 When to Use

• Remote demonstration: Open a demo app on the device for product showcasing
• App testing: Remotely launch an app for functional testing
• User guidance: Guide users to enter a specific app
• Automation workflow: Launch an app as part of an automated workflow

1.3 Execution Mode & Response

This operation is asynchronous — after the command is sent, the device typically responds within seconds.

• Return value: Pid (activity log ID)
• Tracking method: Use the Get an Activity Log tool with the Pid to query execution status
• Prerequisites:
  • The device must be online to receive the command
  • The app must be installed on the device
• Typical duration: Usually completes within 2-10 seconds

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier.

• Type: string
• Format: Non-empty string
• Source:
  1. Obtained via the Get All Devices tool; use the device_id field from the response
  2. Obtained via the Get a Device by Name tool for exact name lookup
• How to fill in a GI node:
  • Constant: Enter the device ID string directly, e.g. fa6edcff65ab444e8b5e0eb08df4175d
  • Upstream reference: Map from the Get All Devices node's Devices[0].device_id field
• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`PkgId`

App package name (Android Package Name).

• Type: string
• Format: Non-empty string in Android package name format (e.g. com.example.app)
• Source:
  1. Obtained via the Get All Device Apps tool; use the pkg_id or package_name field from the response
  2. Obtained from app stores or development documentation
• How to fill in a GI node:
  • Constant: e.g. "com.example.app"
  • Upstream reference: Map from the Get All Device Apps node's app list
• Common app package name examples:
  • Settings: com.android.settings
  • Chrome: com.android.chrome
  • File Manager: com.android.documentsui
• Example:

  "com.example.app"

`AppName`

App display name.

• Type: string
• Format: Non-empty string
• Source:
  1. Obtained via the Get All Device Apps tool; use the app_name field from the response
  2. Use the user-visible name of the app
• How to fill in a GI node:
  • Constant: e.g. "Example App"
  • Upstream reference: Map from the Get All Device Apps node's app list
• Example:

  "Example App"

2.3 Parameter Combination Logic

• All three parameters are required
• PkgId and AppName should correspond to the same app
• Recommended to use Get All Device Apps to obtain accurate package names and app names

3. Outputs

3.1 Response Examples

Success response:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Parameter error response:

{
  "Pid": "",
  "StatusCode": -1,
  "ErrorMessage": "Invalid pkg_id."
}

Network error response:

{
  "Pid": "",
  "StatusCode": 500,
  "ErrorMessage": "Request timeout after 60 seconds."
}

3.2 Field Descriptions

3.3 Pid Tracking

Use the returned Pid with the Get an Activity Log tool to track execution status:

4. Examples

4.1 Basic Example: Open a company app

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "PkgId": "com.company.workapp",
  "AppName": "Work App"
}

Response:

{
  "Pid": "789012",
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Open the Settings app

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "PkgId": "com.android.settings",
  "AppName": "Settings"
}

Response:

{
  "Pid": "789013",
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Empty package name

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "PkgId": "",
  "AppName": "Example App"
}

Response:

{
  "Pid": "",
  "StatusCode": -1,
  "ErrorMessage": "Invalid pkg_id."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The agent should decide how to handle based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Tips

• Confirm device is online: Check device status before the operation to avoid sending commands to offline devices
• Confirm app is installed: Use Get All Device Apps to verify the app exists

6.2 Security Considerations

🟢 Low Risk: This operation only opens an app to the foreground and does not cause destructive impact on the device.

Operation notes:

• Can only open apps that are already installed
• If the app is not installed, the operation will fail
• Users can switch to another app at any time

6.3 Idempotency

Idempotency: Naturally idempotent.

• Opening the same app multiple times has no side effects
• If the app is already in the foreground, calling again refreshes the app
• Safe to retry

6.4 Async Operation Tracking

Use the returned Pid with Get an Activity Log to track execution status:

Polling recommendations:

• Interval: 5 seconds
• Max polling attempts: 6 (approx. 30 seconds)
• On timeout: Prompt the user to manually check device status

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Remote Demonstration Pattern

Scenario: Open a demo app on the device for product showcasing

Tool chain:

Get All Devices → Get All Device Apps → Open App to Foreground → Get an Activity Log

Steps:

1. Call Get All Devices to obtain the target device's device_id
2. Call Get All Device Apps to get the app's pkg_id and app_name
3. Call Open App to Foreground to open the app
4. Use Get an Activity Log with the Pid to confirm the operation succeeded

8.2 Batch App Launch Pattern

Scenario: Open the same app on multiple devices simultaneously

Tool chain:

Get All Devices (filter target group) → [Loop] Open App to Foreground → Get an Activity Log

Steps:

1. Call Get All Devices with Keyword={"group_name":"kiosk-devices"} to get the target device list
2. Iterate through devices and call Open App to Foreground for each
3. Collect all Pid values and use Get an Activity Log to batch-track status

8.3 Automation Workflow Pattern

Scenario: As part of an automated flow, launch the app once the device is ready

Tool chain:

[Wait for device online] → Open App to Foreground → [Subsequent operations]

Steps:

1. Monitor device online status
2. Once the device is online, call Open App to Foreground to launch the specified app
3. Continue with subsequent automated operations