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");

CapturePage#

Take an screenshot of the web page in JPEG format, return it as base64 encoded.

Syntax
await CapturePage (quality);
Parameters
Name Description
quality The quality of the image (from 0 to 100), default is 80.
Example
const imgBase64 = await CapturePage();
const betterImgBase64 = await CapturePage(100);

CaptureArea#

Capture a specified area of the web page with JPEG format, return as base64 encoded.

Syntax
await CaptureArea (x1, y1, x2, y2, quality);
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
quality The quality of the image (from 0 to 100), default is 80.
Example
const imgBase64 = await CaptureArea(0, 0, 300, 500);
const betterImgBase64 = await CaptureArea(0, 0, 300, 500, 100);

CaptureElement#

Capture an element by a selector of the web page with JPEG format, return as base64 encoded. Useful when you need to take a picture to bypass captcha, but you can also capture any element not just img tag.

Syntax
await CaptureElement (selector, quality, frameSearch, frameSearchType);
Parameters
Name Description
selector The CSS selector
quality The quality of the image (from 0 to 100), default is 80.
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
const captcha = await CaptureElement("#image_captcha");
const avatar = await CaptureElement("#profile img.avatar");
Tip

You can also generate the CaptureElement command easily by using the Editor.

Get CaptureElement

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"));

SolveRecaptcha#

This is a high-level function for solving ReCaptcha, built on top of functions _2CaptchaSolve and ACSolve. If the captcha is successfully solved, the result will automatically be assigned, then you can click the buttons such as Submit, Continue, etc using click functions. If these buttons do not exist, you can call the function TryToCallRecaptchaCallBack instead. The return result will be false in case of failed resolve, otherwise the data from the service API server.

Syntax
await SolveRecaptcha (service, apiKey, timeout = 300, overrideApiServer = null);
Parameters
Name Description
service Can be: 2captcha or anti-captcha
apiKey Your API key with the corresponding service
timeout Maximum time to solve the captcha, in seconds (optional)
overrideApiServer Overwrite the URL server of the captcha service (optional)
Example
//test on https://www.google.com/recaptcha/api2/demo
await WaitForLoading ();
const result = await SolveRecaptcha("2captcha", "YOUR_API_KEY");
//const result = await SolveRecaptcha("anti-captcha", "YOUR_API_KEY");
await ClickBySelector('#recaptcha-demo-submit'); //click submit button
//await TryToCallRecaptchaCallBack(result.request);

/*
Example of result value:

2captcha: {"status":1,"request":"THE_RESPONSE_RESULT","captchaId":"71006265012"}

anti-captcha: 
{
    "errorId":0,
    "status":"ready",
    "solution":{
        "gRecaptchaResponse":"THE_RESPONSE_RESULT",
        "cookies":{
            "_GRECAPTCHA":"COOKIES..."
        }
    },
    "cost":"0.00200",
    "ip":"1.2.3.4",
    "createTime":1658115990,
    "endTime":1658116074,
    "solveCount":0,
    "taskId":685667638
}
*/

SolveImageCaptcha#

This is a high-level function for solving image captcha, built on top of functions _2CaptchaSolve and ACSolve. If the captcha is successfully solved, the result will automatically be assigned, then you can click the buttons such as Submit, Continue, etc using click functions.The return result will be false in case of failed resolve, otherwise the data from the service API server.

Syntax
await SolveImageCaptcha (imgSelector, resultSelector, service, apiKey, timeout = 300, overrideApiServer = null);
Parameters
Name Description
imgSelector The CSS selector of the image.
resultSelector The CSS selector of the input textbox to fill the reuslt.
service Can be: 2captcha or anti-captcha
apiKey Your API key with the corresponding service
timeout Maximum time to solve the captcha, in seconds (optional)
overrideApiServer Overwrite the URL server of the captcha service (optional)
Example
//test on https://captcha.com/demos/features/captcha-demo.aspx
await WaitForLoading ();
const result = await SolveImageCaptcha("#demoCaptcha_CaptchaImage", "#captchaCode", "2captcha", "YOUR_API_KEY")
// const result = await SolveImageCaptcha("#demoCaptcha_CaptchaImage", "#captchaCode", "anti-captcha", "YOUR_API_KEY")
await ClickBySelector ("#validateCaptchaButton");

