Class: ScreenshotFreeAPI::Resources::Screenshots

Inherits:
Object
  • Object
show all
Defined in:
lib/screenshotfreeapi/resources/screenshots.rb

Overview

Screenshot capture endpoints with optional synchronous polling helpers.

All ‘web`, `mobile`, and `html` methods return a 202 job receipt. The `*_and_wait` variants block until the job completes and return the full result hash directly.

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ Screenshots

Returns a new instance of Screenshots.

Parameters:



12
13
14
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 12

def initialize(http)
  @http = http
end

Instance Method Details

#html(options = {}) ⇒ Hash

Enqueue an HTML-string screenshot job.

Parameters:

  • html (String) —

    Raw HTML to render and capture.

  • dimensions (Hash) —

    { width: Integer, height: Integer }

  • full_page (Boolean)
  • format (String) —

    “png” | “jpeg” | “webp” | “pdf”

  • webhook_url (String)

Returns:

  • (Hash) —

    { “jobId”, “status”, “statusUrl”, “estimatedSeconds” }



64
65
66
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 64

def html(options = {})
  @http.request(:post, "/screenshots/html", body: camelize_keys(options))
end

#html_and_wait(options = {}, poll_interval: 2, timeout: 120) ⇒ Hash

Render an HTML string and block until the screenshot is ready.

Parameters:

  • options (Hash) (defaults to: {}) —

    Same keyword arguments as ‘html`.

  • poll_interval (Numeric) (defaults to: 2)
  • timeout (Numeric) (defaults to: 120)

Returns:

  • (Hash) —

    Full result hash



102
103
104
105
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 102

def html_and_wait(options = {}, poll_interval: 2, timeout: 120)
  job = html(options)
  wait(job["jobId"], poll_interval: poll_interval, timeout: timeout)
end

#mobile(options = {}) ⇒ Hash

Enqueue a mobile app screenshot job.

Parameters:

  • app_name (String) —

    App display name (e.g. “Instagram”)

  • platform (String) —

    “ios” | “android” | “both”

  • bundle_id (String) —

    Bundle/package ID

  • include_store_listing (Boolean) —

    Also download store listing images

  • device_emulation (String) —

    Playwright device preset (e.g. “iPhone 12”)

  • webhook_url (String)

Returns:

  • (Hash) —

    { “jobId”, “status”, “statusUrl”, “estimatedSeconds” }



51
52
53
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 51

def mobile(options = {})
  @http.request(:post, "/screenshots/mobile", body: camelize_keys(options))
end

#mobile_and_wait(options = {}, poll_interval: 2, timeout: 120) ⇒ Hash

Capture a mobile screenshot and block until it completes.

Parameters:

  • options (Hash) (defaults to: {}) —

    Same keyword arguments as ‘mobile`.

  • poll_interval (Numeric) (defaults to: 2)
  • timeout (Numeric) (defaults to: 120)

Returns:

  • (Hash) —

    Full result hash



90
91
92
93
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 90

def mobile_and_wait(options = {}, poll_interval: 2, timeout: 120)
  job = mobile(options)
  wait(job["jobId"], poll_interval: poll_interval, timeout: timeout)
end

#wait(job_id, poll_interval: 2, timeout: 120) {|status| ... } ⇒ Hash

Poll a job until it reaches a terminal state.

Parameters:

  • job_id (String)
  • poll_interval (Numeric) (defaults to: 2) —

    Seconds between status polls (default: 2)

  • timeout (Numeric) (defaults to: 120) —

    Maximum seconds to wait (default: 120)

Yield Parameters:

  • status (Hash) —

    Called on each poll (optional progress callback)

Returns:

  • (Hash) —

    Full result hash (from /jobs/:id/result)

Raises:



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 117

def wait(job_id, poll_interval: 2, timeout: 120, &on_progress)
  deadline = Time.now + timeout

  loop do
    status_data = @http.request(:get, "/jobs/#{job_id}/status")

    on_progress.call(status_data) if on_progress

    case status_data["status"]
    when "completed"
      return @http.request(:get, "/jobs/#{job_id}/result")
    when "failed"
      reason = status_data["error"] || "Unknown failure"
      raise JobFailedError.new(job_id, reason)
    end

    if Time.now >= deadline
      raise JobTimeoutError.new(job_id, timeout)
    end

    sleep(poll_interval)
  end
end

#web(options = {}) ⇒ Hash

Enqueue a web screenshot job.

Parameters:

  • url (String) —

    Required. Public URL to capture.

  • description (String) —

    Plain-English description of the element to target (triggers AI vision path).

  • element (String) —

    CSS selector to capture instead of full page.

  • dimensions (Hash) —

    { width: Integer, height: Integer }

  • full_page (Boolean) —

    Capture the entire scrollable page.

  • scrolling (Boolean) —

    Enable scroll-based capture.

  • format (String) —

    “png” | “jpeg” | “webp” | “pdf” (default: “png”)

  • paper_size (String) —

    PDF paper size, e.g. “A4”, “Letter”

  • block_ads (Boolean) —

    Block ad scripts before capture (STARTER+)

  • accept_cookies (Boolean) —

    Auto-dismiss cookie banners (STARTER+)

  • stealth (Boolean) —

    Enable stealth mode (BUSINESS+)

  • proxy_location (String) —

    Proxy region, e.g. “eu-west” (BUSINESS+)

  • video (Hash) —

    { duration: Integer, fps: Integer } (GROWTH+)

  • bypass_cache (Boolean) —

    Skip the response cache.

  • storage (Hash) —

    Custom S3 config (BUSINESS+)

  • webhook_url (String) —

    URL to POST completion event to.

Returns:

  • (Hash) —

    { “jobId”, “status”, “statusUrl”, “estimatedSeconds” }



37
38
39
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 37

def web(options = {})
  @http.request(:post, "/screenshots/web", body: camelize_keys(options))
end

#web_and_wait(options = {}, poll_interval: 2, timeout: 120) {|status| ... } ⇒ Hash

Capture a web screenshot and block until it completes.

Combines ‘web` + `wait` in a single call.

Parameters:

  • options (Hash) (defaults to: {}) —

    Same keyword arguments as ‘web`.

  • poll_interval (Numeric) (defaults to: 2) —

    Seconds between status polls (default: 2)

  • timeout (Numeric) (defaults to: 120) —

    Maximum seconds to wait (default: 120)

Yield Parameters:

  • status (Hash) —

    Called on each poll with the current status hash.

Returns:

  • (Hash) —

    Full result hash (same as Jobs#result)



78
79
80
81
 
# File 'lib/screenshotfreeapi/resources/screenshots.rb', line 78

def web_and_wait(options = {}, poll_interval: 2, timeout: 120, &on_progress)
  job = web(options)
  wait(job["jobId"], poll_interval: poll_interval, timeout: timeout, &on_progress)
end