WebSave as Image Documentation

Overview

WebSave as Image is a JavaScript integration for adding an image download button to a website. When a visitor clicks the button, PDFCrowd creates an image from the webpage, using either its URL or the current page HTML.

WebSave as Image product overview

Quick Start

Use this starter code to add the WebSave button.

The starter code includes PDFCrowd's demo key for testing. If you are signed in and have a WebSave key, the example uses your selected key instead. See key setup.

<!-- Button shown on your page -->
<button class="pdfcrowd-websave pdfcrowd-websave-style"
        data-key="demo"
        data-config="webSaveConfig">
  Save as Image
</button>

<!-- Required image settings -->
<script>
window.webSaveConfig = {
  apiSettings: {
    output_format: 'png'
  }
};
</script>

<!-- Load WebSave once, after the button and configuration -->
<script src="https://edge.pdfcrowd.com/websave/1.4.1/websave.min.js" async></script>

<!-- Button with content mode configuration -->
<button class="pdfcrowd-websave pdfcrowd-websave-style"
        data-key="demo"
        data-config="webSaveConfig">
  Save as Image
</button>

<script>
window.webSaveConfig = {
  // Enable content mode to capture current DOM state
  conversionMode: "content",
  apiSettings: {
    output_format: 'png',
  }
};
</script>

<script src="https://edge.pdfcrowd.com/websave/1.4.1/websave.min.js" async></script>

window.WebSave.initButton(document.querySelector('#save-as-image'));

Recipes

Use these optional recipes when you need customization or advanced behavior.

<!-- No pdfcrowd-websave-style class - use your own CSS -->
<button class="pdfcrowd-websave my-custom-button"
        data-key="demo"
        data-config="webSaveConfig">
  Save As Image
</button>

<!-- Customization configuration -->
<script>
window.webSaveConfig = {
  fileAction: 'download',  // or 'open', 'openNewTab'
  fileName: () => 'screenshot-' + new Date().toISOString().split('T')[0] + '.jpg',     
  
  // Image conversion settings
  apiSettings: {
    output_format: 'jpg',     // JPEG format
    screenshot_width: 1600,   // Width in pixels
    jpeg_quality: 85          // Quality (1-100)
  }
};
</script>

