guardian4_api

An easy-to-use API which calls Guardian4 and returns the results.

Installation

The API requires G4 v1.11.2 or above and all prerequisites to be installed.

Install in a Node.js project using:

npm install guardian4_api

Basic usage

To process a single URL using the default parameters and async/await:

(async () => {

  const g4api = require('guardian4_api');

  try {
    let g4 = await g4api.run('siteurl.com');
    console.log(g4.result);
  }
  catch (e) {
    console.log(e);
  }

})();

Options

The following options can be set:

|option|description| |-:|-| |command|Guardian4 shell command (g4)| |timeout|maximum execution time in ms (0)| |opt|Guardian4 parameters (long names only - see G4 documentation)|

Example:

const g4api = require('guardian4_api');

g4api.timeout = 60000;                  // timeout at 60 seconds
g4api.opt.proxy = '1.2.3.4:5555';       // set proxy
g4api.opt.device = 'ip7';               // set device to iPhone 7
g4api.opt.individual = './profile1/';   // use a specific profile folder
g4api.opt.url = 'site1.com,site2.com';  // set URLs

Once any option is set, it remains set regardless of how many runs are initiated. It is possible to change options while a .run() is progressing, but it will have no effect on the current run.

By default, G4 has the following .opt parameters set:

• .verbose = 0 - no output
• .proxy = 'local' - local connection, no proxy
• .device = 'wdc' - Windows desktop Chrome browser
• .result = true - output result JSON

The .command need only be changed if G4 is not installed globally according to instructions with npm link and chmod, e.g.

g4api.command = 'node ~/guardian4/guardian4.js';

Run options

The .run() method executes G4. It only permits one operation at a time and can be passed two optional parameters:

• a set of URLs in a single string (not necessary if g4api.opt.url or g4api.opt.series has been set)
• a callback function

If set, the callback function is executed when processing completes. It is passed an error and a G4 result object, e.g.

g4api.run(null, (err, g4) => {
  if (!err) console.log( g4.result );
});

If no callback function is set, .run() returns a Promise which either triggers an error or resolves with a G4 result object. This can either be used in an async/await, e.g.

try {
  g4 = await g4api.run();
  console.log(g4.result);
}
catch (e) {}

or a Promise .then chain, e.g.

g4api.run()
  .then(g4 => {
    console.log(g4.result);
  })
  .catch(err => {
    console.log(err);
  })

G4 result object

The .run() method returns an object with two properties:

|property|description| |-:|-| |.result|G4 result JSON parsed into an object (see G4 documentation)| |.stdout|the G4 run output|

Example:

(async () => {

  const g4api = require('guardian4_api');

  try {
    const { result } = await g4api.run('siteurl.com');

    console.log('device    ', result.devicename);
    console.log('proxy     ', result.proxy);
    console.log('log folder', result.log);

    // loop processed URLs
    result.run.forEach((run, rIdx) => {

      console.log('URL     ', rIdx + 1, run.url);
      console.log('complete', run.complete);

      // loop journeys
      run.ad.forEach((ad, aIdx) => {

        console.log('ad           ', aIdx + 1);
        console.log('ad image file', result.log + ad.scrAd);
        console.log('ad log file  ', result.log + ad.log);

        // loop redirects
        ad.journey.forEach((redir, jIdx) => {

          console.log('redirect URL        ', jIdx + 1, redir.url);
          console.log('screenshots captured', redir.src.length);

        });

      });


    })

  }
  catch (e) {
    console.log(e);
  }

})();