Skip to content

Commit

Permalink
Merge pull request #458 from dailymotion/modularization
Browse files Browse the repository at this point in the history
Modularization
  • Loading branch information
Rapha0511 authored Jun 27, 2024
2 parents 0feaaeb + c1c8b42 commit 37d5ac4
Show file tree
Hide file tree
Showing 67 changed files with 11,456 additions and 4,364 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
node_modules/*
npm-debug.log
dist_old
examples/node_modules/*
examples/.parcel-cache/*
examples/dist/*
39 changes: 30 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ This library provides three components:
For the full API documentation go [here](#api).
For the full Class reference go [here](https://github.com/dailymotion/vast-client-js/blob/master/docs/api/class-reference.md)

Complies with the [VAST 4.2 specification](https://iabtechlab.com/wp-content/uploads/2019/06/VAST_4.2_final_june26.pdf) provided by the [Interactive Advertising Bureau (IAB)](https://www.iab.com/).
To explore a practical example of how the vast client can be implemented, please visit this [link](https://githubbox.com/dailymotion/vast-client-js/tree/master/examples).

Complies with the [VAST 4.3 specification](https://iabtechlab.com/wp-content/uploads/2022/09/VAST_4.3.pdf) provided by the [Interactive Advertising Bureau (IAB)](https://www.iab.com/).

## Get Started

Expand All @@ -29,7 +31,7 @@ Then import the components you need.

### VASTClient

If you need to fetch and parse VAST documents, you can use the **VASTClient**:
If you need to fetch and parse VAST documents, you can use the `get` method from the **VASTClient**:

```javascript
import { VASTClient } from '@dailymotion/vast-client'
Expand All @@ -47,9 +49,25 @@ vastClient.get('https://www.examplevast.com/vast.xml')

In addition to fetching and parsing a VAST resource, **VASTClient** provides options to filter a sequence of calls based on count and time of execution, together with the possibility to track URLs using **VASTTracker**.

If you need to directly parse a VAST XML and also follow any wrappers chain, you can use the `parseVAST` method from the **VASTClient** :

```javascript
import { VASTClient } from '@dailymotion/vast-client'

const vastClient = new VASTClient();

vastClient.parseVAST(vastXml)
.then(parsedVAST => {
// Do something with the parsed VAST response
})
.catch(err => {
// Deal with the error
});
```
### VASTParser

To directly parse a VAST XML you can use the **VASTParser**:
The **VASTParser** will make no fetching, the final response will only contain the first VAST encountered.

```Javascript
import { VASTParser } from '@dailymotion/vast-client'
Expand Down Expand Up @@ -110,18 +128,21 @@ const vastTracker = new VASTTracker();

#### Browser script

A pre-bundled version of VAST Client JS is available: [`vast-client-browser.min.js`](dist/vast-client-browser.min.js) [minified].
A pre-bundled version of VAST Client JS is available: [`vast-client.min.js`](dist/vast-client.min.js) [minified].

You can add the script directly to your page and access the library's components through the `VAST` object.
To use it, either host it on your CDN or locally in your project. If you're using a script tag make sure to set the type property to module like below.

_your index.html_
```html
<script src="vast-client-browser.min.js"></script>
<script type="module" src="your-main-file.js"></script>
```

_main.js_
```javascript
const vastClient = new VAST.VASTClient();
const vastParser = new VAST.VASTParser();
const vastTracker = new VAST.VASTTracker();
import {VASTClient, VASTParser, VASTTracker} from "vast-client.min.js"

const vastClient = new VASTClient();
const vastParser = new VASTParser();
const vastTracker = new VASTTracker();
```

#### Node
Expand Down
6 changes: 4 additions & 2 deletions bundle_size.js
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
const fs = require('fs');
const path = require('path');

const newDistPath = './dist';
const oldDistPath = './dist_old';

const getFileSizes = (folderPath) => {
return fs.readdirSync(folderPath).reduce((res, fileName) => {
res[fileName] = fs.readFileSync(path.join(folderPath, fileName)).byteLength;
const stats = fs.statSync(`${folderPath}/${fileName}`);
if (stats.isFile()) {
res[fileName] = stats.size;
}
return res;
}, {});
};
Expand Down
1 change: 0 additions & 1 deletion dist/vast-client-browser.min.js

This file was deleted.

127 changes: 126 additions & 1 deletion docs/api/vast-client.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# VASTClient

The `VASTClient` class provides a client to manage the fetching and parsing of VAST documents.
The `VASTClient` class provides a client to manage the fetching and parsing of VAST documents. It provides methods for fetching VAST resources by resolving the wrapper chain (recursive fetching and parsing) by using the `VASTParser` parsing methods.

- [Constructor](#constructor)
- [Properties](#properties)
Expand Down Expand Up @@ -147,6 +147,62 @@ vastClient.get('http://example.dailymotion.com/vast.xml', options)
// Deal with the error
});
```
### parseVAST(vastXml, options)<a name="parse"></a>

Parses the given xml Object into a [VASTResponse](https://github.com/dailymotion/vast-client-js/blob/master/docs/api/class-reference.md#vastresponse).
Returns a `Promise` which either resolves with the fully parsed `VASTResponse` or rejects with an `Error`.

By using this method, you will be able to perform fetching in case you want to parse a VAST document and follow a wrappers chain.
If you just need to parse an inline VAST or you want to parse the first VAST document encountered, you should use the **parseVAST** method from the **VASTParser**.

#### Parameters

- **`vastXml: Object`** - An object representing an xml document
- **`options: Object`** - An optional Object of parameters to be used in the parsing process
- `timeout: Number` - A custom timeout for the possible wrapper resolving requests (default `120000`)
- `withCredentials: Boolean` - A boolean to enable the withCredentials options for the XHR URLHandler (default `false`)
- `wrapperLimit: Number` - A number of Wrapper responses that can be received with no InLine response (default `10`)
- `urlHandler: URLHandler` - Custom urlhandler to be used instead of the default ones [`urlhandlers`](../../src/urlhandlers)
- `urlhandler: URLHandler` - Fulfills the same purpose as `urlHandler`, which is the preferred parameter to use
- `allowMultipleAds: Boolean` - A boolean value that identifies whether multiple ads are allowed in the requested VAST response. This will override any value of allowMultipleAds attribute set in the VAST
- `followAdditionalWrappers: Boolean` - A boolean value that identifies whether subsequent Wrappers after a requested VAST response is allowed. This will override any value of followAdditionalWrappers attribute set in the VAST
- `requestDuration: Number` - The fetching time of the XML in ms. Provide it with byteLength to have a more accurate estimated bitrate.
- `byteLength: Number`- The size of the request in bytes. Provide it with requestDuration to have a more accurate estimated bitrate.

#### Events emitted

- **`VAST-resolved`**
- **`VAST-resolving`**
- **`VAST-warning`**

#### Example

```Javascript
const vastXml = (new window.DOMParser()).parseFromString(xmlStr, "text/xml");

vastParser.parseVAST(vastXml)
.then(res => {
// Do something with the parsed VAST response
})
.catch(err => {
// Deal with the error
});

// Or with some options
const options = {
timeout: 5000,
withCredentials: true,
wrapperLimit: 7
}
vastParser.parseVAST(vastXml, options)
.then(res => {
// Do something with the parsed VAST response
})
.catch(err => {
// Deal with the error
});
```


#### How does resolveAll work

Expand Down Expand Up @@ -304,3 +360,72 @@ const vastParser = vastClient.getParser();
// Clear the url template filters used
vastParser.clearUrlTemplateFilters();
```

### addURLTemplateFilter(filter)

Adds a filter function to the array of filters which are called before fetching a VAST document.

#### Parameters

- **`filter: function`** - The filter function to be added at the end of the array

#### Example

```Javascript
vastClient.addURLTemplateFilter( vastUrl => {
return url.replace('[DOMAIN]', 'mywebsite.com')
});

/*
For a VASTAdTagURI defined as :
<VASTAdTagURI>http://example.dailymotion.com/vast.php?domain=[DOMAIN]</VASTAdTagURI>
HTTP request will be:
http://example.dailymotion.com/vast.php?domain=mywebsite.com
*/
```

### removeLastURLTemplateFilter()

Removes the last element of the url templates filters array.

#### Example

```Javascript
const replaceDomain = () => {
return url.replace('[DOMAIN]', 'mywebsite.com')
};

vastClient.addURLTemplateFilter(replaceDomain);
// ...
vastClient.removeURLTemplateFilter(replaceDomain);
// [DOMAIN] placeholder is no longer replaced
```
### countURLTemplateFilters()

Returns the number of filters of the url templates filters array.

#### Example

```Javascript
vastClient.addURLTemplateFilter( vastUrl => {
return url.replace('[DOMAIN]', 'mywebsite.com')
});

vastClient.countUrlTemplateFilters();
// returns 1
```

### clearURLTemplateFilters()

Removes all the filter functions from the url templates filters array.

#### Example

```Javascript
vastClient.addURLTemplateFilter( vastUrl => {
return url.replace('[DOMAIN]', 'mywebsite.com')
});

vastClient.clearUrlTemplateFilters();
// [DOMAIN] placeholder is no longer replaced
```
Loading

0 comments on commit 37d5ac4

Please sign in to comment.