UI Watcher

Watchers are used to monitor UI changes in real-time and execute preset actions, such as clicking elements, pressing keys, or recording occurrences, when preset conditions are met. You can think of it as the underlying implementation of features like Li Tiaotiao or similar ad-skipping tools. Since this feature performs clicks or key presses automatically, it may cause unintended actions when manual intervention is required. Please use it with caution.

Tip

Normally, watchers and event registration should be done at the very beginning of a script. They are generally not modified during execution.

Enable the Watcher

The following interface enables the UI watcher. By default, the watcher is disabled.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.set_watcher_loop_enabled(True)

Get Watcher Status

You can use the following interface to check if the UI watcher is currently enabled.

d.get_watcher_loop_enabled()

Disable the Watcher

Disables the watcher loop, which will stop the automatic handling of registered events like clicks.

d.set_watcher_loop_enabled(False)

Attention

Registering too many watch events may affect system performance or real-time responsiveness.

Remove All Watchers

Removes all applied watch events. This can clear rules applied by previous or abnormally terminated scripts. It is recommended to run this before starting each script to prevent events registered by previous tasks from interfering with the current process.

d.remove_all_watchers()

Register a Click Event

A click event will automatically perform a click action when a matching selector appears on the screen. For example, it can be used to automatically bypass software pop-ups like user agreements or update prompts, or to perform automatic clicks on specific screens.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.register_click_target_selector_watcher("ClickAcceptWhenShowAggrement", [Selector(textContains="User Agreement")], Selector(textContains="Agree", clickable=True))

Hint

The second parameter supports multiple Selectors, meaning the event will only be handled if all Selector conditions are met.

After registering the event above, when a screen containing the text "User Agreement" appears, it will automatically click the "Agree" button.

Register a Key Press Event

A key press event will automatically perform a key press action when a matching selector appears. For example, it can be used for automatic "back" actions to avoid entering certain screens, although a click event could also achieve the same result.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.register_press_key_watcher("PressBackWhenHomePageShows", [Selector(textContains="Personal Center")], Keys.KEY_HOME)

Hint

The second parameter supports multiple Selectors, meaning the event will only be handled if all Selector conditions are met.

After registering the event above, when a screen containing the text "Personal Center" appears, it will automatically press the phone's HOME key.

Register a Count Event

A count event increments a counter by 1 when a matching selector appears on the screen. This can be used to track whether a certain screen has appeared or to count its occurrences, especially for important information that flashes by quickly.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.register_none_op_watcher("RecordElementAppearTimes", [Selector(textContains="OK")])

Hint

The second parameter supports multiple Selectors, meaning the event will only be handled if all Selector conditions are met.

The event above records the number of times a screen containing "OK" appears. Use the following interface to get the triggered count for this event.

d.get_watcher_triggered_count("RecordElementAppearTimes")

Enable an Event

After an event is registered, it must be enabled to be added to the UI watcher loop; otherwise, it will not be applied.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.set_watcher_enabled("RecordElementAppearTimes", True)

Disable an Event

You can call the following interface to make the UI watcher stop monitoring a specific event.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.set_watcher_enabled("RecordElementAppearTimes", False)

Remove an Event

Completely removes an event from the watcher. It will also be deleted from the list of registered events.

d.remove_watcher(name)

Get Event Enabled Status

Call the following interface to check if an event is properly enabled, preventing cases where it is registered but not enabled.

d.get_watcher_enabled(name)

Advanced Selectors

In addition to simple selectors, you can also use more complex selectors for element matching. The following is an example of 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 sample code block that enables the watcher loop and registers three types of watch events. When text containing "User Agreement" appears, it automatically clicks "Agree". When text containing "Personal Center" appears, it immediately returns to the home screen. When text containing "OK" appears, it records the number of times this screen has appeared.

Attention

Any matching events that occur on the UI before the watcher or a specific watch event is enabled will not be handled!
d.remove_all_watchers()
d.set_watcher_loop_enabled(True)

d.register_click_target_selector_watcher("ClickAcceptWhenShowAggrement", [Selector(textContains="User Agreement")],
                                         Selector(textContains="Agree", clickable=True))
d.register_press_key_watcher("PressBackWhenHomePageShows", [Selector(textContains="Personal Center")], Keys.KEY_HOME)
d.register_none_op_watcher("RecordElementAppearTimes", [Selector(textContains="OK")])

d.set_watcher_enabled("ClickAcceptWhenShowAggrement", True)
d.set_watcher_enabled("PressBackWhenHomePageShows", True)
d.set_watcher_enabled("RecordElementAppearTimes", True)