Using the oEmbed API with Transistor audio embeds
oEmbed is an open format designed to allow embedding content from a website into other pages. Transistor provides an oEmbed endpoint that allows you to easily embed podcast episodes using simple URLs. This guide will walk you through how to use the oEmbed API with Transistor URLs to embed content dynamically.
oEmbed is a specification that allows a website to display embedded content (such as podcasts) when a user posts a link to that resource, without having to parse the resource directly. It returns JSON or XML formatted metadata, providing information necessary to embed the resource into a web page.
Each episode hosted on Transistor has a unique URL, which can be used to retrieve the embedding code.
For example:
https://share.transistor.fm/s/e83b42d0
To embed an episode, you need to construct an oEmbed API request with the episode URL. Here is how you can construct the URL for the API request:
https://share.transistor.fm/oembed?url=https%3A%2F%2Fshare.transistor.fm%2Fs%2Fe83b42d0
Encode the episode URL and append it as a parameter to the oEmbed endpoint. You can use standard URL encoding.
Alternatively, you can also discover the oEmbed URI by searching the document for a <link> element with the type set to application/json+oembed.
Here's an example from this shareable URL:
<link rel="alternate" type="application/json+oembed" title="Paul Jarvis: gaining freedom by building an indie business oEmbed profile" href="https://share.transistor.fm/oembed?url=https%3A%2F%2Fshare.transistor.fm%2Fs%2Fe83b42d0" />
The oEmbed API response will be in JSON format containing the details necessary to embed the episode. Here is an example of a typical oEmbed JSON response:
Use the HTML snippet provided in the html field of the JSON response to embed the episode in your webpage. Simply include the HTML code in the body of your HTML where you want the episode to appear.
To "embed" the player in an HTML email, you'll need to reconstruct the elements in HTML tables.
You can use our HTML email table template here as a starting point:
https://play.tailwindcss.com/xkd95aUaXa
Handling Errors: Always implement error checking in your code to handle situations where the API may be down or URLs are incorrect.
Responsive Design: Since the iframe is responsive, ensure that your site's CSS accommodates it appropriately.
Using the oEmbed API with Transistor is a powerful way to enhance your website or application by embedding rich podcast content directly into your pages. This ensures that your users enjoy a seamless experience while interacting with podcast content hosted on Transistor.
For more details or support, contact our support team.
What is oEmbed?
oEmbed is a specification that allows a website to display embedded content (such as podcasts) when a user posts a link to that resource, without having to parse the resource directly. It returns JSON or XML formatted metadata, providing information necessary to embed the resource into a web page.
How to use the Transistor oEmbed API
Step 1: Obtain the URL of the Episode
Each episode hosted on Transistor has a unique URL, which can be used to retrieve the embedding code.
For example:
https://share.transistor.fm/s/e83b42d0
Step 2: Constructing an Embed URL
To embed an episode, you need to construct an oEmbed API request with the episode URL. Here is how you can construct the URL for the API request:
https://share.transistor.fm/oembed?url=https%3A%2F%2Fshare.transistor.fm%2Fs%2Fe83b42d0
Encode the episode URL and append it as a parameter to the oEmbed endpoint. You can use standard URL encoding.
Alternatively, you can also discover the oEmbed URI by searching the document for a <link> element with the type set to application/json+oembed.
Here's an example from this shareable URL:
<link rel="alternate" type="application/json+oembed" title="Paul Jarvis: gaining freedom by building an indie business oEmbed profile" href="https://share.transistor.fm/oembed?url=https%3A%2F%2Fshare.transistor.fm%2Fs%2Fe83b42d0" />
Step 3: Understanding the Response
The oEmbed API response will be in JSON format containing the details necessary to embed the episode. Here is an example of a typical oEmbed JSON response:
{
"type": "rich",
"version": "1.0",
"provider_name": "Transistor",
"provider_url": "https://transistor.fm",
"author_name": "Build Your SaaS",
"title": "Paul Jarvis: gaining freedom by building an indie business",
"html": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/e83b42d0\"></iframe>",
"width": "100%",
"height": 180,
"duration": 4303,
"description": "Justin catches up with his old internet friend Paul Jarvis...",
"thumbnail_url": "https://img.transistor.fm/gPFfoSoi...",
"thumbnail_width": 300,
"thumbnail_height": 300
}Step 4: Embedding the Episode
In a standard web page
Use the HTML snippet provided in the html field of the JSON response to embed the episode in your webpage. Simply include the HTML code in the body of your HTML where you want the episode to appear.
In an HTML email
To "embed" the player in an HTML email, you'll need to reconstruct the elements in HTML tables.
You can use our HTML email table template here as a starting point:
https://play.tailwindcss.com/xkd95aUaXa
Example
Best Practices
Handling Errors: Always implement error checking in your code to handle situations where the API may be down or URLs are incorrect.
Responsive Design: Since the iframe is responsive, ensure that your site's CSS accommodates it appropriately.
Conclusion
Using the oEmbed API with Transistor is a powerful way to enhance your website or application by embedding rich podcast content directly into your pages. This ensures that your users enjoy a seamless experience while interacting with podcast content hosted on Transistor.
For more details or support, contact our support team.
Updated on: 24/06/2024
Thank you!