Automation API

Android device automation

Configuration

Set up parameters, job variables, requirements, and sharing

Access configuration options through the Options panel on the right side of the IDE. These settings control how your automation behaves and who can access it.

Metadata

Basic information about your automation:

FieldDescriptionLimits
NameDisplay name for your automationMax 225 characters
DescriptionExplain what the automation doesMax 10,100 characters
IconVisual identifier for the automation512x512 WebP, max 2MB

Requirements

Set minimum version requirements to ensure compatibility:

Minimum Android Version

The lowest Android version your automation supports. Options range from Android 7.0 (API 24) to Android 16 (API 36).

Tip: Some features like dpad() and inputKey() require Android 13+.

Minimum App Version

The minimum version of the Xgodo app required on the device. Select from available versions sorted by version code.

Automation Parameters

Define configuration options that users can set when running your automation. These are static values set once before execution.

Example: Automation Parameters Schema
TypeScript
// Accessible via agent.arguments.automationParameters
interface AutomationParameters {
targetUsername: string; // Required string
maxRetries: number; // Number with validation
enableNotifications: boolean; // Toggle option
messageTemplate: string; // Text with default value
}

Supported Field Types

TypeValidationsUse Case
stringminLength, maxLength, pattern, enumText input, selections
numbermin, max, integerCounts, limits, delays
boolean-Feature toggles
arrayminItems, maxItems, item schemaLists of values
objectNested propertiesComplex configs
any-Flexible input
Accessing Parameters in Code
TypeScript
// Access automation parameters
const { targetUsername, maxRetries, enableNotifications } =
agent.arguments.automationParameters;
console.log("Target:", targetUsername);
console.log("Max retries:", maxRetries);
if (enableNotifications) {
await agent.actions.showNotification("Started", "Automation is running");
}

Job Variables

Define runtime variables provided for each job task. Unlike automation parameters, job variables can change between tasks in the same job.

Example: Job Variables Schema
TypeScript
// Accessible via agent.arguments.jobVariables
interface JobVariables {
email: string; // Account to process
password: string; // Credentials
proxyUrl?: string; // Optional proxy
}
Accessing Job Variables
TypeScript
// Get current task data
const task = await agent.utils.job.getCurrentTask();
if (task.success) {
const { email, password } = agent.arguments.jobVariables;
// Use the job variables
await processAccount(email, password);
// Submit results
await agent.utils.job.submitTask("success", {
email,
processedAt: new Date().toISOString()
});
// Stop the automation
stopCurrentAutomation();
}

Parameters vs Job Variables

  • Automation Parameters: Set once, same for all tasks (e.g., retry count, feature flags) in a job.
  • Job Variables: Different per task (e.g., account credentials, target data)

Sharing

Control who can access your automation. Only project owners can manage sharing settings.

Execution Access

Users who can run the automation on their devices or create a device automation job using the automation. They can see the automation in their list on DEVICES -> Automations and execute it.

Editor Access

Users who can edit the automation's code. They have full access to the IDE and can modify files.

Logs Access

Users who can view logs from automation runs. Useful for debugging and monitoring without edit access.

Managing Access

For each sharing type:

  1. Open the Sharing section in Options panel
  2. Enter a username in the input field
  3. Click Add or press Enter
  4. To remove access, click the remove button next to a user

Auto-Generated Types

When you define parameter schemas, TypeScript types are automatically generated. These provide full autocomplete and type checking in the IDE.

Generated Type Definitions
TypeScript
// Auto-generated from your schema
interface AutomationParameters {
/** Target user to process */
targetUsername: string;
/** Maximum retry attempts */
maxRetries: number;
/** Enable push notifications */
enableNotifications: boolean;
}
interface JobVariables {
/** Account email */
email: string;
/** Account password */
password: string;
}
interface AgentArguments {
automationParameters: AutomationParameters;
jobVariables: JobVariables;
}
// Available on agent object
interface Agent {
arguments: AgentArguments;
// ... other properties
}

Type Safety

The IDE will show errors if you access non-existent properties or use wrong types. This helps catch bugs before running the automation.

Next Steps