中文

What is Surroga?

Surroga is a keyboard & mouse automation utility for macOS. Need to type things into apps and simulators for testing? Surroga is what you need.

Surroga can be downloaded on AppStore. We continue to make Surroga the best automation utility ever to fit you needs. We need you help to shape the future direction of new features and improvements. If you have any comments about Surroga, please feel free to let us know. We will reply every feedback email.

Content

What is Surroga?

 Surroga is a keyboard & mouse automation utility for macOS.
Tips: The app will need ask for "Accessibility" permission at the "Privacy & Security" at the System Settings.

Content

Script

Remove Script

To remove a script, select it via the script list at left sidebar, then press the DELETE key on the keyboard. Or, click the script via the mouse right button, the click the Delete option in the context menu.

Export & Share

Select a script, then click Export, choice Share or Share as Protected.

The protected script is not editable, and will not create the logs.

Content

Statement

Statement group expressions and control the flow of execution.

Sort Statements

Drag the statement via mouse to change its order in the statement queue.

Delete a Statement

In the script editor, click a statement via the mouse right button, the click the Delete option in the context menu.

Tips: Don't click in the textfield. Or else, the context menu is not include the Delete item.

If

By default, one statement include only one action. When a statement is executed, this action will be executed.

On the other side, we can insert an IF sub-statement into a statement. The IF sub-statement is consist of one or more Conditions. The action of the statement, so called THEN sub-statement, will be executed only when all conditions are true. In the other words, all conditions are AND conditions.

Then

By default, one statement include only one action. After some conditions are inserted into this statement, the original action of the statement, now is called THEN sub-statement.

The action of the statement, so called THEN sub-statement, will be executed only when all conditions are true.

Else

If Conditions are false, then execute the ELSE statement (just one action).

Loop

Surroga doesn't support LOOP statement yet. Instead, it support flexible repeating at script level.

To initialize a loop, consider two scripts, main and sub-script. In the main script, we initialize the variable name VAR by assign a value(1) to it before call the sub-script. In the sub-script, it increase the VAR by 1 each time, and repeat until VAR is greater than 5. Surroga ship with a on-board script named "Counting". To view the results of this script, open a window that support text inpurt (typing keys), the click the system status bar -> Surroga -> Run -> General -> Counting.

Return

RETURN statement will abort the current script, and return to its parent script.

RETURN statement doesn't returns any value to its parent script. Instead, if we want to do this, assign the value to one of variables before return, then read the value of the variable in the parent script. In Surroga, the scope of variables are global. Variables are shared by all scripts.

In Surroga, it is implemented as an action.

Exit

EXIT, also called ABORT, END or STOP statement. This statement only only abort the running of the current script, but also its parent script, ..., parent of parent. Finally, it abort the 'Root' script.

In Surroga, it is implemented as an action.

Content

Actions

Type a Keystroke

Type a keystroke.

Tips: When recording the keystroke, please avoid conflict keys that used by system or other apps as the hot-key.

Typing Text

Enter some text by send keystrokes automatically.

Tips: This text must be consist of keys on the hardware keyboard. No all languages are supported.

Mouse Operations

Move the mouse cursor to

Click the mouse button at the calculated position.

Tips: Before move the mouse cursor or click the mouse button in the window, please make sure the window is already open and bring to front. See also: Open Application Action.

Match Precision

The different matching precisions are used when search colors or images in window / on screen:

Tips: The real color on iPhone/iPad/Mac may be dynamic according to current system appearance (dark or light), zoom ratio of iPhone Mirroring window. So, the color parameter of the Click-Color action must fit the real environment.

To accelerate the image recognizing,

Search Region

Specify the search region to speed up the search and boost the precision. It also be used to distinguish the similar or same target objects in the visual content.

If we look at the whole area as a nine-square grid

↖️⬆️↗️
⬅️❤️➡️
↙️⬇️↘️

then define search regions:

Content

Screenshot

Take a screenshot of screen or window.

We can specify the content to capture:

We can also specify the position of the origin of the portion. For a frame which size is (100,100):

Tips: The action will need ask for "Screen & System Audio Recording" permission at the "Privacy & Security" at the System Settings.

Window Title

The most macOS app shows more than one windows at the same time. For example, if we click the about option of an app, this app will shows at least two windows, the main window and the about window. For Safari, every Tab own its window. We can specify the Window Title to distinguish these windows. For Safari, the window title, in most cases, is the title of Tab.

Tips: For Safari, if we specify the title of the window, in others words, the title of the Tab, this Tab MUST be the current Tab of Safari. Or lese, the script will report 'Window Not Found'."

Optimize Performance

There are some tips to optimize the performance when capture screen content.

Content

Recognize Text

Recognize text from image. No matter where that image comes from.

Obviously, it's possible for an image to contain more than one piece of text. So, the results of recognizing-text is array of text that encoded as a JSON string, instead of just one text in a basic variable. For example, for an image that only contains a number, 32, this actions returns the array "[32]". Next, use Decode Array from JSON action to get the array [32]. Then, use Get the First Element in Array action to get 32。

Tips: DON'T look the text recognition results in the variable as a basic string, specially when the image contains only one word.

Content

Popup Alert

Pop-up a modal dialog.

Tips: There is only one model dialog can appear on screen at the same time. If more than one actions are executed to pop-up dialogs, only the first one will appear.

Send Notification

Send a local notification that showed on the current device. Notifications are used to show the status of running script, or notify users to do necessary operations.

Tips: This action just request the Mac for the notification. There is no guarantee that the notification will be showed. Please visit Apple Mac User Guide for more infomation.

Content

Variables

A variable is a container used to store content such as text, number, or image. Variables will make your scripts more powerful and flexible.

Variable, Array & Dictionary

There are three kinds of variables are supported in Surroga.

In Surroga, the scope of variables are global. Variables are shared by all scripts.

Content

In-App Purchases

Paid Features

Paid features include:

For example, when insert a new action into script, some actions in the candidate action list are disabled for picking. It means these actions are paid features. They will be unlocked after payment.

Non-Consumable vs. Subscription

Monthly-Subscription, Yearly-Subscription and Pro shared the same features but payment. Both of three unlock all features. Subscriptions are for monthly or yearly. Pro is lifetime.

Activate

Nothing happen after payment?

Surroga embedded a built-in shop from Apple that fully maintained by Apple. If the payment was completed, Apple should tell the application when network available. There are some sugguestions below:

Content

Privacy & Security

Surroga can perform lots of tasks of applications and control your Mac. As such, it needs your security permissions to do these jobs for you. These permissions may vary according to different macOS versions. In most cases, the app will need ask for these permissions at the Privacy & Security at the System Settings.

Accessibility

Allows control of your mouse and keyboard, and monitoring your mouse and keystrokes. It is required for following app features:

Screen Recording

Allows capture the screen. It is used for following app features:

Content

Privacy Statement

Data Not Collected.

The developer does not collect any data from this app.

Which app features will use screen recording?

Accessibility and Screen Recording permissions are needed to implement the essensial features of this app. The storken keys or screenshots are automated by the user's own, and never send to the developer. Please visit Privacy & Security for more infomation.

What data does your app collect via screen recording?

The data, user-specified image or text, was recorded by the user's own willing. No data was collected by this app or the developer.

For what purposes are you collecting this information? What plan for uses of this data.

No data was collected by the developer. No plan to use.

Will the data be shared with any third parties?

No.

Where will this information be stored?

This information was stored in device RAM. It will lost if app quit, or device shutdown/reboot. If the users choice output the data to system pasteboard, then they can visit macOS system instead of this app.

Content