{"id":13878470,"url":"https://github.com/urlbox/urlbox-ruby","last_synced_at":"2025-10-13T02:32:05.252Z","repository":{"id":38011094,"uuid":"433519862","full_name":"urlbox/urlbox-ruby","owner":"urlbox","description":"The Urlbox Ruby gem provides easy access to the Urlbox API and saves you from having to do this 👇","archived":false,"fork":false,"pushed_at":"2024-10-14T13:26:45.000Z","size":52,"stargazers_count":9,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-20T19:51:40.598Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://urlbox.com/screenshot-api/ruby","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urlbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-30T17:17:09.000Z","updated_at":"2024-03-11T17:44:45.000Z","dependencies_parsed_at":"2022-08-08T22:45:59.159Z","dependency_job_id":null,"html_url":"https://github.com/urlbox/urlbox-ruby","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlbox%2Furlbox-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlbox%2Furlbox-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlbox%2Furlbox-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlbox%2Furlbox-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urlbox","download_url":"https://codeload.github.com/urlbox/urlbox-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236298335,"owners_count":19126500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:01:50.906Z","updated_at":"2025-10-13T02:31:59.960Z","avatar_url":"https://github.com/urlbox.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"![image](https://user-images.githubusercontent.com/1453680/143582241-f44bd8c6-c242-48f4-8f9a-ed5507948588.png)\n# Urlbox Ruby Library\n![Tests](https://github.com/urlbox/urlbox-python/actions/workflows/tests.yml/badge.svg)\n![Linter](https://github.com/urlbox/urlbox-python/actions/workflows/linters.yml/badge.svg)\n\nThe Urlbox Ruby gem provides easy access to the \u003ca href=\"https://urlbox.com/\" target=\"_blank\"\u003eUrlbox website screenshot API\u003c/a\u003e from your Ruby/Rails application.\n\nNow there's no need to muck around with http clients, etc...\n\nJust initialise the Urlbox::Client and make a screenshot of a URL in seconds.\n\n\n## Documentation\n\nSee the \u003ca href=https://urlbox.com/docs/overview target=\"_blank\"\u003eUrlbox API Docs\u003c/a\u003e.\n\n## Requirements\n\nRuby 2.5 and above.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'urlbox'\n```\n\nAnd then run:\n```\n$ bundle install\n```\nOr just...\n```\n$ gem install urlbox\n```\n\n## Usage\n\nFirst, grab your Urlbox API key and API secret* found in your \u003ca href=\"https://urlbox.com/dashboard/api\" target=\"_blank\"\u003eUrlbox Dashboard\u003c/a\u003e.\n\n*\\* Requests will be automatically authenticated when you supply your API secret.*\n\n### Quick Start:  Generate a Screenshot URL\nFor use directly in HTML templates, the browser etc.\n\n```ruby\nrequire  'urlbox/client'\n\n# Initialise the UrlboxClient\nurlbox_client = Urlbox::Client.new(api_key: 'YOUR_API_KEY', api_secret: 'YOUR_API_SECRET')\n\n# Generate a screenshot url\nscreenshot_url = urlbox_client.generate_url({url: 'http://example.com/'})\n\n```\n\nIn your erb/html template, use the screenshot_url generated above:\n```html\n\u003c%= image_tag screenshot_url %\u003e\n```\n\n###  Quick Start: Quickly Get a Screenshot of a URL\n```ruby\nrequire  'urlbox/client'\n\nurlbox_client = Urlbox::Client.new(api_key: 'YOUR_API_KEY', api_secret: 'YOUR_API_SECRET')\n\n# Make a request to the UrlBox API\nresponse = urlbox_client.get({url: 'http://example.com/'})\n\n# Save your screenshot image to screenshot.png:\nFile.write('screenshot.png', response.to_s)\n```\n\nAll UrlboxClient methods require at least one argument: a hash that *must include either a \"url\", or \"html\" entry*, which the Urlbox API will render as a screenshot.\n\nAdditional options in the dictionary include:\n\n\"format\" can be either: png, jpg or jpeg, avif, webp ,pdf, svg, html  *(defaults to png if not provided).*\n\n\"full_page\", \"width\", and many more.\nSee all available options here: https://urlbox.com/docs/options\n\neg:\n```ruby\n{url: 'http://example.com/', full_page: true, width: 300}\n```\n\n\n### A More Extensive Get Request\n```ruby\noptions = {\n\turl: \"https://www.independent.co.uk/arts-entertainment/tv/news/squid-game-real-youtube-mrbeast-b1964007.html\",\n\tformat: 'jpg',\n\tfull_page: false,\n\thide_cookie_banners: true,\n\tblock_ads: true\n}\n\nresponse = urlbox_client.get(options)\n\n# The Urlbox API will return binary data as the response with the\n# Content-Type header set to the relevant mime-type for the format requested.\n# For example, if you requested jpg format, the Content-Type will be image/jpeg\n# and response body will be the actual jpg binary data.\n\nresponse.to_s # Your screenshot as binary image data which looks like 👇\n```\n![image](https://user-images.githubusercontent.com/1453680/143479491-78d8edbc-dfdc-48e3-9ae0-3b59bcf98e2c.png)\n\n\n## Other Methods/Requests\nThe UrlboxClient has the following public methods:\n\n### get(options)\n*(as detailed in the above examples)*\nMakes a GET request to the Urlbox API to create a screenshot for the url or html passed in the options dictionary.\n\nExample request:\n```ruby\nresponse = urlbox_client.get({url: 'http://example.com/'})\nresponse.to_s # Your screenshot 🎉\n```\n\n### delete(options)\nRemoves a previously created screenshot from the cache.\n\nExample request:\n```ruby\nurlbox_client.delete({url: 'http://example.com/'})\n```\n### head(options)\nIf you just want to get the response status/headers without pulling down the full response body.\n\nExample request:\n```ruby\nresponse = urlbox_client.head({url: 'http://example.com/'})\n\nputs(response.headers)\n\n```\n\nExample response headers:\n\n```json\n{\n   \"Date\":\"Fri, 26 Nov 2021 16:22:56 GMT\",\n   \"Content-Type\":\"image/png\",\n   \"Content-Length\":\"1268491\",\n   \"Connection\":\"keep-alive\",\n   \"Cache-Control\":\"public, max-age=2592000\",\n   \"Expires\":\"Sun, 26 Dec 2021 16:16:09 GMT\",\n   \"Last-Modified\":\"Fri, 26 Nov 2021 16:14:56 GMT\",\n   \"X-Renders-Used\":\"60\",\n   \"X-Renders-Reset\":\"Sun Dec 05 2021 09:58:00 GMT+0000 (Coordinated Universal Time)\",\n   \"X-Renders-Allowed\":\"22000\"\n}\n```\nYou can use these headers to check how many renders you have used or your current rate limiting status, etc.\n\n### post(options)\nUses Urlbox's webhook functionality to initialise a render of a screenshot. You will need to provide a *\"webhook_url\"* entry in the options which Urlbox will post back to when the rendering of the screenshot is complete.\n\nExample request:\n```ruby\nurlbox_client.post({url: \"http://twitter.com/\", webhook_url: \"http://yoursite.com/webhook\"})\n```\nGive it a couple of seconds, and you should receive, posted to the webhook_url specified in your request above, a post request with a JSON body similar to:\n```json\n{\n  \"event\": \"render.succeeded\",\n  \"renderId\": \"2cf5ffe2-7736-4d41-8c30-f13e16d35248\",\n  \"result\": {\n    \"renderUrl\": \"https://renders.urlbox.io/urlbox1/renders/61431b47b8538a00086c29dd/2021/11/25/e2dcec18-8353-435c-ba17-b549c849eec5.png\"\n  },\n  \"meta\": {\n    \"startTime\": \"2021-11-25T16:32:32.453Z\",\n    \"endTime\": \"2021-11-25T16:32:38.719Z\"\n  }\n}\n```\nYou can then parse the renderUrl value to access the your screenshot.\n\n\n## Secure Webhook Posts\nThe Urlbox API post to your webhook endpoint will include a header that you can use to  ensure this is a genuine request from the Urlbox API, and not a malicious actor.\n\nUsing your http client of choice, access the *x-urlbox-signature* header. Its value will be something similar to:\n\n`t=1637857959,sha256=1d721f99aa03122d494f8b49f201fdf806efaec609c614f0a0ec7b394f1d403a`\n\nUse the *webhook_validator* helper function that is included, for no extra charge, in the urlbox package to verify that the webhook post is indeed a genuine request from the Urlbox API. Like so:\n\n```ruby\nrequire 'urlbox/webhook_validator'\n\n# extracted from the x-urlbox-signature header\nheader_signature = \"t=1637857959,sha256=1d721f...\"\n\n# the raw JSON payload from the webhook request body\npayload = {\n  \"event\": \"render.succeeded\",\n  \"renderId\": \"794383cd-b09e-4aef-a12b-fadf8aad9d63\",\n  \"result\": {\n    \"renderUrl\": \"https://renders.urlbox.io/urlbox1/renders/foo.png\"\n  },\n  \"meta\": {\n    \"startTime\": \"2021-11-24T16:49:48.307Z\",\n    \"endTime\": \"2021-11-24T16:49:53.659Z\",\n  },\n}\n\n# Your webhook secret - coming soon.\n# NB: This is NOT your api_secret, that's different.\nwebhook_secret = \"YOUR_WEBHOOK_SECRET\"\n\n# This will either return true (if the signature is genuinely from Urlbox)\n#   or it will raise a InvalidHeaderSignatureError (if the signature is not from Urlbox)\nUrlbox::WebhookValidator.call(header_signature, payload, webhook_secret)\n```\n\n## Using Env Vars?\n\nIf you are using env vars, in your .env file, set:\n```yaml\nURLBOX_API_KEY: YOUR_URLBOX_API_KEY\nURLBOX_API_SECRET: YOUR_URLBOX_API_SECRET\nURLBOX_API_HOST_NAME: YOUR_URLBOX_API_HOST_NAME # (optional, advanced usage)\n```\n\nThen the Urlbox::Client will pick these up and you can use all the above Urlbox::Client class methods directly, without having to initialise the Urlbox::Client.\nEg:\n\n```ruby\nrequire  'urlbox/client'\n\nscreenshot_url = Urlbox::Client.generate_url({url: \"http://example.com/\"})\n\nUrlbox::Client.get(...)\nUrlbox::Client.head(...)\n# etc\n\n```\n## Feedback\n\n\nFeel free to contact us if you spot a bug or have any suggestions at: support`[at]`urlbox.com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furlbox%2Furlbox-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furlbox%2Furlbox-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furlbox%2Furlbox-ruby/lists"}