oembed.js v1.0.8
oembed.js
oembed.js is a JavaScript implementation of the oEmbed format.
Features
- Fetch oEmbed data for websites
Installing
npm install oembed.js
API
The oembed.js class needs to be initialized with a list of providers. It is
recommended to use the provider list from oEmbed itself: https://oembed.com/providers.json
.
You can also supply your own list or, if you don't want to use the provider lookup,
use an empty array (new oEmbed([])
).
Constructor
The constructor takes two arguments: providers
and an optional config
.
Parameter | Type | Description |
---|---|---|
providers | object[] | An array with the provider syntax (see below) |
config | object | A config object with the config syntax (see below) |
Provider syntax
Asterisks represent a wildcard.
{
"provider_name": "lars.koelker.dev",
"provider_url": "https://lars.koelker.dev",
"endpoints": [
{
"schemes": [
"https:/lars.koelker.dev/*"
],
"url": "https:/lars.koelker.dev/oembed"
}
]
}
Config syntax
Config entry | Type | Description |
---|---|---|
format | string | Response format. Either json (default) or xml . |
maxWidth | number|undefined | Maximum width (defaults to undefined ). |
maxHeight | number|undefined | Maximum height (defaults to undefined ). |
oembedParameters | object | Parameters that will be applied to an endpoint (see syntax below). |
oembedParameters
syntax
Some providers (e.g. Facebook) use parameters that are not defined in the official oEmbed specification. You can supply these by origin here.
{
'<URL_ORIGIN>': { // e.g. 'https://graph.facebook.com'
'<PARAMETER_NAME>': '<PARAMETER_VALUE>' // e.g. 'acess_token': '12|34'
}
}
The <URL_ORIGIN>
should match with the origin of an endpoint url.
For example one of Facebooks endpoints has the url https://graph.facebook.com/v10.0/oembed_post
.
The origin would be https://graph.facebook.com
.
Method async getProviderUrl(url): Promise<string[]>
This method fetches the given url
and checks whether it has a <link rel="alternate">
tag
or link
header for oEmbed data. If a tag or header is found, the method will
return a Promise<string[]>
, otherwise an empty Promise<string[]>
.
This method does not check the providers list.
Method async getData(url, useProviderLookup=true): Promise<object | null>
This method will check the given providers list for the url
host. If the
host is not inside the providers list, the given host of url
will be fetched
and checked for an oEmbed url, if useProviderLookup
is enabled. metaAppId
can
either be specified in the initial config or using the parameter as a fallback.
If no oEmbed url was found, Promise<null>
will be returned, otherwise an Promise<object>
with the fetched data.
Example
The following code will get the oembed data for https://lars.koelker.dev
.
We also supply a maxWidth
and maxHeight
which should be respected by the oEmbed endpoints (https://lars.koelker.dev
doesn't though).
const oEmbed = require("oEmbed.js");
const axios = require("axios");
(async () => {
const providers = await axios.get('https://oembed.com/providers.json');
const oe = new oEmbed(providers.data, {
maxWidth: 420,
maxHeight: 69
});
const response = await oe.getData('https://lars.koelker.dev');
console.log(response);
})()