The JavaScript SDK for Vidy Embeds
## Getting Started
Please check out our [Embed Guide](Embed-Tutorial-Guide.md) for a complete tutorial for installing the Vidy SDK on your website, registering an account, and embedding Vidys into your website. You will also find comprehensive explanations for what `appid` and `postid` mean, as well as how to find them!
We also have a number of [SDK example integrations](https://github.com/VIDY/embed-web-examples) to help guide you.
## Install
```html
```
> This registers the `Vidy` constructor globally.
## Usage
:bulb: Looking for examples? [We got you covered](https://github.com/VIDY/embed-web-examples)!
***Basic Setup***
_This assumes the text content exists at the time of instantiation._
```js
let vidy = new Vidy({
appid: '2199e8c8-abcd-efgh-a123-d463129790c5',
postid: location.pathname, //=> eg "hello-world"
content: '#article',
autoload: true
});
```
***Dynamic Setup — AKA, no autoload***
_When text is rendered dynamically / after script execution._
```js
let selector = '#article';
let div = document.querySelector(selector);
let pathname = location.pathname; //=> eg "hello-world"
let vidy = new Vidy({
appid: '2199e8c8-abcd-efgh-a123-d463129790c5',
postid: pathname,
content: selector
});
// Query our own Blog API for JSON
fetch(`/api/posts/${pathname}`).then(r => r.json()).then(data => {
// Add text to the container we care about!
div.innerHTML = data.html;
// Manually call load()
vidy.load();
});
```
## API
### Vidy(options)
Returns: `Vidy`
Returns the `Vidy` instance.
#### options.appid
Type: `String`
Required: `true`
The Application identifier.
> You may create a new Vidy Application for free [here](#todo)! :tada:
#### options.postid
Type: `String|Number`
Required: `true`
The unique identifier for any given page.
Most web frameworks have built-in helpers to generate & ensure unique page identifiers; see [some examples](https://github.com/VIDY/embed-web-examples) for help. You may also resort to using the `location.pathname`, if necessary.
> **Important:** This should be immutable; each `postid` yields its own specific list of Vidy Embeds!
#### options.content
Type: `String`
Default: `'body'`
The selector of the parent container that wraps the text content Vidy should traverse.
For example, given the following markup:
```html
```
By default, the Vidy SDK will grab ***all text*** on the page, including comments, related & trending post widgets, etc. You _probably_ don't want the SDK placing links in these areas.
Instead, you could pass `content: '#content'`, targeting the article _and_ the comments' text; or you can narrow link placements within the article exclusively via the `'#content > article'` selector.
#### options.autoload
Type: `Boolean`
Default: `false`
Whether or not the SDK should immediately draw link around text phrases.
If the text within [`options.content`](#optionscontent) is loaded dynamically (e.g., via an API or a headless CMS), then `autoload` should retain the `false` default.
> **Important:** This should _only_ be `true` if your content is included in the server response!
### init(postid)
The method that appends the SDK elements to the page, if they don't already exist. It also queries the Vidy API for the list of Embeds (both social & advertising) that belong to the given `postid`.
If no `postid` is received, the SDK uses the value provided on instantiation — see [`options.postid`](#optionspostid) for more.
You should only need to invoke this method after successfully navigating to a new page on a client-side application.
> **Note:** This is always called automatically when creating a new `Vidy` instance.
### load()
The method that draws Vidy links around their relevant phrases.
At this point, the SDK expects and traverses text content within the [`options.content`](#optionscontent) container.
> **Note:** This is called automatically when [`options.autoload`](#optionsautoload) is true.
## Browser Support
The JavaScript SDK relies on [`fetch`](https://caniuse.com/#search=fetch) and [`Promise`](https://caniuse.com/#search=promise) support, which yields these minimum browsers:
* Edge 14+
* Firefox 40+
* Chrome 42+
* Safari 10.1+
* iOS 10.3+
The SDK will automatically download polyfills for `fetch` and `Promise` if it does not detect these globals.
> **Note:** To use the polyfills you already provide, ensure that `window.fetch` and `window.Promise` are defined.
## License
MIT © [VIDY](https://vidy.com)