<!-- Custom CSS for the button -->
<style>
.my-custom-button {
  background: #007bff;
  color: white;
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
.my-custom-button:hover {
  background: #0056b3;
}
.my-custom-button:disabled {
  opacity: 0.6;
  cursor: wait;
}
</style>

<script src="https://edge.pdfcrowd.com/websave/1.4.1/websave.min.js" async></script>

<button class="pdfcrowd-websave pdfcrowd-websave-style"
        data-key="demo"
        data-config="webSaveConfig">
  Save as Image
</button>

<!-- Method Selection Guide:
   - URL parameters: Best when server has print-specific templates
   - Print stylesheets: Quick option if @media print CSS exists
   - Custom CSS: Flexible styling without modifying HTML
   - JavaScript: Dynamic content manipulation
   - pdfcrowd-remove class: Simple for removing static elements -->

<script>
window.webSaveConfig = {

  // Method 1: URL parameters, adds ?print=1 (URL mode only)
  onBeforeConversion: function(config) {
    if (config.conversionMode === 'url') {
      const url = new URL(config.url);
      url.searchParams.set('print', '1');
      config.url = url.toString();
    }
    return false; // Proceed with conversion
  },
  
  apiSettings: {
    // Method 2: Print stylesheets
    // use_print_media: true,
    
    // Method 3: Custom CSS injection
    custom_css: `
      /* Hide elements in screenshot */
      .advertisement, .sidebar, footer { 
        display: none !important; 
      }
      /* Adjust layout for cleaner capture */
      .content { 
        width: 100% !important; 
        max-width: none !important; 
      }
    `,
    
    // Method 4: JavaScript preprocessing
    custom_javascript: `
      // Remove dynamic content before conversion
      document.querySelectorAll('.video-player, .chat-widget').forEach(el => {
        el.remove();
      });
      // Expand collapsed sections
      document.querySelectorAll('.collapsed').forEach(el => {
        el.classList.remove('collapsed');
      });
    `,

    output_format: 'png'      
  }
};

</script>

<!-- Method 5: Use pdfcrowd-remove class directly in HTML
     Add this class to elements in your actual page content: -->
<nav class="pdfcrowd-remove">
  This navigation won't appear in the screenshot
</nav>

<script src="https://edge.pdfcrowd.com/websave/1.4.1/websave.min.js" async></script>

<!-- Advanced customization with callbacks -->
<button class="pdfcrowd-websave pdfcrowd-websave-style"
        data-key="demo"
        data-config="webSaveConfig">
  Save as Image
</button>

<script>
// Application-specific hooks. Replace these with your own UI, analytics,
// and permission checks:
// - showCustomErrorModal(message, code) - your error UI
// - trackEvent(name, data) - your analytics
// - userIsLoggedIn() - your auth check

window.webSaveConfig = {

  // Custom error handling
  onError: function(errorMessage, statusCode) {
    console.error('WebSave error:', errorMessage, 'Code:', statusCode);
    
    // Display your own error UI instead of default dialog
    showCustomErrorModal(errorMessage, statusCode);
    
    return true; // Return true to prevent default error dialog
  },
  
  // Track successful conversions
  onFileCreated: function(blob) {
    // Log success for analytics
    trackEvent('image_generated', {
      size: blob.size,
      page: window.location.pathname
    });
    
    return false; // Return false to let WebSave handle download
  },
  
  // Pre-conversion validation (optional)
  onBeforeConversion: function(config) {
    // Validate or modify before conversion starts
    // Example: Check if user is logged in
    if (!userIsLoggedIn()) {
       alert('Please log in to download image');
       return true; // Cancel conversion
    }

    return false; // Proceed with conversion
  },

  // Image generation settings
  apiSettings: {
    output_format: 'png'
  }
};
</script>

<script src="https://edge.pdfcrowd.com/websave/1.4.1/websave.min.js" async></script>

Authentication

How WebSave Keys Work

Each personal WebSave key is tied to the domain or subdomain you enter when creating the key. This lets you include the key in client-side code - if someone copies it, they cannot use it on their own website. The key is provided via the data-key attribute on your conversion button.

Getting Your Keys

Key Management Options

• Create separate keys for unrelated domains and subdomains.
• Enable "Include subdomains" when one key should cover subdomains under the entered site.
• You can generate multiple keys per site for various sections or teams.
• Use separate keys for staging and production environments.
• Revoke and regenerate keys anytime if needed.

Error Handling

WebSave handles common error states automatically. You only need custom error handling when you want to use your own UI or logging.

Built-in Error Recovery

• Retries conversion requests that fail with HTTP 502/503 up to twice (three attempts total).
• Disables buttons with the pdfcrowd-websave-style class during conversion and re-enables them afterwards.
• Prevents multiple simultaneous conversions from the same button.

Error Display Options

Without configuration, WebSave shows a default error dialog after automatic recovery attempts. Use the onError callback if you want to customize the final error presentation.

Implementing Custom Error Handling

Use the onError callback to customize error handling. This recipe shows a simple custom error handler with user-friendly messages and console logging:

<button class="pdfcrowd-websave"
        data-key="demo"
        data-config="webSaveConfig">
  Save as Image
</button>

<script>
window.webSaveConfig = {
  onError: function(errorMessage, statusCode) {
    // Log to console for debugging
    console.error('WebSave Error:', {
      message: errorMessage,
      code: statusCode,
      url: window.location.href
    });
    
    // Show user-friendly message
    let userMessage = 'Unable to generate image. Please try again.';
    if (statusCode === 429) {
      userMessage = 'Too many requests. Please wait a moment and try again.';
    } else if (statusCode >= 500) {
      userMessage = 'Service temporarily unavailable. Please try again later.';
    }
    
    // Display to user
    alert(userMessage);
    
    // Return true to suppress default dialog
    return true;
  },
  apiSettings: {
    output_format: 'png'
  }
};
</script>

<script src="https://edge.pdfcrowd.com/websave/1.4.1/websave.min.js" async></script>

For detailed error code information, see the Status Codes Reference.

Troubleshooting

This guide helps you diagnose and resolve common WebSave integration issues. For automatic error recovery and customization options, see the Error Handling section above.

Button Not Working

Button doesn't respond to clicks

• Verify the button has the correct class: pdfcrowd-websave
• Check that data-key attribute contains your WebSave key
• Ensure the WebSave script loads
• Confirm your page is served over HTTPS - WebSave requires secure connections
• Open browser console and check for JavaScript errors or security warnings

Invalid WebSave key error

• Verify the key matches the domain or subdomain where your page is hosted
• Check the key scope in your WebSave dashboard: "Exact only" keys do not work on subdomains
• For example, a key for example.com works on www.example.com only when "Include subdomains" is enabled
• A key for www.example.com with "Include subdomains" covers deeper subdomains such as app.www.example.com, not sibling sites such as dev.example.com
• Check that you're using a WebSave key (not a regular API key)
• Ensure the key is active

Works on one subdomain but not another

WebSave key scope follows the exact site entered when the key is created. A key for example.com with "Include subdomains" works on www.example.com and dev.example.com. A key for www.example.com works on www.example.com and, with "Include subdomains", on deeper subdomains such as app.www.example.com. It does not work on sibling sites such as dev.example.com.

Custom URL mode target rejected

In URL mode, WebSave normally converts the current page URL. If your JavaScript changes the URL to be converted, the browser same-origin check still uses exact host matching. example.com and www.example.com are different origins, even if the WebSave key includes subdomains. Use content mode when you need to convert the current browser page state.

Not working on localhost

WebSave cannot access localhost URLs as conversions happen on PDFCrowd servers. Use ngrok or localtunnel to create a temporary public HTTPS URL for your local development server.

Button not working in reactive frameworks

• For buttons rendered after page load, see Initialize Buttons Rendered After Page Load.

Content Not Captured Correctly

Pages behind login or with user input

URL mode fetches a fresh page from your server. Use conversionMode: "content" in your JavaScript configuration for:

• Pages behind login/authentication
• Form values and user input
• User-modified content after page load
• Single-page application state

See Use Content Mode for Logged-In Pages and Forms for implementation.

JavaScript-generated or AJAX content missing

For dynamic content, either use content mode or add javascript_delay to wait for content to load:

window.webSaveConfig = {
  apiSettings: {
    javascript_delay: 2000,  // Wait 2 seconds for JS/AJAX
  }
}

Wrong responsive layout or content cut off

Images may show mobile layout instead of desktop (or vice versa) based on viewport width. Set screenshot_width to control which responsive breakpoint is used:

window.webSaveConfig = {
  apiSettings: {
    screenshot_width: "1280px",  // Force desktop layout
  }
}

Common widths: Mobile (375-414px), Tablet (768-834px), Desktop (1280-1920px).

Debugging Tools and Techniques

WebSave provides two debugging options to help diagnose different types of issues:

• verbosity logs WebSave events (button clicks, API calls, key validation) to your browser console - useful for integration and configuration issues.
• debug_log captures what happens on PDFCrowd servers (resource loading, timeouts) - helpful for content and layout problems. Find these logs in your conversion log.

window.webSaveConfig = {
  verbosity: 1,  // Client-side: logs events to browser console
  apiSettings: {
    debug_log: true,  // Server-side: saves details to conversion log
  }
};

Getting Help

If you're still experiencing issues after trying these solutions:

• Review the API Status Codes for specific error code explanations
• Check the FAQ for answers to common questions
• Visit the WebSave Reference for detailed configuration options
• Contact support with your configuration and any error messages

When contacting support, include:

• Your WebSave configuration code
• The URL where the issue occurs (or a test page demonstrating the problem)
• Browser console output with verbosity: 1 enabled
• Screenshots of any error messages