RenderScreenshot Ruby SDK

The official Ruby SDK for RenderScreenshot - a developer-friendly screenshot API for capturing web pages programmatically.

Installation

Add this line to your application's Gemfile:

gem 'renderscreenshot'

And then execute:

bundle install

Or install it yourself as:

gem install renderscreenshot

Requirements

• Ruby 3.0 or higher

Quick Start

require 'renderscreenshot'

# Create a client
client = RenderScreenshot.client('rs_live_your_api_key')

# Take a screenshot
image_data = client.take(
  RenderScreenshot::TakeOptions
    .url('https://example.com')
    .width(1200)
    .height(630)
    .format('png')
)

# Save to file
File.binwrite('screenshot.png', image_data)

Configuration

Global Configuration

RenderScreenshot.configure do |config|
  config.base_url = 'https://api.renderscreenshot.com'  # Default
  config.timeout = 30  # Default timeout in seconds
end

Per-Client Configuration

client = RenderScreenshot.client(
  'rs_live_your_api_key',
  base_url: 'https://custom.api.com',
  timeout: 60
)

Usage

Taking Screenshots

Binary Response

# Get screenshot as binary data
image_data = client.take(
  RenderScreenshot::TakeOptions
    .url('https://example.com')
    .preset('og_card')
)

JSON Response (with metadata)

# Get screenshot URL and metadata
response = client.take_json(
  RenderScreenshot::TakeOptions
    .url('https://example.com')
    .preset('og_card')
)

puts response['image']['url']      # CDN URL
puts response['image']['width']    # 1200
puts response['image']['height']   # 630
puts response['cache']['key']      # Cache key for later reference

Screenshot Options

The TakeOptions class provides a fluent interface for configuring screenshots:

options = RenderScreenshot::TakeOptions
  .url('https://example.com')
  # Viewport
  .width(1920)
  .height(1080)
  .scale(2)
  .mobile(true)
  # Capture
  .full_page
  .element('#main-content')
  .format('webp')
  .quality(90)
  # Wait conditions
  .wait_for('networkidle')
  .delay(500)
  .wait_for_selector('.loaded')
  # Blocking
  .block_ads
  .block_trackers
  .block_cookie_banners
  # Browser emulation
  .dark_mode
  .timezone('America/New_York')
  .locale('en-US')

Using Presets

# Social card presets
options = RenderScreenshot::TakeOptions
  .url('https://example.com')
  .preset('og_card')  # 1200x630 for Open Graph

# Device presets
options = RenderScreenshot::TakeOptions
  .url('https://example.com')
  .device('iphone_14_pro')

PDF Generation

options = RenderScreenshot::TakeOptions
  .url('https://example.com')
  .format('pdf')
  .pdf_paper_size('a4')
  .pdf_landscape
  .pdf_print_background
  .pdf_margin('1cm')

pdf_data = client.take(options)
File.binwrite('document.pdf', pdf_data)

Batch Processing

# Simple batch (same options for all URLs)
response = client.batch(
  ['https://example1.com', 'https://example2.com', 'https://example3.com'],
  options: RenderScreenshot::TakeOptions.url('').preset('og_card')
)

response['results'].each do |result|
  puts "#{result['url']}: #{result['status']}"
end

# Advanced batch (per-URL options)
response = client.batch_advanced([
  { url: 'https://example1.com', options: { preset: 'og_card' } },
  { url: 'https://example2.com', options: { preset: 'twitter_card' } }
])

Signed URLs

Generate signed URLs for client-side use without exposing your API key:

options = RenderScreenshot::TakeOptions
  .url('https://example.com')
  .preset('og_card')

# URL expires in 24 hours
signed_url = client.generate_url(options, expires_at: Time.now + 86400)

# Use in HTML
# <img src="#{signed_url}" />

Cache Management

cache = client.cache

# Get cached screenshot
data = cache.get('cache_key_123')

# Delete cached entry
cache.delete('cache_key_123')

# Bulk purge
cache.purge(['key1', 'key2', 'key3'])

# Purge by URL pattern
cache.purge_url('https://example.com/*')