/*
Example of result value:

2captcha: {"status":1,"request":"bw8t","captchaId":"71014870176"}

anti-captcha: 
{
    "errorId":0,
    "status":"ready",
    "solution":{
        "text":"BW8T",
        "url":"http://209.212.146.170/80/165820017899645.jpg"
    },
    "cost":"0.00070",
    "ip":"1.2.3.4",
    "createTime":1658200178,
    "endTime":1658200181,
    "solveCount":0,
    "taskId":701277528
}
*/

_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 _2CaptchaSolve (params, timeout);
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.

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.gRecaptchaResponse);

WaitForElement#

Wait for an element (a DOM object) until a certain condition is satisfied. Return true when conditionCallback function returns true, false when timed out.

Syntax
await WaitForElement (selector, conditionCallback, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
conditionCallback The callback function with an argument of the object selected by the selector must return true or false.
timeout Maximum time to wait for the conditionCallback to returns true, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
1
2
3
4
//wait for an image (img tag) to has a none-empty src
await WaitForElement("img#captcha", (elm) => {
    return elm && elm.src != ""
})

WaitForElmToAppear#

Wait for an element to appear.

Syntax
await WaitForElmToAppear (selector, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
timeout Maximum time to wait, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await WaitForElmToAppear("#submit-btn");
await WaitForElmToAppear("#submit-btn", 25); //wait for 25s

WaitForElmToDisappear#

Wait for an element to disappear.

Syntax
await WaitForElmToDisappear (selector, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
timeout Maximum time to wait, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await WaitForElmToDisappear("#cancel-btn");
await WaitForElmToDisappear("#cancel-btn", 25); //wait for 25s

WaitForElmToHasAttr#

Wait for an element until it has a desired attribute.

Syntax
await WaitForElmToHasAttr (selector, attr, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
attr The desired attribute
timeout Maximum time to wait, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await WaitForElmToHasAttr("#submit-btn", "class");

WaitForElmToHasAttrValue#

Wait for an element until it has a desired attribute with a desired value.

Syntax
await WaitForElmToHasAttrValue (selector, attr, value, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
attr The desired attribute
value The desired value
timeout Maximum time to wait, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await WaitForElmToHasAttrValue("#submit-btn", "class", "success-btn");

WaitForElmToLoseAttr#

Wait for an element until it lose a desired attribute.

Syntax
await WaitForElmToLoseAttr (selector, attr, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
attr The desired attribute
timeout Maximum time to wait, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await WaitForElmToLoseAttr("#submit-btn", "disabled");

WaitForElmTextUntil#

Wait for an element until its text (innerText) satisfies a certain condition.

Syntax
await WaitForElmTextUntil (selector, condition, value, timeout, frameSearch, frameSearchType);
Parameters
Name Description
selector a CSS selector
condition Condition to check value, can be: equals, contains, starts-with, ends-with
value The desired value
timeout Maximum time to wait, in seconds, default is 300s
frameSearch See ClickBySelector
frameSearchType See ClickBySelector
Example
await WaitForElmTextUntil("#count-down", "contains", "Please wait");
await WaitForElmTextUntil("#count-down", "equals", "0s");

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");

SendKeyPress#

Simulate keypress event.

Syntax
await SendKeyPress (keyCode, modifiers);
Parameters
Name Description
keyCode Key Code
modifiers Valid values: WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT
Example
1
2
3
await SendKeyPress (K_KEYA); //press A
await SendKeyPress (K_KEYV, WITH_CTRL); //press Ctrl + V
await SendKeyPress (K_KEYV, WITH_CTRL | WITH_SHIFT); //press Ctrl + Shift + V

SendKeyDown#

Simulate keydown event.

Syntax
await SendKeyDown (keyCode, modifiers);
Parameters
Name Description
keyCode Key Code
modifiers Valid values: WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT
Example
await SendKeyDown (K_KEYA); //keydown A

SendKeyUp#

Simulate keyup event.

Syntax
await SendKeyUp (keyCode, modifiers);
Parameters
Name Description
keyCode Key Code
modifiers Valid values: WITH_ALT, WITH_CTRL, WITH_COMMAND, WITH_SHIFT
Example
await SendKeyUp (K_KEYA); //keyup A

SendKeyChar#

Simulate keychar event.

Syntax
await SendKeyChar (keyCode);
Parameters
Name Description
keyCode Key Code or a character
Example
await SendKeyChar (K_KEYA);
await SendKeyChar ("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.

Keycode Table#

Use for these functions: SendKeyPress, SendKeyDown, SendKeyUp, SendKeyChar.

Click here to see the list of key codes
Name Description
K_BACKSPACE Backspace
K_TAB Tab
K_ENTER Enter
K_SHIFT Shift
K_CONTROL Control
K_ALT Alt
K_PAUSE Pause
K_CAPSLOCK CapsLock
K_ESCAPE Escape
K_SPACE Space
K_PAGEUP PageUp
K_PAGEDOWN PageDown
K_END End
K_HOME Home
K_ARROWLEFT ArrowLeft
K_ARROWUP ArrowUp
K_ARROWRIGHT ArrowRight
K_ARROWDOWN ArrowDown
K_PRINTSCREEN PrintScreen
K_INSERT Insert
K_DELETE Delete
K_DIGIT0 Digit0 (0)
K_DIGIT1 Digit1 (1)
K_DIGIT2 Digit2 (2)
K_DIGIT3 Digit3 (3)
K_DIGIT4 Digit4 (4)
K_DIGIT5 Digit5 (5)
K_DIGIT6 Digit6 (6)
K_DIGIT7 Digit7 (7)
K_DIGIT8 Digit8 (8)
K_DIGIT9 Digit9 (9)
K_KEYA KeyA (A)
K_KEYB KeyB (B)
K_KEYC KeyC (C)
K_KEYD KeyD (D)
K_KEYE KeyE (E)
K_KEYF KeyF (F)
K_KEYG KeyG (G)
K_KEYH KeyH (H)
K_KEYI KeyI (I)
K_KEYJ KeyJ (J)
K_KEYK KeyK (K)
K_KEYL KeyL (L)
K_KEYM KeyM (M)
K_KEYN KeyN (N)
K_KEYO KeyO (O)
K_KEYP KeyP (P)
K_KEYQ KeyQ (Q)
K_KEYR KeyR (R)
K_KEYS KeyS (S)
K_KEYT KeyT (T)
K_KEYU KeyU (U)
K_KEYV KeyV (V)
K_KEYW KeyW (W)
K_KEYX KeyX (X)
K_KEYY KeyY (Y)
K_KEYZ KeyZ (Z)
K_METALEFT MetaLeft (Meta)
K_METARIGHT MetaRight (Meta)
K_CONTEXTMENU ContextMenu
K_NUMPAD0 Numpad0 (0)
K_NUMPAD1 Numpad1 (1)
K_NUMPAD2 Numpad2 (2)
K_NUMPAD3 Numpad3 (3)
K_NUMPAD4 Numpad4 (4)
K_NUMPAD5 Numpad5 (5)
K_NUMPAD6 Numpad6 (6)
K_NUMPAD7 Numpad7 (7)
K_NUMPAD8 Numpad8 (8)
K_NUMPAD9 Numpad9 (9)
K_NUMPADMULTIPLY NumpadMultiply (*)
K_NUMPADADD NumpadAdd (+)
K_NUMPADSUBTRACT NumpadSubtract (-)
K_NUMPADDECIMAL NumpadDecimal (.)
K_NUMPADDIVIDE NumpadDivide (/)
K_F1 F1
K_F2 F2
K_F3 F3
K_F4 F4
K_F5 F5
K_F6 F6
K_F7 F7
K_F8 F8
K_F9 F9
K_F10 F10
K_F11 F11
K_F12 F12
K_NUMLOCK NumLock
K_SCROLLLOCK ScrollLock
K_AUDIOVOLUMEMUTE AudioVolumeMute
K_AUDIOVOLUMEDOWN AudioVolumeDown
K_AUDIOVOLUMEUP AudioVolumeUp
K_MEDIATRACKNEXT MediaTrackNext
K_MEDIATRACKPREVIOUS MediaTrackPrevious
K_MEDIASTOP MediaStop
K_MEDIAPLAYPAUSE MediaPlayPause
K_LAUNCHMAIL LaunchMail
K_LAUNCHMEDIAPLAYER LaunchMediaPlayer
K_LAUNCHAPPLICATION1 LaunchApplication1
K_LAUNCHAPPLICATION2 LaunchApplication2
K_SEMICOLON Semicolon (;)
K_EQUAL Equal (=)
K_COMMA Comma (,)
K_MINUS Minus (-)
K_PERIOD Period (.)
K_SLASH Slash (/)
K_BACKQUOTE Backquote (`)
K_BRACKETLEFT BracketLeft ([)
K_BACKSLASH Backslash (\)
K_BRACKETRIGHT BracketRight (])
K_QUOTE Quote (')
Back to top