UI Watcher¶
The watcher is used to monitor real-time changes in the user interface. When predefined conditions are met, it automatically performs specified actions such as clicking elements, pressing keys, or counting occurrences. You can think of this functionality as the underlying implementation of tools like Liaotiaotiao or similar features that automatically skip ads. Since this feature automatically performs clicks or key presses, unintended operations may occur when manual intervention is required. Please use with caution.
Tip
Under normal circumstances, watchers and event registrations should be set up at the beginning of a script and generally not modified during execution.
Enable Watcher¶
The following interface enables the UI watcher. By default, the watcher is disabled.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.set_watcher_loop_enabled(True)
Check If Watcher Is Enabled¶
Use the following interface to check whether the UI watcher is currently enabled.
d.get_watcher_loop_enabled()
Disable Watcher¶
Disables the watcher loop, stopping automatic processing of registered events such as clicks.
d.set_watcher_loop_enabled(False)
Attention
Registering too many watcher events may impact system performance or responsiveness.
Remove All Watchers¶
Removes all previously applied watcher events. This clears rules left by previous or abnormally terminated scripts. It’s recommended to call this method at the start of each script to prevent previously registered events from interfering with current operations.
d.remove_all_watchers()
Register Click Event¶
A click event automatically triggers a click (or other action) when a matching selector appears on the screen. For example, it can automatically bypass popups such as usage agreements or update prompts, or perform automatic clicks on specific screens.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.register_click_target_selector_watcher("ClickAcceptWhenShowAggrement", [Selector(textContains="用户协议")], Selector(textContains="同意", clickable=True))
Hint
The second parameter supports multiple Selectors; all conditions must be satisfied for the event to trigger.
After registering the above event, whenever an interface containing the text “用户协议” (User Agreement) appears, the system will automatically click the “同意” (Agree) button.
Register Key Press Event¶
A key press event automatically simulates a key press when a matching selector appears on the screen—for example, automatically pressing the back button to avoid entering certain interfaces. Note that similar behavior can also be achieved using click events.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.register_press_key_watcher("PressBackWhenHomePageShows", [Selector(textContains="个人中心")], Keys.KEY_HOME)
Hint
The second parameter supports multiple Selectors; all conditions must be satisfied for the event to trigger.
After registering the above event, whenever an interface containing the text “个人中心” (Personal Center) appears, the device will automatically press the HOME key.
Register Counting Event¶
A counting event increments a counter when a matching selector appears on the screen. This is useful for tracking transient but important information—such as whether a particular screen appeared, or how many times it appeared.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.register_none_op_watcher("RecordElementAppearTimes", [Selector(textContains="好的")])
Hint
The second parameter supports multiple Selectors; all conditions must be satisfied for the event to trigger.
The above event counts how many times an interface containing the text “好的” (OK) appears. Use the following interface to retrieve the number of times the watcher has been triggered:
d.get_watcher_triggered_count("RecordElementAppearTimes")
Enable Event¶
After registering an event, you must explicitly enable it so that it becomes active within the watcher loop. Otherwise, it will not take effect.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.set_watcher_enabled("RecordElementAppearTimes", True)
Disable Event¶
Call the following interface to disable a specific watcher event.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.set_watcher_enabled("RecordElementAppearTimes", False)
Remove Event¶
Completely removes an event from the watcher and deletes it from the list of registered events.
d.remove_watcher(name)
Check If Event Is Enabled¶
Call the following interface to check whether a watcher event is currently enabled, helping prevent situations where an event is registered but not activated.
d.get_watcher_enabled(name)
Advanced Selectors¶
In addition to simple selectors, you can use more complex selectors for precise element matching. The example below demonstrates how to write a complex selector.
d.register_press_key_watcher("PressBackWhenHomePageShows", [Selector(resourceId="com.android.market:id/v_app_item").child(index=3).sibling(index=2).child(index=2).child()], Keys.KEY_HOME)
Complete Example Code¶
Below is a complete example script that enables the watcher loop and registers three types of watcher events:
When an interface containing the text “用户协议” (User Agreement) appears, it automatically clicks “同意” (Agree).
When an interface containing the text “个人中心” (Personal Center) appears, it immediately returns to the home screen.
When an interface containing the text “好的” (OK) appears, it records the occurrence count.
Attention
Any matching events occurring on the UI before the watcher or watch events are enabled will NOT be processed!
d.remove_all_watchers()
d.set_watcher_loop_enabled(True)
d.register_click_target_selector_watcher("ClickAcceptWhenShowAggrement", [Selector(textContains="用户协议")],
Selector(textContains="同意", clickable=True))
d.register_press_key_watcher("PressBackWhenHomePageShows", [Selector(textContains="个人中心")], Keys.KEY_HOME)
d.register_none_op_watcher("RecordElementAppearTimes", [Selector(textContains="好的")])
d.set_watcher_enabled("ClickAcceptWhenShowAggrement", True)
d.set_watcher_enabled("PressBackWhenHomePageShows", True)
d.set_watcher_enabled("RecordElementAppearTimes", True)