Instruction Sets

Instruction sets are a powerful tool to control existing module and external payload private jobs at the record level.

An instuction set is included in an input domain list or file in a monitored repo. Ensure that you toggle the instruction set on (either for a domain list or monitored repo job) in order to include it in your job runs.

It is expected as a column to the right of the URL/domain target and is provided in JSON format. For example:

Note that the examples above are shown after CSV parsing. Any files containing instruction sets should be CSV-escaped, e.g. with double quotations in the JSON "".

The format of the instruction set payload includes a version and a profile, one or more actions or both a profile and actions.

Supported Profile Attributes

{"version":"3.0", "profile": {"user_agent": 1,"proxy": 1,"block_ads": true}}

An instruction set profile can control the following attributes on a per-URL basis:

• user_agent: the user agent sent by the Sincera Synthetic User.
• proxy: the proxy through which the Synthetic User visits the target.
• block_ads: Whether or not to block ads and trackers during the visit.

The following user agents are currently available:

The following proxies are currently available; note that using a residential proxy incurs an additional fee.

block_ads can be set to a boolean true or false value. Setting block_ads to false has the same effect as omitting the key/value entirely.

Contact us via Slack for additional user agent and proxy options.

Supported Actions

The latest version includes the following:

Click

{"version": "3.0", "actions": [{"click": {"selector": "h2", "limit": 1, "order": "random", "waitAfter": 0.1, "success": "new_window", "offsetCoordinates": [[1,1],[0,0]] }}]}

The “Click Element” module must be enabled in your private job. You can supply a CSS selector (such as .my-element), the number of potential matches to try if more than one exists on the URL and a delay parameter after clicking to wait for e.g. new windows to load. In 2.0+, you can supply a success condition (either a simple “click” or a “new_window”; “click” is the default) as well as x/y relative coordinates inside of the element match.

Supported Attributes:

• selector: a CSS selector used to locate DOM elements.
• limit: the maximum number of success events (e.g. clicks, new pages)
• order: how to check elements; either “random” or “fixed”
• waitAfter: the length of time in seconds to wait after clicking before proceeding.
• success: what defines a successful action; either “new_window” or “click”
• offsetCoordinates: the click target offset within a selected DOM element, measured in pixels.
• elementCheckLimit: how many “candidate” DOM elements to check to try and achieve the success condition.

Screenshot

{"version": "3.0", "actions": [{"screenshot": {"selector": "img", "trim": true}}]}

The “Screenshot” module must be enabled in your private job. You can supply a CSS selector to screenshot instead of the entire page. The first matching element will be returned. If there are multiple tabs/windows open, the selector will be applied to each window.

If you pass a “trim” parameter, the resulting screenshot will be limited to a cropped version of non-white (background) pixels. This is typically used without the selector parameter as well, if, for example, the specific selector cannot be determined ahead of time.

Versions

Version 3.0

Introduced initial browser profile.

Version 2.2

Support for “elementCheckLimit” in Click Element module.

Version 2.1

Added “trim” parameter to screenshots.

Version 2.0

Support for a success type (“click” or “new_window”) and relative coordinates to specify a click location inside of the detected element.

Version 1.1

Support for the screenshot action.

Version 1.0

Initial release of instruction sets.