Skip to content

9Hits Macros Build-in Functions#


Note

Some functions are required await keyword

TheCampaign object#

You can get some informations of your campaign from TheCampaign object. This object is available on the Exchange Mode only.

1
2
3
4
5
6
7
8
const TheCampaign  = { 
    "id": 123,
    "url": "http://google.com",
    "duration": 15
}

////For example, to get the campaign ID, you can use
TheCampaign.id

Log#

Print one or more message to the Macros Editor output.

Syntax
Log(msg1[, msg2, msg3, ...);
Parameters
Name Description
msg1 Message to show on the Output tab on the Macros Editor
... Message to show on the Output tab on the Macros Editor
msg_n Message to show on the Output tab on the Macros Editor
Example
await WaitForLoading ();
Log("hello", new Date(), await EvalScript ("location.href"));

Delay#

Pause the script for a period of time in milliseconds.

Syntax
await Delay (ms [, ms2]);
Parameters
Name Description
ms Delay time in miliseconds.
ms2 Delay in the range from ms to ms2 (optional).
Example
await Delay(3000);//delay for 3 seconds
await Delay(3000, 10000);//delay random between 3-10 seconds

Random#

Returns a random integer that is within a specified range.

Syntax
await Random (num1 [, num2]);
Parameters
Name Description
num1 Random a number from 0 to num1.
num2 Random a number between num1 and num2 (optional).
Example
const r1 = Random(3); //random a number from 0 to 3 (3 excluded)
const r2 = Random(5, 10);  //random a number between 5 and 10 (10 excluded)

RandomArray#

Take a random item from an array.

Syntax
await RandomArray (array);
Parameters
Name Description
array An array of any element
Example
const randomKeyword = RandomArray(["traffic exchange", "auto surf"]);
Log (randomKeyword);

ClickByCoordinates#

Click on an area on your website based on coordinates.

Syntax
await ClickByCoordinates (x1, y1, x2, y2, nClick=1);
Parameters
Name Description
x1 x coordinate of the top-left
y1 y coordinate of the top-left
x2 x coordinate of the right-bottom
y2 y coordinate of the right-bottom
nClick Click count, default is 1

Coordinates

Example
await ClickByCoordinates(100, 100, 200, 200);
await ClickByCoordinates(100, 100, 200, 200, 2);
Tip

You can also get the coordinates from the Editor like this

Get Coordinates

ClickBySelector#

Click on an element based on a css selector.

Syntax
await ClickBySelector (selector, index=0, nClick = 1, frameSearch="", frameSearchType="");
Parameters
Name Description
selector a CSS selector
index Index of the element in case there are more than one elements matched the selector. You can use number (0 for the first element) or "random" to randomly click an element, default is 0.
nClick Click count, default is 1
frameSearch If the target element is in an iframe, you have to tell the macros what frame is, empty mean top main frame.
frameSearchType Frame search conditions, possible value: "src-starts", "src-ends", "src-equals", "src-contains", "src-regex", "frame-path", default is "src-contains".
Example
//click to a link that contains 9hits.com
await ClickBySelector("a[href*='9hits.com']");

//click to a button with id #submit, inside an iframe which has src starts with http://9hits.com
await ClickBySelector("button#submit", 0, 1, "https://9hits.com", "src-starts");

//click to a button with id #submit, inside an iframe which has src equals to http://9hits.com/contact.html
await ClickBySelector("button#submit", 0, 1, "https://9hits.com/contact.html", "src-equals");

//click to a button with id #submit, inside an iframe which has src ends with /contact.html
await ClickBySelector("button#submit", 0, 1, "/contact.html", "src-ends");

//click to a button with id #submit, inside an iframe which has src contains 9hits.com
await ClickBySelector("button#submit", 0, 1, "9hits.com", "src-contains");

//click to a button with id #submit, inside an iframe which has src matched regex \d+hits\.com
await ClickBySelector("button#submit", 0, 1, "\d+hits\.com", "src-regex");

//click to a button with id #submit, inside the first frame
await ClickBySelector("button#submit", 0, 1, "0", "frame-path");

//click to a button with id #submit, inside the 2nd frame of the first frame
await ClickBySelector("button#submit", 0, 1, "0>1", "frame-path");
Tip

Are you confused? Don't worry! You can also generate this click command easily by using the Editor like this.

Get Coordinates

ClickById#

Click on an element based on its ID.

Syntax
await ClickById (id, nClick=1, frameSearch="", frameSearchType="");
Parameters
Name Description
id ID of the element.
nClick Click count, default is 1
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await ClickById("load-more-button");

ClickByXpath#

Click on an element based on its xpath.

Syntax
await ClickByXpath (xpath, nClick=1, frameSearch="", frameSearchType="");
Parameters
Name Description
xpath xpath of the element. You may use the GenerateXpath function to generate xpath.
nClick Click count, default is 1
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await ClickByXpath("/html/body/div/div[1]/div/ul/li[6]/a/div[1]/span");
await ClickByXpath(GenerateXpath("a", "href", "https://9hits.com%"));

ClickByTag#

Click on an element based on its tag name.

Syntax
await ClickByTag (tag, index, nClick=1, frameSearch="", frameSearchType="");
Parameters
Name Description
tag Tag name of the element.
index Index of the element in case there are more than one elements has the same tag name. You can use number (0 for the first element) or "random" to randomly click an element, default is 0.
nClick Click count, default is 1
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await ClickByXpath("/html/body/div/div[1]/div/ul/li[6]/a/div[1]/span");
await ClickByXpath(GenerateXpath("a", "href", "https://9hits.com%"));

ClickByClass#

Click on an element based on its class name.

Syntax
await ClickByClass (class, index, nClick=1, frameSearch="", frameSearchType="");
Parameters
Name Description
class Class name of the element.
index Index of the element in case there are more than one elements has the same class name. You can use number (0 for the first element) or "random" to randomly click an element, default is 0.
nClick Click count, default is 1
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
1
2
3
await ClickByClass("skip-button"); //Click to the first element has class name "skip-button"
await ClickByClass("skip-button", 1); //Click to the 2nd element has class name "skip-button"
await ClickByClass("skip-button", "random"); //Click to the random any element has class name "skip-button"

Randomly click any link on your website.

Syntax
await ClickRandomLink (frameSearch="", frameSearchType="");
Parameters
Name Description
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await ClickRandomLink();

Randomly click any internal link on your website.

Syntax
await ClickRandomInternalLink (frameSearch="", frameSearchType="");
Parameters
Name Description
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await ClickRandomInternalLink();

Randomly click any external link on your website.

Syntax
await ClickRandomExternalLink (frameSearch="", frameSearchType="");
Parameters
Name Description
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await ClickRandomExternalLink();

SetById#

Set the value for an attribute of an element based on its ID.

Syntax
await SetById (id, attr, value, frameSearch="", frameSearchType="");
Parameters
Name Description
id ID of the element.
attr The attribute you want to set.
value The value you want to set.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await SetById("email", "value", "[email protected]");

SetByXpath#

Set the value for an attribute of an element based on its xpath.

Syntax
await SetByXpath (xpath, attr, value, frameSearch="", frameSearchType="");
Parameters
Name Description
xpath Xpath of the element.
attr The attribute you want to set.
value The value you want to set.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await SetByXpath ('//input[@type="email"]', 'value', '[email protected]');

SetByClass#

Set the value for an attribute of an element based on its class name.

Syntax
await SetByClass (class, attr, value, index, frameSearch="", frameSearchType="");
Parameters
Name Description
class Class name of the element.
attr The attribute you want to set.
value The value you want to set.
index Index of the element in case there are multiple elements with the same class name. 0 is the first element, you can also use "random" or "all".
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
1
2
3
4
await SetByClass("text-box", "value", "text value");
await SetByClass("text-box", "value", "text value", 2);
await SetByClass("text-box", "value", "text value", "random");
await SetByClass("text-box", "value", "text value", "all");

SetByTag#

Set the value for an attribute of an element based on its tag name.

Syntax
await SetByTag (tag, attr, value, index, frameSearch="", frameSearchType="");
Parameters
Name Description
tag Tag name of the element.
attr The attribute you want to set.
value The value you want to set.
index Index of the element in case there are multiple elements with the same tag name. 0 is the first element, you can also use "random" or "all".
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
1
2
3
4
await SetByTag("input", "value", "text value");
await SetByTag("input", "value", "text value", 2);
await SetByTag("input", "value", "text value", "random");
await SetByTag("input", "value", "text value", "all");

EvalScript#

Execute javascript code on the website and return value.

Syntax
await EvalScript (jsCode, frameSearch="", frameSearchType="");
Parameters
Name Description
jsCode The javascript code to execute.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
1
2
3
4
await WaitForLoading();
const loc = await EvalScript ('window.location');
loc.href="https://9hits.com";
Log(loc);

GenerateXpath#

Create xpath to target the element. You can combine this function with ClickByXpath, SetByXpath or any function that use xpath.

Syntax
GenerateXpath (tag, attr, value, index);
Parameters
Name Description
tag Tag name of the element.
attr The attribute of the element.
value The value of the attr.
index The index of the element.
Example
//a link has href = "http://google.com"
GenerateXpath("a", "href", "http://google.com");

//a link has href starts with "http://google"
GenerateXpath("a", "href", "http://google%");

//a link has href ends with "google.com"
GenerateXpath("a", "href", "%google.com");

//a link has href contains "google"
GenerateXpath("a", "href", "%google%");

GetAttribute#

Get the value of an attribute of an element based on its xpath.

Syntax
await GetAttribute (xpath, attr, frameSearch="", frameSearchType="");
Parameters
Name Description
xpath Xpath of the element.
attr The attribute of the element.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
const result = await GetAttribute ('//input[@type="email"]', 'value');
Log (result);

GetElementPos#

Get the coordinates of an element.

Syntax
await GetElementPos (jsCode, frameSearch="", frameSearchType="");
Parameters
Name Description
jsCode The javascript code to locate the element.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
1
2
3
4
5
const pos = await GetElementPos ("document.getElementById('submit-button');");
//Return: object {X1: 100, Y1: 100, X2:200, Y2: 200}
if(pos) {
    ClickByCoordinates(pos.X1, pos.Y1, pos.X2, pos.Y2);
}

GetBrowserSize#

Return the browser size.

Syntax
await GetBrowserSize ();
Example
const size = await GetBrowserSize();
//Return: object {width: 1000, height: 800}

GetSource#

Return the source code of the website.

Syntax
await GetSource ();
Example
const source = await GetSource();

GetHtml#

Return the renderrerd html code of the website.

Syntax
await GetHtml ();
Example
const source = await GetHtml();

GetUrl#

Return the current URL.

Syntax
await GetUrl ();
Example
const url = await GetUrl();

GetUserAgent#

Return the current User-Agent.

Syntax
GetUserAgent ();
Example
const ua = GetUserAgent();

IsLoading#

Indicates that the browser is loading or not.

Syntax
await IsLoading ();
Example
1
2
3
while(await IsLoading ()) {
    await Delay(1000);
}

IsMobile#

Indicates that the browser is mobile or not (base on the User-Agent).

Syntax
IsMobile ();
Example
const isMobile = IsMobile ();

IsHideBrowser#

Indicates the browser visibility.

Syntax
await IsHideBrowser ();
Example
const isHide = IsHideBrowser ();

WaitForLoading#

Wait until the browser has finished loading (main and all sub frame), return true if browser is fully loaded, false if timedout (if timeout is passed).

Syntax
await WaitForLoading (timeout=0);
Parameters
Name Description
timeout In seconds, 0 mean unlimited.
Example
await WaitForLoading();
Log("loaded");

Navigate to an url.

Syntax
await Navigate (url[, referrer]);
Parameters
Name Description
url The target URL.
referrer Spoof a referrer url.
Example
1
2
3
await Navigate("https://google.com/");
await WaitForLoading();
await Navigate("https://9hits.com/", "https://google.com/");

GetDuration#

Exchange Mode only

Returns the maximum duration in seconds that the app will view your website.

Syntax
await GetDuration ();

GetViewedDuration#

Exchange Mode only

Returns the total time in seconds that the app viewed your website.

Syntax
await GetViewedDuration ();

GetMaxPopups#

Exchange Mode only

Returns the maximum number of popups your site may be allowed to open, if the owner disabled popups, the return value will be 0.

Syntax
await GetMaxPopups ();

GetConnectionType#

Exchange Mode only

Returns the connection type of the app. Possible values are: system, http, socks4, socks5, ssh.

Syntax
await GetConnectionType ();

GetImageByXpath#

Get an image in base64 format based on its xpath.

Syntax
await GetImageByXpath (xpath, frameSearch="", frameSearchType="");
Parameters
Name Description
xpath xpath of the element.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
const imgB64 = await GetImageByXpath (GenerateXpath("img", "name", "captcha"));

_2CaptchaSolve#

Solve captcha by 2Captcha service. If you want to use another provider that is similar with 2captcha, you can override the api endpoint by set a url to _2CaptchaServer.

Syntax
await GetImageByXpath (xpath, frameSearch="", frameSearchType="");
Parameters
Name Description
params 2Captcha parameters.
timeout Timeout in seconds.
Example
//_2CaptchaServer = "http://a-similar-2captcha.com";
const captBase64 = await GetImageByXpath('//*[@id="CAPTCHA"]');
const result = await _2CaptchaSolve({
    'key' : '2CAPTCHA_API_KEY', //replace with your 2Captcha API Key
    'method' : 'base64',
    'json' : 1,
    'body': captBase64
});
Log("Result is:", result.request);
//Example Result: {status:1, request: VMXKDG, captchaId: 1241352612}

_2CaptchaReportBad#

If you believe that captcha is resolved incorrectly, you can use this function to report it. However do not abuse.

Syntax
await _2CaptchaReportBad (key, captchaId);
Parameters
Name Description
key Your 2Captcha API Key.
captchaId ID of the captcha returned by the _2CaptchaSolve function.
Example
1
2
3
4
5
6
7
8
9
const captBase64 = await GetImageByXpath('//*[@id="CAPTCHA"]');
const result = await _2CaptchaSolve({
    'key' : '2CAPTCHA_API_KEY', //replace with your 2Captcha API Key
    'method' : 'base64',
    'json' : 1,
    'body': captBase64
});
//do something...
await _2CaptchaReportBad('2CAPTCHA_API_KEY', result.captchaId);

ACSolve#

Solve captcha by anti-captcha service. If you want to use another provider that is similar with anti-captcha, you can override the api endpoint to AntiCaptchaServer. Want to see a demo?

Syntax
await ACSolve (params, timeout);
Parameters
Name Description
params anti-captcha parameters.
timeout Timeout in seconds.
Example
//AntiCaptchaServer = "http://a-similar-anti-captcha.com";
const image = await GetImageByXpath('//*[@id="captcha_one"]');
const result = await ACSolve({
    "clientKey":"Your anti-captcha API Key",
    "task":
    {
        "type":"ImageToTextTask",
        "body":image,
        "phrase":false,
        "case":false,
        "numeric":false,
        "math":0,
        "minLength":0,
        "maxLength":0
    }
}, 150);

/* Example result
{
    "taskId":1234567,
    "errorId":0,
    "status":"ready",
    "solution":
        {
            "text":"deditur",
            "url":"http:\/\/61.39.233.233\/1\/147220556452507.jpg"
        },
    "cost":"0.000700",
    "ip":"46.98.54.221",
    "createTime":1472205564,
    "endTime":1472205570,
    "solveCount":"0"
}
*/

ACReportIncorrectImage#

If you believe that the image captcha is resolved incorrectly, you can use this function to report it. However do not abuse.

Syntax
await ACReportIncorrectImage(key, taskId);
Parameters
Name Description
key Your anti-captcha API Key.
taskId The taskId returned by the ACSolve function.
Example
const image = await GetImageByXpath('//*[@id="captcha_one"]');
const result = await ACSolve({
    "clientKey":"Your anti-captcha API Key",
    "task":
    {
        "type":"ImageToTextTask",
        "body":image,
        "phrase":false,
        "case":false,
        "numeric":false,
        "math":0,
        "minLength":0,
        "maxLength":0
    }
}, 150);
...
//do something | submit captcha...
...
if(somehow you know that the captcha was incorrect)
{
    ACReportIncorrectImage("Your anti-captcha API Key", result.taskId);
}

ACReportIncorrectRecaptcha#

If you believe that the reCaptcha is resolved incorrectly, you can use this function to report it. However do not abuse.

Syntax
await ACReportIncorrectRecaptcha(key, taskId);
Parameters
Name Description
key Your anti-captcha API Key.
taskId The taskId returned by the ACSolve function.
Example
const result = await ACSolve({
    "clientKey": "Your anti-captcha API Key",
    "task":
    {
        "type":"NoCaptchaTaskProxyless",
        "websiteURL":"https://9hits.com",
        "websiteKey":"6LdPp08UAAAAADi4dE6frVDXCv2CgESTpcscb_LS"
    }
}, 600);

/// ...
// do something | submit captcha...
/// ...

if(somehow you know that the reCaptcha was incorrect)
{
    ACReportIncorrectRecaptcha("Your anti-captcha API Key", result.taskId);
}

TryToCallRecaptchaCallBack#

Try to execute recaptcha callback.

Syntax
TryToCallRecaptchaCallBack (result);
Parameters
Name Description
result The recaptcha response.
Example
const result = await ACSolve({
    "clientKey": "Your anti-captcha API Key",
    "task":
    {
        "type":"NoCaptchaTaskProxyless",
        "websiteURL":"https://9hits.com",
        "websiteKey":"6LdPp08UAAAAADi4dE6frVDXCv2CgESTpcscb_LS"
    }
}, 600);

await TryToCallRecaptchaCallBack(result.solution.text);

TabCount#

Returns the number of opening browser windows.

Syntax
await TabCount();
Example
const tabs = await TabCount();

Typing#

Simulate keyboard typing.

Syntax
await Typing (text[, speed1, speed2]);
Parameters
Name Description
text Text to type.
speed1 - speed2 Delay time range to adjust typing speed (in miliseconds).
Example
await Typing ("Hello 9Hits");
await Typing ("Hello 9Hits", 300, 500);

ResizeTo#

Change the browser size.

Syntax
await ResizeTo (width, height);
Parameters
Name Description
width New width.
height New height.
Example
await ResizeTo (600, 500);

ScrollTo#

Scroll the browser to the specified coordinates.

Syntax
await ScrollTo (x, y, smooth = false);
Parameters
Name Description
x x coordinates.
y y coordinates.
smooth Smooth scrolling.
Example
await ScrollTo(0, 1000);
await ScrollTo(0, 0, true);

TabFocus#

Focusing on the specified browser tab, macros will be executed on the focused tab after this function call.

Syntax
await TabFocus (target);
Parameters
Name Description
target Can be a tab index (1 is the first tab) or a search pattern by URL.
Example
await WaitForLoading();
await EvalScript('open("https://google.com")');
await EvalScript('open("https://facebook.com")');
await Delay(2000);
await EvalScript('document.write("this is main tab")');
await TabFocus(2); //focus to the 2nd tab
await Delay(1000);
await EvalScript('document.write("this 2nd tab")');
await TabFocus("facebook.com"); //focus to the tab which has url contains "facebook.com"
await Delay(1000);
await EvalScript('document.write("this facebook tab")');

//focus to the first tab that does not contains facebook.com
await TabFocus("!facebook.com");

SendKeyDown#

Simulate keydown event.

Syntax
await SendKeyDown (keyCode);
Parameters
Name Description
keyCode Key Code
Example
await SendKeyDown (65); //A

SendKeyUp#

Simulate keyup event.

Syntax
await SendKeyUp (keyCode);
Parameters
Name Description
keyCode Key Code
Example
await SendKeyUp (65); //A

SendKeyChar#

Simulate keychar event.

Syntax
await SendKeyChar (keyCode);
Parameters
Name Description
keyCode Key Code
Example
await SendKeyChar ("a");

SendKeyPress#

Simulate keypress event.

Syntax
await SendKeyPress (keyCode);
Parameters
Name Description
keyCode Key Code
Example
await SendKeyPress ("a");

SendMouseClick#

Simulate mouseclick event.

Syntax
await SendMouseClick (x, y, button);
Parameters
Name Description
x x coordinates.
y y coordinates.
button can be "left", "right" or "middle".
Example
await SendMouseClick (100, 150, "left");

SendMouseMove#

Simulate mousemove event.

Syntax
await SendMouseMove (x, y);
Parameters
Name Description
x x coordinates.
y y coordinates.
Example
await SendMouseMove (100, 150);

SendMouseWheel#

Simulate mousewheel event.

Syntax
await SendMouseWheel (deltaX, deltaY);
Parameters
Name Description
deltaX Delta X.
deltaY Delta Y.
Example
1
2
3
await SendMouseWheel(0, -120); //scroll down 120px
await Delay(3000);
await SendMouseWheel(0, 120); //scroll up 120px

Exit#

Close all browsers immediately.

Syntax
Exit();

HttpRequest#

Make HTTP Request

Syntax
await HttpRequest (url, params, referrer, headers);
Parameters
Name Description
url URL to send request.
params Post Parameters.
referrer Referrer URL.
headers Custom HTTP headers.
Example
1
2
3
4
5
6
const test1 = await HttpRequest("http://google.com");
const test2 = await HttpRequest("http://google.com", "", {"post_data" : "xxx", "other_data": "yyy"});
const test3 = await HttpRequest("http://google.com", "", {"post_data" : "xxx", "other_data": "yyy"}, {"custom-header": "custom-value"});

//send raw body
const test4 = await HttpRequest("url", JSON.stringify({post_field: value}), "", {"Content-Type": "application/json"}));