# Purge by date
cache.purge_before(Time.now - 86400 * 7)  # Older than 7 days

# Purge by storage path pattern
cache.purge_pattern('screenshots/2024/01/*')

Presets and Devices

# List all presets
presets = client.presets
presets.each { |p| puts "#{p['id']}: #{p['name']}" }

# Get specific preset
preset = client.preset('og_card')

# List all devices
devices = client.devices
devices.each { |d| puts "#{d['id']}: #{d['name']} (#{d['width']}x#{d['height']})" }

Webhook Verification

# In your webhook endpoint
def webhook_handler(request)
  payload = request.body.read
  signature, timestamp = RenderScreenshot::Webhook.extract_headers(request.headers)

  unless RenderScreenshot::Webhook.verify(
    payload: payload,
    signature: signature,
    timestamp: timestamp,
    secret: ENV['WEBHOOK_SECRET']
  )
    return [401, 'Invalid signature']
  end

  event = RenderScreenshot::Webhook.parse(payload)

  case event[:event]
  when 'screenshot.completed'
    handle_screenshot_completed(event[:data])
  when 'screenshot.failed'
    handle_screenshot_failed(event[:data])
  when 'batch.completed'
    handle_batch_completed(event[:data])
  end

  [200, 'OK']
end

Error Handling

All API errors inherit from RenderScreenshot::Error:

begin
  client.take(RenderScreenshot::TakeOptions.url('https://example.com'))
rescue RenderScreenshot::ValidationError => e
  puts "Invalid request: #{e.message}"
rescue RenderScreenshot::AuthenticationError => e
  puts "Auth failed: #{e.message}"
rescue RenderScreenshot::RateLimitError => e
  puts "Rate limited. Retry after #{e.retry_after} seconds"
  sleep(e.retry_after) if e.retry_after
  retry
rescue RenderScreenshot::TimeoutError => e
  puts "Request timed out" if e.retryable?
rescue RenderScreenshot::ServerError => e
  puts "Server error: #{e.message}"
  retry if e.retryable?
rescue RenderScreenshot::ConnectionError => e
  puts "Connection failed: #{e.message}"
end

Error properties:

• http_status - HTTP status code
• code - Error code from API
• message - Human-readable message
• request_id - Request ID for support
• retry_after - Seconds to wait (rate limits)
• retryable? - Whether the error can be retried

Complete Options Reference

Category	Methods
Viewport	width, height, scale, mobile
Capture	full_page, element, format, quality
Wait	wait_for, delay, wait_for_selector, wait_for_timeout
Preset	preset, device
Blocking	block_ads, block_trackers, block_cookie_banners, block_chat_widgets, block_urls, block_resources
Page	inject_script, inject_style, click, hide, remove
Browser	dark_mode, reduced_motion, media_type, user_agent, timezone, locale, geolocation
Network	headers, cookies, auth_basic, auth_bearer, bypass_csp
Cache	cache_ttl, cache_refresh
PDF	pdf_paper_size, pdf_width, pdf_height, pdf_landscape, pdf_margin, pdf_margin_top, pdf_margin_right, pdf_margin_bottom, pdf_margin_left, pdf_scale, pdf_print_background, pdf_page_ranges, pdf_header, pdf_footer, pdf_fit_one_page, pdf_prefer_css_page_size
Storage	storage_enabled, storage_path, storage_acl

Development

After checking out the repo:

bundle install
bundle exec rake test      # Run tests
bundle exec rubocop        # Run linter
bundle exec rake           # Run both

Pre-commit Hooks

This project uses pre-commit hooks to prevent secrets from being committed:

# Install pre-commit (if not already installed)
brew install pre-commit    # macOS
pip install pre-commit     # or via pip

# Install the hooks
pre-commit install

# Run manually on all files
pre-commit run --all-files

The hooks include:

• Gitleaks - Scans for secrets and API keys
• detect-private-key - Prevents committing private keys
• check-added-large-files - Prevents large files (>500KB)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/renderscreenshot/renderscreenshot-ruby.

License

The gem is available as open source under the terms of the MIT License.