Somiibo, all rights reserved. 2018 ©

Example Modules

Start building a bot from one of our templates

Learn from our example bots

Sometimes it's easier to see some premade, finished and polished products before all the nitty-gritty things start to make sense. That's why we've compiled an extensive list of example modules that you can instantly load into Somiibo. Let's go over the basic structure of each example bot.

Each example will contain 3 basic elements: A run down of what the example does, the source code, and finally a detailed explanation of the example. If you're not sure how to use one of these examples, we explain how to load a script into Somiibo in our getting started tutorial.

Otherwise, let's get right to it!

Skeleton Module

The absolute, bare-minimum essential elements of a custom bot module

Rundown

Let's start off with something basic. This is an example of just enough code to get you up and running. No more, no less.

Source Code

copy

  //A. settings
  var userSettings = {}

  //B. variables

  //C. bot script
  async function run() {
    //D. general procedure
    bot.generalProcedure()

    if (bot.getProtocol() == 'init') {
      //E1. init code here
      bot.setProtocol('main')
    }

    if (bot.getProtocol() == 'main') {
      //E2. main code here
    }

    //F. script runner
    setTimeout(function () { run() }, bot.getRunDelay());
  }

                    

Walkthrough

That's it! Pretty simple right?

  • A

    This is your required userSettings variable. We'll go over how settings work in the next example, but this is just to show you where the object should go.

  • B

    Here is where your other custom variables will go. Again, nothing is here but this is just showing where the variables should go. They must be outside of the run() function or else they will be garbage-collected.

  • C

    The most important part of a module: the run() function. Here is where the magic happens. This is a sort of a recursive loop containing multiple smaller processes know as protocols. The entire life of the bot exists within this function. When the bot ends, this function ceases to execute. During the bot's run(), it will operate on one protocol at a time, synchornously, that exists inside the run() function. You can change protocols whenever you want.

  • D

    We're not going to go into incredible detail here, but the generalProcedure() function, which is a method of our bot class, is just meant for some general housekeeping. This function checks if the bot needs to take a break, among other things.

  • E1

    The first required protocol, the Init protocol. This is where the bot starts. In other words, the first protocol to run is always this, the Init Protocol. You should only be in the Init protocol once during a bot's lifetime.

  • E2

    The second and last required protocol, the Main protocol. You can put anything you want here, but this protocol serves as the base of your bot. You would generally want to have the rest of your protocols stream out from the Main protocol.

  • F

    The final required element of a custom bot module is the calling of the run() function. This is how the module's logic repeats. Without this, your module will only run through once and then stop.

Protocols, Waiting, and Console Logs

Let's expand on the last example and add a few protocols, waits, and console logs!

Rundown

In this example we will explore how to navigate between protocols, how to wait arbitrary amounts of time, and how to console log messages!

Source Code

copy

// settings
var userSettings = {}

// variables
var counter = 0;
var myMessage1 = 'This is the first message!'
var myMessage2 = 'This is the second message!'

// bot script
async function run() {
  bot.generalProcedure()

  if (bot.getProtocol() == 'init') {
    bot.setProtocol('main')
  }

  if (bot.getProtocol() == 'main') {
    // A. first time through, counter is 0
    if (counter == 0) {
      bot.consoleLog(myMessage1)
    }
    // B. fifth time through, counter is 5
    if (counter == 5) {
      await bot.wait(2000, 500)
    }
    // C. tenth time through, counter is 10
    if (counter == 10) {
      bot.consoleLog(myMessage2)
      bot.end()
    }
    // D. this is outside of a conditional statement, so it runs every time
    bot.setProtocol('counter_raise')
  }

  // E. protocol that actually increases the counter
  if (bot.getProtocol() == 'counter_raise') {
    counter += 1;
    bot.consoleLog('Counter is now ' + counter)
    bot.setProtocol('main')
  }

  setTimeout(function () { run() }, bot.getRunDelay());
}

                    

Walkthrough

That's it! Pretty simple right? This bot is very easy to follow if you study it and then run it inside Somiibo, so we suggest doing that. Be sure to press Cmd + I or Ctrl + I to open the developer tools.

Here's a quick summary of whats going on: We define two messages at the top namely myMessage1 and myMessage2 and a counter. During the main protocol, we simply check the counter for 3 separate values via the 3 conditional if statements.

Regardless of whether a conditional is triggered during the main protocol, this script will always go to the counter_raise protocol and increase the counter.

  • A

    After pressing start, the bot will eventually reach the main. The counter variable is 0, so the firstif statement triggers, the following two are ignored. Inside the if statement, the first message is console logged. At the end of the main protocol, we see that the bot is set to jump to the counter_raise protocol.

  • B

    While the counter is 1 - 4, nothing happens other than a simple console log of the current value during the counter_raise protocol. But when the counter is equal to 5, we initiate a wait() function. This function is synchronous, as definined by the word await. All bot functions will cease until the timer is fulfilled. In this case we passed a 2000 and a 500. You can read more about the wait function, as well as other functions in our functions doc.

  • C

    This conditional is only executed once when counter is equal to 10. It console logs the second message and also calls end()

  • D

    As mentioned above, this setProtocol() function is outside of the 3 conditional statements inside the main protocol, which means it is executed every time.

Rundown

Okay now we're getting to the good stuff about making bots. In this tutorial we're going to go over how to navigate to different web pages, select elements (like buttons) on the webpage, and then click them!

Source Code

copy

// settings
var userSettings = {}

// variables
var searchQuery = 'reDDit'
var googleSearchBox = 'input.gsfi'
var resultToClick = 'a[href="https://www.reddit.com/"]' /* got by Ctrl + I, then inspect the link on Google */
var finalSite = 'https://www.reddit.com/'

