Somiibo, all rights reserved. 2018 ©

Functions

Methods to manipulate the bot

Bot Functions

Here's the full list of all available bot functions

You could easily customize your bot by using the functions below to control the behavior. Before going too deep into the various functions, it is imperative to understand the difference between regular functions that require an await expression. If you're a little lost while reading thise, it is highly recommended that you check out the example bots where you can see some real-world examples of custom bots and modules.

The await expression causes the main run() function execution to pause until a Promise is fulfilled or rejected, and to resume execution of the run() function after fulfillment. The purpose of await functions is to simplify the behavior of the bot and allow actions to operate synchronously.

Please note: the bot class is already predefined for you, you do not need to define it.


Bot Object Methods

Here's the full list of all available bot methods

This section documents how to make your bot perform important actions such as navigating webpages, finding elements on a webpage, clicking buttons, moving the mouse, and more!

bot.generalProcedure()

Checks if the bot needs a break, if the bot has stopped, and updates the run speed as needed.

Syntax

copy
bot.generalProcedure()

Parameter Values

Parameter Type Description
none - -

Return Values

no return

Notes

Must be positioned as the first line in the run() function.

  • Example Implementation

bot.getProtocol()

Returns the current protocol of the bot

Syntax

copy
bot.getProtocol()

Parameter Values

Parameter Type Description
none - -

Return Values

A string representing the current protocol

Notes

Protocol can be changed and retrieved before the current protocol is finished running.

  • Example Implementation

bot.setProtocol()

Sets the current protocol of the bot

Syntax

copy
bot.setProtocol(protocol)

Parameter Values

Parameter Type Description
protocol string Required. The protocol to change to

Return Values

none

Notes

Protocol can be changed and retrieved before the current protocol is finished running.

  • Example Implementation

bot.wait()

Pauses the bot for a specified amount of time.

await is satisfied when the timer is completed.

Syntax

copy
await bot.wait(ms, msRandom)

Parameter Values

Parameter Type Description
ms Number Required. Milliseconds to wait
msRandom Number Required. Randomizes ms by (+/-) this amount

Return Values

none

Notes

none

Example

  • Example Implementation

bot.selectElement()

Selects an element on the bot's current webpage. You must select an element before you can click it. Providing an indexOffset argument gives you control over which element to pick in the event that multiple elements are found matching your query string.

await is satisfied when the DOM returns an element.

Syntax

copy
await bot.selectElement(options)

Parameter Values

Parameter Type Description
options Object An object where querySelector describes which DOM element to select and indexOffset describes which element to select in the event that multiple elements match the query string.
  • querySelector: Required String. A standard Javascript QuerySelectorAll string. eg.div.links > a
  • indexOffset: Optional String or Number. Offset the selector. eg. first, last, 2

Return Values

none

Notes

Changes the selectElement property. If no indexOffset is provided it will default to the first element found.

Example

  • Example Implementation

bot.mouseClick()

Clicks on the selected element.

await is satisfied after the mouse is moved and the click is completed.

Syntax

copy
await bot.mouseClick(options)

Parameter Values

Parameter Type Description
options Object An object where selectedElement is a boolean that controls whether the current selectedElement is to be clicked.
  • selectedElement: Required Boolean. Click the selected element. eg.true

Return Values

none

Notes

none

Example

  • Example Implementation

bot.keyboardType()

Types a sequence of characters, case-sensitive.

await is satisfied when the last character of the string has finished typing.

Syntax

copy
await bot.keyboardType(options)

Parameter Values

Parameter Type Description
options Object An object where string is a String to be typed and special is String representing a special key to be pressed. You may pass either string or special but not both.
  • string: Optional String. The string to type, upper-case is respected. eg.reDDit
  • special: Optional String. A special character to type. eg.enter
  • note, you can pass either string or special but not both.

Return Values

none

Notes

none

Example

  • Example Implementation

bot.waitForCondition()

Waits for a bot property to meet a condition.

await is satisfied when the condition is met or when the test times out.

Syntax

copy
await bot.waitForCondition(options)

Parameter Values

Parameter Type Description
options Object An object containing the property to test, what type of test to perform, and how long to wait for the condition to satisfy before timing out.
  • property: Required String. A property to test. eg. 'urlLoaded'
  • equator: Required String. Type of comparison. eg. 'equals'
  • condition: Required String, Boolean, or Number. The other side of the comparison. eg. true.
  • timeout: Required Number. How many ms to wait before the test concludes automatically. eg. 20000.

Return Values

none

Notes

none

Example

  • Example Implementation

bot.consoleLog()

Log a message to the bot's console. Remember, you can open the console by pressing Cmd + I or Ctrl + I

Syntax

copy
bot.consoleLog(message)

Parameter Values

Parameter Type Description
message String Required. A string that will be console logged. eg. 'Hello World!'

Return Values

none

Notes

none

Example

  • Example Implementation

bot.getRandomProxy()

Get a random proxy from either the default proxy list or the user's custom proxy list.

Syntax

copy
bot.getRandomProxy(type)

Parameter Values

Parameter Type Description
type String Required. A string that deterimes which type of proxy to get (default or custom).
  • default: Returns a random proxy from the list of default proxies
  • custom: Returns a random proxy from the list of custom proxies

Return Values

A string representing a proxy in ip:port format.

Notes

none

Example

  • Example Implementation

bot.setProxy()

Set a proxy for the current tab/session.

await is satisfied when the proxy is set or cannot connect.

Syntax

copy
await bot.setProxy(proxy)

Parameter Values

Parameter Type Description
proxy String Required. A proxy in ip:port format. eg. '12.34.56.78:1234'

Return Values

none

Notes

none

Example

  • Example Implementation

bot.clearProxy()

Set a proxy for the current tab/session.

await is satisfied when the proxy clears.

Syntax

copy
await bot.clearProxy()

Parameter Values

Parameter Type Description
none - -

Return Values

none

Notes

none

Example

  • Example Implementation

bot.getRandomUserAgent()

Get and return a random user agent string.

Syntax

copy
bot.getRandomUserAgent()

Parameter Values

Parameter Type Description
none - -

Return Values

none

Notes

none

Example

  • Example Implementation

bot.setUserAgent()

Set a user agent for the current tab/session.

await is satisfied when the user agent is set.

Syntax

copy
await bot.setUserAgent(ua)

Parameter Values

Parameter Type Description
ua String Required. A user agent in ip:port format. eg. 'userAgentStringHerew'

Return Values

none

Notes

none

Example

  • Example Implementation

Bot Object Properties

Here's the full list of all available bot properties

All Bot Properties

Top Level Properties

Top Level Properties are accessed via bot.getProperty('propertyname')

Property Type Read Description
url String Read Only The current URL of the bot. eg: 'https://www.google.com/'
urlLoaded Boolean Read Only Page-load status. eg: true
selectElement Object Read Only An object representing data points of the current selected element. Child properties:
  • exists
  • id
  • class
  • href
  • count
  • innerText
  • x
  • y
  • width
  • height

Example

  • Example Implementation