@vidy/embed
v0.15.1
Published
The JavaScript SDK for Vidy Embeds
Downloads
1,072
Readme
Getting Started
Please check out our Embed Guide 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 to help guide you.
Install
<script src="https://static.vidy.com/embed.min.js"></script>
This registers the
Vidy
constructor globally.
Usage
:bulb: Looking for examples? We got you covered!
Basic Setup
This assumes the text content exists at the time of instantiation.
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.
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! :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 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:
<body>
<div id="app">
<header id="top">
<nav>...</nav>
</header>
<div class="wrapper">
<main id="content">
<article>
<!-- content lives here -->
</article>
<div id="comments">...</div>
</main>
<aside id="sidebar">
<div id="trending-posts">...</div>
<div id="related-posts">...</div>
</aside>
</div>
</div>
</body>
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
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
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
container.
Note: This is called automatically when
options.autoload
is true.
Browser Support
The JavaScript SDK relies on fetch
and 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
andwindow.Promise
are defined.
License
MIT © VIDY