Building Configuration Files

Configuration files capture the tap/scroll/text steps Mantle Mobile will repeat inside an app during a provision. Follow the workflow below to record, label, and save a config.

Prerequisites

Device connected via USB and imported into the database
Target APK already installed on the device
No physical interaction with the device during recording

Hands off the screen

Touching the device while recording can desynchronize the task list. Use the on-screen controls inside Mantle Mobile instead.

Record a New Configuration

Path: Create > Create Config

Select Device – choose the database device you want to drive.
Select App – pick the installed app you want to configure and wait for it to launch.
Select Element – Mantle Mobile lists interactable UI elements once scanning completes. Additional actions are displayed at the bottom (See Advanced tasks):
Define Action – select Touch, Long Touch, or Send Text and click Next.
- Touch: Send a quick tap on the selected element.
- Long Touch: Send a tap and hold on the selected element.
- Send Text: Send a text value to the selected text field. (Usernames, Passwords, etc.) In this case, a URL value in the url text field for OVPN.
  In order to send text, ensure an element with send text is selected:
  
  After selecting Send Text, you can either select a Custom Variable defined for the profile set for the device you are recording with,
  or you can manually enter the text you would like to send.
- Optional Task: Select the optional checkbutton for tasks such as pop ups that do not occur on every device.
  These tasks will attempt to execute the defined amount of attempts then continue to the next task without failing.
Review & Label – label the task and click Execute & Add Task.
- This will execute the task on the device and add it to the configuration.
- After a task is executed, you will be asked if you would like to Finish or Add Another Task:
  
  Select Add Another Task to continue recording another task (Return to step 3).
  Select Finish Recording to finish recording where you will be prompted to name and save the configuration. You will then be able to view the config you've created within Assets > Configs

Use the advanced task controls for loops, delays, or conditional prompts when needed.

Advanced Tasks

Note

The below additional actions are for advanced use cases.

Press Back: Adds a task to press Android's Navigate Back button.
Press Home: Adds a task to press Android's Home button.
Scroll: Adds a task to scroll for a specified word or text value.
You will need to manually scroll on the device to find the exact value of the text you would like to scroll for, then scroll back to the top to execute the task after the correct information has been entered.
In the example below, the user scrolled to find "Security and privacy" and entered this text exactly as it appears on the device.

Once the text to scroll for has been entered, scroll back to the beginning of the screen on the device.
You can then configure the remaining scroll settings:
Scroll Direction: Vertical or Horizontal
Scroll Window: Used if there are multiple scrollable elements on the screen.
Press and Hold: Toggle if the value should be held after touching.
Short Scroll: Toggle to execute shorter scrolls.
Maximum Swipes: Select to specify the amount of scrolls before failing the task if the value cannot be found.

Re-record or Insert Tasks

From within the Configuration Editor, you can re-record and insert tasks between existing task sequences. Use this when:

A UI path changed in app updates.
A pop up is discovered that sometimes occurs between existing tasks.

To begin the re-record process select the + Execute & Start Recording Here button between the tasks you would like to insert the new tasks or where the pop up occurs.

Select the device you would like to re-record with. This needs to be a device in a state where the pop-up will occur again to ensure you can record the required tasks to solve the failing condition.

After selecting a device, the every task prior to your selected insert step will be executed. This ensures you will be recording from the correct step in the config. Do not interact with the device while these tasks are executed.

Once complete you will be presented with two options:
- Insert Tasks: The record process will begin and the tasks you record will be inserted where you selected. Reference Record a New Config.
- Insert Conditional Tasks: The screen will scan and you will select an element to define a condition that will trigger the tasks you record in the following step. These tasks will only execute if the element you selected as a condition is visible. These are useful for pop-ups that only occur occasionally as you can select the title of the pop-up as the condition for example and these tasks will only execute if that title is seen.

In this example, selecting the File System Access Changes title will ensure the tasks you record in the following steps will only execute if this pop up is seen.
The the same record process will then begin allowing you to record the necessary tasks to remove the selected pop-up. The record process will begin and the tasks you record will be inserted where you selected. Reference Record a New Config.

Edit Existing Configurations

Path: Assets > Configs

To edit a config navigate to Assets > Configs and select the Edit button for the config you would like to edit.

From here, you can edit, delete, insert, and view tasks for the selected Configuration.

Warning

Editing a configuration will cause it to fail if done incorrectly.

Selecting Edit will display a window allowing for you to edit the Label, Find Value, Action parameters etc.

After editing, select Submit.

Device-Specific Inputs

Use profiles to avoid hardcoding values.

Profiles allow for you to configure:
- Custom Variables for per profile text values such as usernames and passwords.
- Files per profile files that will only be transferred to and accesible by devices assigned the specified profile.

See Device Profiles

Best Practices

Keep labels explicit so logs are readable.
Prefer stable selectors over transient UI text.
Re-test application configurations after app version upgrades.
Keep one "known-good" baseline config for rollback.

Continue to Building Baseline Files once at least one configuration is saved.