YouTube Widget Documentation

Quick Start Guide

Get your YouTube widget up and running in minutes!

Step 1: Create an Instance

1. Navigate to YouTube Instances from your dashboard
2. Click "Create New Instance"
3. Enter a name for your widget (e.g., "Homepage Videos")
4. Click "Create Instance"

Step 2: Add Video Sources

1. Click "Manage Sources" on your instance
2. Create a video group (e.g., "Latest Updates")
3. Add video sources: YouTube channels, playlists, or individual videos
4. Videos will be automatically fetched and updated

Step 3: Configure Settings

1. Click "Widget Settings"
2. Choose your layout: Grid, List, Featured, Playlist, or Carousel
3. Customize colors, fonts, and display options
4. Save your settings

Step 4: Get Embed Code

1. Click "Embed Code"
2. Choose between Script (recommended) or iFrame
3. Copy the code and paste it into your website
4. Your widget is now live!

Embedding Methods

Method 1: Script Embed (Recommended)

<script src="https://yoursite.com/widgets/youtube-to-website/embed/script/YOUR_IDENTIFIER"></script>
<div id="ytw-YOUR_IDENTIFIER"></div>

Advantages: Better SEO, fully responsive, inherits page styling, faster loading

Method 2: iFrame Embed

<iframe src="https://yoursite.com/widgets/youtube-to-website/embed/iframe/YOUR_IDENTIFIER" 
        width="100%" height="600" frameborder="0"></iframe>

Advantages: Complete style isolation, works everywhere, no JavaScript conflicts

Layout Types

URL Parameters

Override widget settings by adding URL parameters to your embed code.

Layout Parameters

Display Parameters

Theme Parameters

Example Usage

https://yoursite.com/embed/iframe/YOUR_ID?layout_type=list&videos_per_page=10&color_theme=dark_mode

Color Themes

Choose from professionally designed color themes or create your own custom palette.

Pre-Built Themes

Select from 8 carefully crafted themes that work beautifully across all layouts:

Custom Colors

Create your own unique theme by specifying individual color values:

Example: Custom Brand Theme

?color_theme=custom&primary_color=%23FF5733&background_color=%23FFFFFF&text_color=%23333333

Fonts & Typography

Enhance your widget's appearance with professional typography that matches your brand.

Font Categories

Implementation

Specify any Google Font using the font_family parameter:

?font_family=Open+Sans

Font Pairing Suggestions

Typography Best Practices

Advanced Font Customization

Google Fonts are automatically loaded by the widget. To use a custom font:

1. Choose from Google Fonts
2. Copy the font name (spaces encoded as +)
3. Add to your embed URL: font_family=Your+Font+Name

?layout_type=grid&font_family=Poppins&color_theme=ocean_breeze

API Access

Access your videos programmatically with our RESTful API.

Authentication

Include your API key in the X-API-Key header or api_key parameter.

GET /api/instances/{identifier}/videos?api_key=YOUR_API_KEY

API Parameters

Example Response

{
  "videos": [...],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_videos": 100
  }
}

Video Sources

Add videos from multiple sources to your widget.

Supported Source Types

• YouTube Channels: Automatically sync latest videos from any channel
• YouTube Playlists: Display videos from playlists in order
• Individual Videos: Manually curate specific videos
• Video Groups: Organize sources into tabs/categories

Analytics

Track widget performance with built-in analytics.

Metrics Tracked

• Widget Loads: Number of times the widget is displayed
• Video Plays: Number of video plays initiated
• Popular Videos: Most played videos
• Time-based Analytics: Performance over time periods

Examples

Grid Layout with Custom Colors

?layout_type=grid&grid_columns_desktop=4&color_theme=dark_mode

List Layout with Limited Videos

?layout_type=list&videos_per_page=5&show_description=0

Playlist Layout with Custom Font

?layout_type=playlist&font_family=Open+Sans&border_radius=large

Troubleshooting

Widget Not Displaying

Problem: Widget doesn't appear on the page

Solutions:

• Verify the instance is set to Active
• Check that the identifier in embed code is correct
• Ensure JavaScript is enabled in browser
• Check browser console for errors (F12)
• For iFrame: Verify iframe src URL is accessible

Videos Not Loading

Problem: Widget shows but videos are missing

Solutions:

• Verify video sources are added and active
• Check that video groups contain videos
• Ensure videos are public (not private/unlisted)
• Refresh video data from Manage Sources
• Check if YouTube API quota is exceeded

Styling Issues

Problem: Widget looks broken or unstyled

Solutions:

• For Script embed: Check for CSS conflicts
• For iFrame: Ensure proper width/height attributes
• Clear browser cache and reload page
• Try different color theme or layout
• Check if custom CSS is overriding widget styles

Pagination Not Working

Problem: Cannot navigate between pages

Solutions:

• Ensure videos_per_page is less than total videos
• Check JavaScript console for errors
• For iFrame: Try the Script embed method instead
• Verify pagination_type setting is correct

Analytics Not Tracking

Problem: Analytics dashboard shows zero data

Solutions:

• Wait 24 hours for data to populate
• Verify widget is actually embedded and loading
• Check that tracking is not blocked by ad blockers
• Ensure cookies are enabled
• Test widget in different browser

API Not Working

Problem: API requests return errors

Solutions:

• Verify API key is correct and active
• Check API key is included in request header or parameter
• Ensure instance identifier is valid
• Check API endpoint URL is correct
• Review rate limits (max 100 requests/minute)