// bot script
async function run() {
  bot.generalProcedure()

  if (bot.getProtocol() == 'init') {
    bot.setProtocol('main')
  }

  if (bot.getProtocol() == 'main') {
    bot.setProtocol('google_search')
  }


  if (bot.getProtocol() == 'google_search') {
    // A. navigation to our first site
    await bot.navigateUrl('https://google.com')
    // B. selecting an element: takes a stardard js querySelectorAll argument
    await bot.selectElement({querySelector: googleSearchBox})
    // C. mouseClick on selected element
    await bot.mouseClick({selectedElement: true})
    await bot.wait(500, 100)
    // D. typing a string, and then pressing the enter key
    await bot.keyboardType({string: searchQuery})
    await bot.keyboardType({special: 'enter'})
    // E. when clicking a page-changing button, it's wise to wait for the URL to load before continuing
    await bot.wait(2000, 100)
    await bot.waitForCondition({
      property: 'urlLoaded', equator: 'equals', condition: true,
      timeout: 20000
    })
    bot.setProtocol('google_click')
  }

  if (bot.getProtocol() == 'google_click') {
    await bot.selectElement({querySelector: resultToClick})
    await bot.mouseClick({selectedElement: true})
    await bot.wait(2000, 100)
    await bot.waitForCondition({
      property: 'urlLoaded', equator: 'equals', condition: true,
      timeout: 20000
    })
    bot.setProtocol('check_reddit')
  }

  if (bot.getProtocol() == 'check_reddit') {
    if (bot.getProperty('url') == finalSite) {
      bot.consoleLog('FINISHED: Reached final site')
      bot.end();
    } else {
      bot.consoleLog('ERROR: We did not reach final site!')
      bot.setProtocol('google_search')
    }
  }


  setTimeout(function () { run() }, bot.getRunDelay());
}

                    

Walkthrough

This example bot is a lot less jumping around and much more linear. Essentially, the google_search protocol makes the bot navigate to Google, type a query into the search box, and then press the enter key.

The next protocol, google_click, simply looks for the defined SERP result and then clicks it.

The last bot protocol, check_reddit simply checks if the webpage has been successfully navigated to our example site, https://www.reddit.com/

  • A

    After pressing start, the bot will eventually reach google_search. We see the use of navigate(), a synchronous function, which takes in one paramater: url. The bot stays on this line until the page loads, or times out.

  • B

    selectElement() is somewhat tricky to understand. All it does, is "pick" an HTML element on the page. To actually interact with the element, such as a click, we must first select it with this function. It takes in an object and the only required parameter is querySelector, which accepts a string in standard js querySelectorAll notation

  • C

    The next part to the HTML element selection is the interaction itself. A click is the most popular interaction. click() accepts an object and the only required parameter is selectedElement, a boolean value. Again, any bot command that takes time must be awaited! This is to ensure that the action completes entirely before the next one happens.

  • D

    These lines are pretty simple if you've gotten this far. keyboardType() accepts an object where you must provide either a string.

Setting a Custom Proxy and User Agent

In this lesson we're going to learn how to instantly change our IP and User Agent!

Rundown

When you make a bot, sometimes it's useful to be able to operate it on a custom proxy or a cusotm user agent. You can use this to help create the illusion that the user is coming from a different location or a device.

Source Code

copy

// settings
var userSettings = {}

// variables

// bot script
async function run() {
  bot.generalProcedure()

  if (bot.getProtocol() == 'init') {
    bot.setProtocol('main')
  }

  if (bot.getProtocol() == 'main') {
    bot.setProtocol('set_proxy')
  }


  if (bot.getProtocol() == 'set_proxy') {
    // A. retrieve a random proxy from Somiibo's database of free proxies
    var randomProxy = bot.getRandomProxy('default')
    // B. set the proxy using the variable we stored in part A.
    await bot.setProxy(randomProxy)
    bot.setProtocol('set_userAgent')
  }

  if (bot.getProtocol() == 'set_userAgent') {
    // C. retrieve a random user agent from Somiibo's database of user agents
    var randomUserAgent = bot.getRandomUserAgent()
    // D. set the user agent using the variable we stored in part C.
    await bot.setUserAgent(randomUserAgent)
    bot.setProtocol('check_settings')
  }

  if (bot.getProtocol() == 'check_settings') {
    await bot.wait(2000, 100)
    // E. go to this website to check if settings configured correctly
    await bot.navigateUrl('https://www.iplocation.net/find-ip-address')
    bot.end()
  }

  setTimeout(function () { run() }, bot.getRunDelay());
}
                    

Walkthrough

This bot is incredibly simple if you've done the other examples so far. It simple picks a random proxy and then connects to it. After that, it picks a random user agent and uses it. Finally, it goes to an external website to prove that it connected using the correct IP proxy and user agent.

  • A

    After pressing start, the bot will reachset_proxy. We see the use of bot.getRandomProxy('default'), a synchronous function, which takes in one paramater: a string to tell whether it will retireve a default proxy or a custom proxy. We store this in a variable for later.

  • B

    setProxy(randomProxy) is called immediately after, using the proxy retrieved in step A. We must use await so that we can give the bot time to connect to the proxy.

  • C

    Similar to how we got a random proxy, we are now getting a random user agent by calling bot.getRandomUserAgent() which takes no parameters. We store this returned value to a variable so we can use it in the next step.

  • D

    These commands are pretty simple if you've gotten this far. kbot.setUserAgent(randomUserAgent) is used to actually switch the user agent. This also requries an await to function properly.

  • E

    Finally, we navigate to an external site that will confirm if we have connected to the proxy and user agent successfully. You wouldn't normally navigate to this page, but we do it here to show that it works (hopefully).