ReadFile#

Bot and Profile Mode only

Read and return the contents of a file as text.

Syntax
await ReadFile (path);
Parameters
Name Description
path Path to file.
Example
const test = await ReadFile("C:\\test.txt");
Log(test);

WriteFile#

Bot and Profile Mode only

Write text to a file.

Syntax
await WriteFile (path, content, mode);
Parameters
Name Description
path Path to file.
content Text content.
mode Can be "override" or "append".
Example
await WriteFile("C:\\test.txt", "Hello");
await WriteFile("C:\\test.txt", "World", "append");

GetDownloadedFiles#

Bot and Profile Mode only

Returns an array of downloaded filenames.

Syntax
await GetDownloadedFiles ();
Example
const files = await GetDownloadedFiles();

IsFileDownloaded#

Bot and Profile Mode only

Check if the given file has been downloaded.

Syntax
await IsFileDownloaded (fileName);
Parameters
Name Description
fileName Name of the file to check.
Example
const downloaded = await IsFileDownloaded("update.zip");

SetUploadFileOrFolder#

Bot and Profile Mode only

Set the files will be selected when you click to a Chose File button on a web-page..

Syntax
SetUploadFileOrFolder (paths);
Parameters
Name Description
paths a path to file/folder or an array of paths.
Example
1
2
3
SetUploadFileOrFolder("C:\\test.txt");
SetUploadFileOrFolder("C:\\myfiles");
SetUploadFileOrFolder(["C:\\test_1.txt", "C:\\test_2.txt"]);

GetCurrentDir#

Bot and Profile Mode only

Returns the current path that 9Hits App is running.

Syntax
await GetCurrentDir ();
Example
const dir = await GetCurrentDir ();

Tip

Feel free to request a new function here.

Back to top