Usage Guides

This section provides guides on how to effectively use various features of Screenshotly.

1. Capturing Full Page Screenshots

Learn how to capture the entire scrollable length of a webpage.

• Parameter: "fullPage" (boolean)
• Description: When set to "true", Screenshotly will capture the entire page. If "false" or omitted, it captures the visible viewport.
• API Example:

{
  "url": "https://example.com",
  "fullPage": true
}

• Considerations: Full page screenshots can be significantly larger in file size and take longer to process.

2. Setting Custom Viewports

Define the width and height of the browser window for the screenshot.

• Parameter: "viewport" (object)
  • "width" (integer): Viewport width in pixels.
  • "height" (integer): Viewport height in pixels.
• API Example:

{
  "url": "https://example.com",
  "viewport": {
    "width": 1920,
    "height": 1080
  }
}

• Note: If "fullPage" is "true", the "height" might be overridden by the actual page height, but the "width" will still be respected for rendering.

3. Specifying Output Formats

Choose the desired image format for your screenshot.

• Parameter: "format" (string)
• Supported Values: "png", "jpeg", "webp", "pdf" (Verify actual supported formats)
• API Example:

  {
    "url": "https://example.com",
    "format": "jpeg",
    "quality": 80 // Optional: for jpeg/webp, an integer between 0 and 100
  }
  

• PDF Specific Options:
  • "pdfOptions" (object): (e.g., "scale", "printBackground", "landscape", "pageRanges", "format" (paper size like 'A4'), "margin")

  {
    "url": "https://example.com",
    "format": "pdf",
    "pdfOptions": {
      "format": "A4",
      "printBackground": true,
      "margin": { "top": "1in", "bottom": "1in" }
    }
  }
  

4. Delaying Screenshot Captures

Introduce a delay before the screenshot is taken, allowing time for animations or content to load.

• Parameter: "delay" (integer)
• Description: Time in milliseconds to wait after the page loads before taking the screenshot.
• API Example:

{
  "url": "https://example.com",
  "delay": 5000 // 5 seconds delay
}

5. Handling Cookies and Local Storage

Pass cookies or set local storage items for the page before capturing.

• Parameter: "cookies" (array of objects)
  • Each object should conform to Puppeteer's "page.setCookie(...cookies)" format (e.g., "name: 'cookiename', value: 'cookievalue', domain: '.example.com' ").
• Parameter: "localStorage" (object)
  • Key-value pairs to set in the page's local storage.
• API Example:

{
      "url": "https://auth-required-page.com",
      "cookies": [
        { "name": "session_id", "value": "your_session_token", "domain": ".auth-required-page.com" }
      ],
      "localStorage": {
        "userPreferences": "{\"theme\":\"dark\"}"
      }
}

6. Using Webhooks for Notifications

Get notified when a screenshot capture is complete or fails.

• Parameter: "webhookUrl" (string)
• Description: A URL where Screenshotly will send a POST request with the job status and result.
• API Example:

{
  "url": "https://example.com",
  "webhookUrl": "https://your-service.com/webhook-receiver"
}

• Webhook Payload: Refer to the API Reference - Webhooks for payload structure.
• Security: It's recommended to verify webhook requests, e.g., using a secret signature.

7. Scheduling Screenshots

Automate screenshot captures at regular intervals.

• Screenshotly API: The core API focuses on on-demand captures.
• Scheduling Tools: To schedule captures, you'll typically use external tools like:
  • Cron jobs (Linux/macOS)
  • Task Scheduler (Windows)
  • Serverless functions (AWS Lambda, Google Cloud Functions, Azure Functions) with scheduled triggers
  • Workflow automation tools (Zapier, Make, GitHub Actions)
• Guidance: See our blog post on Scheduling Periodic Captures for detailed examples.

8. Custom User Agent

Specify a custom User-Agent string for the browser.

• Parameter: "userAgent" (string)
• API Example:

{
  "url": "https://example.com",
  "userAgent": "MyCustomBrowser/1.0 (Compatible; ScreenshotlyBot/1.0; +https://screenshotly.app/bot)"
}

For more advanced use cases or features not listed here, please consult the API Reference or contact support.