@vidy/embed

v0.15.1

Published

2 years ago

The JavaScript SDK for Vidy Embeds

Downloads

2,027

0High
0Medium
0Low

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 and window.Promise are defined.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme