# Pixabay Media Search Plugin for Bubble - Complete Documentation

## Table of Contents
1. [Introduction](#introduction)
2. [How It Works](#how-it-works)
3. [Key Features](#key-features)
4. [Installation and Setup](#installation-and-setup)
5. [Configuration Guide](#configuration-guide)
6. [Plugin Elements](#plugin-elements)
7. [Exposed States](#exposed-states)
8. [Workflow Integration](#workflow-integration)
9. [Video Player Integration](#video-player-integration)
10. [Use Cases](#use-cases)
11. [Best Practices](#best-practices)
12. [Troubleshooting](#troubleshooting)
13. [API Limits and Performance](#api-limits-and-performance)
14. [Support](#support)

---

## Introduction

The **Pixabay Media Search Plugin for Bubble** is a comprehensive solution that enables Bubble developers to seamlessly integrate Pixabay's vast library of over 2.8 million royalty-free images and videos directly into their applications. This plugin eliminates the complexity of API integration while providing advanced features like intelligent caching, dynamic filtering, and professional video playback capabilities.

### What is Pixabay?

Pixabay is one of the world's largest repositories of free stock photos, illustrations, vectors, and videos. All content is released under Pixabay's license, making it safe for commercial use without attribution requirements (though attribution is appreciated).

### Why Use This Plugin?

- **No API Coding Required**: Direct integration without backend development
- **Advanced Video Player**: Built-in Video.js player with customizable controls
- **Performance Optimized**: Intelligent caching and lazy loading
- **Comprehensive Filtering**: 20+ categories and advanced search parameters
- **Mobile Responsive**: Optimized for all device types
- **Real-time Updates**: Dynamic content loading with pagination support

---

## How It Works

### Architecture Overview

The plugin operates through a multi-layered architecture:

1. **Frontend Interface**: Bubble elements that users interact with
2. **API Integration Layer**: Secure communication with Pixabay's REST API
3. **Caching System**: Intelligent storage to minimize API calls
4. **Video Player Engine**: Video.js integration for seamless playback
5. **State Management**: Real-time exposure of data to Bubble workflows

### Data Flow

1. **Search Initiation**: User configures search parameters
2. **API Request**: Plugin sends authenticated request to Pixabay
3. **Data Processing**: Results are parsed and optimized
4. **Cache Storage**: Data is intelligently cached for performance
5. **State Exposure**: Results are exposed as Bubble states
6. **UI Update**: Bubble elements display the content dynamically

### Security

- API keys are securely handled and never exposed to client-side
- All requests use HTTPS encryption
- Rate limiting prevents API abuse
- Error handling ensures application stability

---

## Key Features

### 🔍 Advanced Search Capabilities
- **Multi-type Search**: Photos, illustrations, vectors, and videos
- **Category Filtering**: 20+ predefined categories
- **Orientation Control**: Landscape, portrait, or square
- **Size Filtering**: Minimum width and height requirements
- **Color Preferences**: Specific color palette filtering
- **Language Support**: Multi-language search capabilities
- **Safety Filters**: Content moderation options

### 🎬 Professional Video Player
- **Video.js Integration**: Industry-standard HTML5 video player
- **Customizable Controls**: Play, pause, volume, fullscreen, seek
- **Autoplay Support**: Configurable autoplay with mute options
- **Loop Functionality**: Seamless video looping
- **Responsive Design**: Automatic scaling for all screen sizes
- **Poster Images**: Custom thumbnail support
- **Mobile Optimized**: Touch-friendly controls

### ⚡ Performance Optimization
- **Intelligent Caching**: Reduces API calls and improves speed
- **Lazy Loading**: Content loads as needed
- **Prefetching**: Anticipates user needs
- **Bandwidth Optimization**: Efficient resource usage
- **Error Recovery**: Graceful handling of network issues

### 🔧 Developer-Friendly Integration
- **Exposed States**: Real-time data access
- **Workflow Integration**: Seamless Bubble workflow support
- **Dynamic Content**: Live content updates
- **Metadata Access**: Complete media information
- **Pagination Support**: "Load more" functionality

---

## Installation and Setup

### Step 1: Install the Plugin

1. Navigate to your Bubble application's **Plugin** tab
2. Click **Add plugins**
3. Search for "Pixabay Media Search Plugin for Bubble"
4. Click **Install** and wait for installation to complete

### Step 2: Obtain Pixabay API Key

1. Visit [Pixabay.com](https://pixabay.com) and create a free account
2. Navigate to [Pixabay API Documentation](https://pixabay.com/api/docs/)
3. Copy your unique API key from the documentation page
4. Store this key securely - you'll need it for configuration

### Step 3: Add Plugin Elements

1. In your Bubble page editor, drag the **Pixabay Media Search** element onto your page
2. For video functionality, also add the **Pixabay Video Player** element
3. Position and size elements according to your design requirements

---

## Configuration Guide

### Basic Configuration

#### API Key Setup
```
Property: api_key_pixabay
Type: Text
Required: Yes
Description: Your unique Pixabay API key
```

#### Search Parameters
```
Property: search_term
Type: Text
Description: Keywords for media search
Example: "nature landscape mountains"

Property: search_type
Type: Option set
Options: photo, illustration, vector, video
Default: photo

Property: category
Type: Option set
Options: backgrounds, fashion, nature, science, education, feelings, health, people, religion, places, animals, industry, computer, food, sports, transportation, travel, buildings, business, music
Default: all

Property: results_per_page
Type: Number
Range: 3-200
Default: 20
```

#### Filtering Options
```
Property: orientation
Type: Option set
Options: all, horizontal, vertical
Default: all

Property: min_width
Type: Number
Description: Minimum image width in pixels
Default: 0

Property: min_height
Type: Number
Description: Minimum image height in pixels
Default: 0

Property: colors
Type: Option set
Options: grayscale, transparent, red, orange, yellow, green, turquoise, blue, lilac, pink, white, gray, black, brown
Default: all

Property: language
Type: Option set
Options: cs, da, de, en, es, fr, id, it, hu, nl, no, pl, pt, ro, sk, fi, sv, tr, vi, th, bg, ru, el, ja, ko, zh
Default: en
```

#### Performance Settings
```
Property: enable_caching
Type: Yes/No
Default: Yes
Description: Enable intelligent caching

Property: prefetch_next_page
Type: Yes/No
Default: Yes
Description: Preload next page for smoother experience

Property: lazy_loading
Type: Yes/No
Default: Yes
Description: Load content as needed
```

### Video Player Configuration

#### Playback Settings
```
Property: autoplay
Type: Yes/No
Default: No
Description: Auto-start video playback

Property: loop
Type: Yes/No
Default: No
Description: Loop video continuously

Property: muted
Type: Yes/No
Default: No
Description: Start video muted

Property: controls
Type: Yes/No
Default: Yes
Description: Show player controls
```

#### Display Settings
```
Property: poster
Type: Text
Description: URL for poster image
Note: If empty, uses video thumbnail

Property: responsive
Type: Yes/No
Default: Yes
Description: Enable responsive scaling

Property: fluid
Type: Yes/No
Default: Yes
Description: Fill container width
```

---

## Plugin Elements

### Pixabay Media Search Element

This is the main search interface element that handles media discovery and display.

#### Visual Properties
- **Width**: Adjustable container width
- **Height**: Adjustable container height
- **Background**: Customizable background color
- **Border**: Border styling options
- **Margin/Padding**: Spacing controls

#### Functional Properties
- **Search Configuration**: All search and filtering parameters
- **Display Options**: Grid layout, thumbnail sizes
- **Interaction Settings**: Click behaviors, selection modes
- **Loading States**: Progress indicators and placeholders

### Pixabay Video Player Element

Dedicated video player for seamless video content playback.

#### Player Features
- **Video.js Framework**: Professional HTML5 video player
- **Custom Controls**: Branded control interface
- **Responsive Design**: Automatic sizing and scaling
- **Touch Support**: Mobile-optimized interactions
- **Keyboard Shortcuts**: Standard video player shortcuts

#### Configuration Options
- **Player Theme**: Pixabay-branded styling
- **Control Layout**: Customizable control positioning
- **Interaction Modes**: Click-to-play, hover behaviors
- **Quality Selection**: Automatic quality adjustment

---

## Exposed States

### Media Results States

#### Image Results
```
State: image_results
Type: List of Texts
Description: URLs of image results
Usage: Data source for repeating groups

State: image_thumbnails
Type: List of Texts
Description: Thumbnail URLs for preview
Usage: Quick loading preview images

State: image_tags
Type: List of Texts
Description: Comma-separated tags for each image
Usage: Content categorization and filtering

State: image_resolutions
Type: List of Texts
Description: Available resolutions (small, medium, large, original)
Usage: Quality selection and optimization
```

#### Video Results
```
State: video_results
Type: List of Texts
Description: URLs of video files
Usage: Data source for video players

State: video_thumbnails
Type: List of Texts
Description: Video preview thumbnails
Usage: Video selection and preview

State: video_durations
Type: List of Numbers
Description: Video duration in seconds
Usage: Display and filtering

State: video_sizes
Type: List of Texts
Description: Video dimensions (width x height)
Usage: Layout planning and responsive design
```

#### Metadata States
```
State: photographer_names
Type: List of Texts
Description: Content creator names
Usage: Attribution and crediting

State: media_ids
Type: List of Numbers
Description: Unique Pixabay media IDs
Usage: Reference and tracking

State: view_counts
Type: List of Numbers
Description: View statistics
Usage: Popularity indicators

State: download_counts
Type: List of Numbers
Description: Download statistics
Usage: Popularity metrics
```

### Pagination States
```
State: current_page
Type: Number
Description: Currently displayed page number
Usage: Pagination controls

State: total_results
Type: Number
Description: Total available results
Usage: Result counters and pagination

State: has_more_results
Type: Yes/No
Description: Whether more results are available
Usage: "Load more" button visibility

State: results_per_page
Type: Number
Description: Number of results per page
Usage: Grid layout calculations
```

### Status States
```
State: is_loading
Type: Yes/No
Description: Whether API request is in progress
Usage: Loading indicators

State: error_message
Type: Text
Description: Error description if request fails
Usage: Error handling and user feedback

State: last_search_term
Type: Text
Description: Most recent search query
Usage: Search history and state management

State: api_quota_remaining
Type: Number
Description: Remaining API calls for current hour
Usage: Usage monitoring and rate limiting
```

### Video Player States
```
State: video_ready
Type: Yes/No
Description: Whether video player is initialized
Usage: Player state management

State: video_playing
Type: Yes/No
Description: Whether video is currently playing
Usage: Play/pause button states

State: video_current_time
Type: Number
Description: Current playback position in seconds
Usage: Progress bars and time displays

State: video_duration
Type: Number
Description: Total video duration in seconds
Usage: Progress calculations

State: video_volume
Type: Number
Description: Current volume level (0-1)
Usage: Volume controls

State: video_muted
Type: Yes/No
Description: Whether video is muted
Usage: Mute button states
```

---

## Workflow Integration

### Search Workflows

#### Triggering a Search
```
Workflow: User clicks search button
Action: Set state
Element: Pixabay Search Element
Property: search_term
Value: Input's value

Additional Actions:
- Set search_type based on user selection
- Set category filter
- Set orientation preference
- Reset current_page to 1
```

#### Handling Search Results
```
Workflow: When search completes
Condition: Pixabay Search Element's is_loading is "no"
Actions:
1. Make visible: Results repeating group
2. Set data source: Pixabay Search Element's image_results
3. Hide: Loading spinner
4. Show/Hide: "Load more" button based on has_more_results
```

### Pagination Workflows

#### Load More Functionality
```
Workflow: User clicks "Load More"
Actions:
1. Set state: load_more = "yes"
2. Show: Loading indicator
3. When load completes:
   - Append new results to existing list
   - Update pagination states
   - Hide loading indicator
```

#### Page Navigation
```
Workflow: User clicks page number
Actions:
1. Set state: current_page = clicked page number
2. Trigger new search with updated page
3. Update pagination display
4. Scroll to top of results
```

### Selection Workflows

#### Image Selection
```
Workflow: User clicks on image in repeating group
Actions:
1. Set custom state: selected_image_url = Current cell's image URL
2. Set custom state: selected_image_metadata = Current cell's metadata
3. Navigate to detail page OR
4. Show popup with image details OR
5. Add to favorites/cart
```

#### Bulk Selection
```
Workflow: User selects multiple images
Actions:
1. Add to custom list: selected_images
2. Update selection counter
3. Show bulk action buttons
4. Enable download/save all functionality
```

### Video Workflows

#### Video Selection and Playback
```
Workflow: User selects video
Actions:
1. Set Pixabay Video Player's video_url = Selected video URL
2. Set poster image = Video thumbnail
3. Configure player settings (autoplay, loop, etc.)
4. Show video player element
5. Track analytics (optional)
```

#### Video Player Events
```
Workflow: Video starts playing
Trigger: When Pixabay Video Player's video_playing is "yes"
Actions:
- Update UI to show playing state
- Start analytics tracking
- Pause other media if needed

Workflow: Video ends
Trigger: When Pixabay Video Player's video_current_time equals video_duration
Actions:
- Show replay options
- Suggest related videos
- Update view statistics
```

---

## Video Player Integration

### Basic Video Setup

#### Single Video Display
```html
<!-- In your Bubble page -->
1. Add Pixabay Video Player element
2. Set initial properties:
   - video_url: URL from search results
   - poster: Thumbnail from search results
   - controls: Yes
   - responsive: Yes
```

#### Video Gallery
```
1. Use Repeating Group with video_results as data source
2. Each cell contains:
   - Thumbnail image (video_thumbnails)
   - Play button overlay
   - Video metadata (duration, resolution)
3. On click: Load video in main player
```

### Advanced Video Features

#### Custom Controls
```javascript
// Custom play/pause button
Workflow: Custom play button clicked
Condition: Video is not playing
Action: Set video_playing = "yes"

Workflow: Custom pause button clicked  
Condition: Video is playing
Action: Set video_playing = "no"
```

#### Progress Tracking
```javascript
// Custom progress bar
Display: Progress bar width = (video_current_time / video_duration) * 100%
Interaction: User drags progress bar
Action: Set video_current_time = (clicked position / bar width) * video_duration
```

#### Volume Control
```javascript
// Custom volume slider
Display: Volume slider position = video_volume * 100%
Interaction: User adjusts volume
Action: Set video_volume = slider position / 100
```

### Video Player Events

#### Player Lifecycle
```
On video_ready = "yes":
- Show player controls
- Enable user interactions
- Start preloading if configured

On video_playing changes:
- Update play/pause button states
- Start/stop progress tracking
- Handle analytics events

On video ends:
- Reset to beginning OR
- Show replay options OR
- Load next video in playlist
```

#### Error Handling
```
On video error:
- Show error message to user
- Log error for debugging
- Offer alternative video sources
- Fallback to image display
```

---

## Use Cases

### 1. Content Management Systems

**Scenario**: Blog platform needing stock images for articles

**Implementation**:
- Integrate search element in article editor
- Allow authors to search by keyword and category
- Provide image selection and insertion workflow
- Automatically handle attribution and licensing

**Benefits**:
- Streamlined content creation
- Professional-quality visuals
- No licensing concerns
- Improved article engagement

### 2. Social Media Platforms

**Scenario**: Social network requiring media content for posts

**Implementation**:
- Embed search in post creation flow
- Enable image and video selection
- Provide real-time preview
- Support multiple media per post

**Benefits**:
- Enhanced user-generated content
- Increased platform engagement
- Professional content quality
- Reduced copyright issues

### 3. E-commerce Applications

**Scenario**: Online store needing product lifestyle images

**Implementation**:
- Category-specific image search
- Lifestyle and context imagery
- Product demonstration videos
- Seasonal content updates

**Benefits**:
- Improved product presentation
- Higher conversion rates
- Reduced photography costs
- Dynamic content updates

### 4. Educational Platforms

**Scenario**: Learning management system requiring educational media

**Implementation**:
- Subject-specific image searches
- Educational video content
- Illustration and diagram access
- Multi-language support

**Benefits**:
- Enhanced learning materials
- Visual learning support
- Cost-effective content sourcing
- Diverse media types

### 5. Marketing Websites

**Scenario**: Marketing agency creating campaign materials

**Implementation**:
- Campaign-specific media search
- High-resolution image access
- Video content for social media
- Brand-aligned visual selection

**Benefits**:
- Professional campaign assets
- Rapid content creation
- Consistent visual quality
- Cost-effective production

### 6. News and Media Websites

**Scenario**: News platform requiring timely visual content

**Implementation**:
- Breaking news image search
- Topic-specific media discovery
- Real-time content updates
- Mobile-optimized delivery

**Benefits**:
- Timely visual content
- Professional journalism standards
- Reduced licensing complexity
- Mobile-first delivery

---

## Best Practices

### Performance Optimization

#### Caching Strategy
```
1. Enable caching for repeated searches
2. Set appropriate cache duration (recommended: 1 hour)
3. Implement cache warming for popular searches
4. Monitor cache hit rates and adjust accordingly
```

#### API Usage Optimization
```
1. Use specific search terms to reduce result volume
2. Implement search debouncing (wait 500ms after user stops typing)
3. Batch related requests when possible
4. Monitor API quota usage and implement warnings
```

#### Loading Performance
```
1. Enable lazy loading for large result sets
2. Use thumbnail images for initial display
3. Implement progressive loading for full-resolution images
4. Preload next page when user approaches end of current page
```

### User Experience

#### Search Interface Design
```
1. Provide clear search input with placeholder text
2. Implement auto-complete for common search terms
3. Show search suggestions based on categories
4. Display search filters in an intuitive layout
```

#### Result Display
```
1. Use grid layout for optimal space utilization
2. Show loading states during API requests
3. Implement smooth transitions between result pages
4. Provide clear "no results" messaging
```

#### Mobile Optimization
```
1. Ensure touch-friendly interface elements
2. Optimize grid layout for mobile screens
3. Implement swipe gestures for navigation
4. Use appropriate thumbnail sizes for mobile viewing
```

### Error Handling

#### API Error Management
```
1. Implement retry logic for temporary failures
2. Show user-friendly error messages
3. Provide fallback content when possible
4. Log errors for debugging and monitoring
```

#### Network Error Handling
```
1. Detect network connectivity issues
2. Show offline indicators when appropriate
3. Cache results for offline viewing
4. Implement graceful degradation
```

### Security Considerations

#### API Key Protection
```
1. Never expose API keys in client-side code
2. Use Bubble's secure storage for sensitive data
3. Implement API key rotation policies
4. Monitor for unauthorized usage
```

#### Content Safety
```
1. Enable Pixabay's safe search filters
2. Implement content moderation workflows
3. Provide user reporting mechanisms
4. Comply with platform content policies
```

---

## Troubleshooting

### Common Issues

#### Search Returns No Results
**Symptoms**: Empty result set despite valid search terms
**Causes**:
- Overly restrictive filters
- Invalid API key
- Rate limit exceeded
- Network connectivity issues

**Solutions**:
1. Verify API key is correct and active
2. Check current API quota usage
3. Broaden search parameters
4. Test network connectivity
5. Review Bubble application logs

#### Video Player Not Loading
**Symptoms**: Video element shows but doesn't play content
**Causes**:
- Invalid video URL
- Browser compatibility issues
- Video.js library not loaded
- CORS policy restrictions

**Solutions**:
1. Verify video URL is accessible
2. Check browser console for errors
3. Ensure Video.js library is loaded
4. Test in different browsers
5. Verify video format compatibility

#### Slow Performance
**Symptoms**: Long loading times, delayed responses
**Causes**:
- Poor network connectivity
- Large result sets
- Disabled caching
- Inefficient filtering

**Solutions**:
1. Enable intelligent caching
2. Reduce results per page
3. Implement lazy loading
4. Optimize search parameters
5. Monitor API response times

#### Images Not Displaying
**Symptoms**: Broken image links or loading failures
**Causes**:
- HTTPS/HTTP protocol mismatch
- Image URL expiration
- Browser caching issues
- Network restrictions

**Solutions**:
1. Ensure HTTPS URLs are used
2. Clear browser cache
3. Test image URLs directly
4. Check network restrictions
5. Verify image format support

### Debug Mode

#### Enabling Debug Information
```
1. Set custom state: debug_mode = "yes"
2. Show debug panel with:
   - Current API quota
   - Last request details
   - Cache status
   - Error logs
```

#### Monitoring API Usage
```
1. Track daily API call count
2. Monitor response times
3. Log error frequencies
4. Analyze popular search terms
```

### Performance Monitoring

#### Key Metrics to Track
```
1. Average search response time
2. Cache hit ratio
3. API quota utilization
4. User engagement metrics
5. Error frequency rates
```

#### Optimization Targets
```
1. Search response time: < 2 seconds
2. Cache hit ratio: > 80%
3. API quota usage: < 80% of limit
4. Error rate: < 5%
5. User session duration: Track and optimize
```

---

## API Limits and Performance

### Pixabay API Limits

#### Rate Limiting
```
Free Account:
- 5,000 requests per hour
- No daily limit
- Standard rate limiting applies

Commercial Usage:
- Contact Pixabay for higher limits
- Enhanced API features available
- Priority support included
```

#### Request Optimization
```
1. Batch related searches when possible
2. Use caching to reduce repeated requests
3. Implement request queuing for high-traffic scenarios
4. Monitor quota usage and implement warnings at 80% capacity
```

### Performance Benchmarks

#### Target Response Times
```
Search Request: < 1.5 seconds
Image Loading: < 3 seconds
Video Loading: < 5 seconds
Cache Retrieval: < 0.5 seconds
```

#### Optimization Strategies
```
1. CDN utilization for static assets
2. Image compression and optimization
3. Progressive loading implementation
4. Background prefetching
```

### Monitoring and Analytics

#### Usage Tracking
```
1. Search frequency analysis
2. Popular content identification
3. User behavior patterns
4. Performance bottleneck detection
```

#### Optimization Opportunities
```
1. Preload popular content
2. Optimize frequent search patterns
3. Implement smart caching strategies
4. Enhance user experience based on usage data
```

---

## Support

### Documentation Resources

#### Quick Start Guides
- [Basic Setup Tutorial](https://bubbleailabs.com/pixabay-basic-setup)
- [Video Integration Guide](https://bubbleailabs.com/pixabay-video-guide)
- [Advanced Configuration](https://bubbleailabs.com/pixabay-advanced-config)

#### Video Tutorials
- [Plugin Installation and Setup](https://loom.com/pixabay-installation)
- [Creating Media Galleries](https://loom.com/pixabay-galleries)
- [Video Player Customization](https://loom.com/pixabay-video-player)

### Community Support

#### Bubble Forum
- [Plugin Discussion Thread](https://forum.bubble.io/pixabay-plugin)
- [User Examples and Tips](https://forum.bubble.io/pixabay-examples)
- [Troubleshooting Community](https://forum.bubble.io/pixabay-help)

#### GitHub Repository
- [Issue Tracking](https://github.com/bubbleailabs/pixabay-plugin/issues)
- [Feature Requests](https://github.com/bubbleailabs/pixabay-plugin/discussions)
- [Code Examples](https://github.com/bubbleailabs/pixabay-plugin/examples)

### Direct Support

#### Technical Support
- **Email**: support@bubbleailabs.com
- **Response Time**: 24-48 hours
- **Available**: Monday-Friday, 9 AM - 6 PM EST

#### Premium Support
- **Priority Response**: < 4 hours
- **Direct Developer Access**: Yes
- **Custom Integration Support**: Available
- **Contact**: premium@bubbleailabs.com

### Updates and Changelog

#### Version History
- **v1.0.0**: Initial release with basic search functionality
- **v1.1.0**: Added video player integration
- **v1.2.0**: Performance improvements and caching
- **v1.3.0**: Enhanced filtering and categorization
- **v1.4.0**: Mobile optimization and responsive design

#### Future Roadmap
- Advanced analytics integration
- AI-powered content recommendations
- Enhanced video player features
- Multi-platform synchronization
- Extended API integrations

---

## Conclusion

The Pixabay Media Search Plugin for Bubble provides a comprehensive solution for integrating high-quality media content into your applications. With its advanced features, performance optimizations, and developer-friendly design, it enables you to create engaging, visually rich experiences without the complexity of direct API integration.

For the latest updates, examples, and community discussions, visit our [knowledge base](https://bubbleailabs.com/pixabay-plugin) and join our [community forum](https://forum.bubble.io/pixabay-plugin).

---

*Last updated: July 15, 2025*
*Plugin version: 1.4.0*
*Document version: 1.0*