Java SDK

The official Java SDK for RenderScreenshot.

Installation

Maven

Add the JitPack repository:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Add the dependency:

<dependency>
    <groupId>com.github.Render-Screenshot</groupId>
    <artifactId>rs-java</artifactId>
    <version>v1.0.0</version>
</dependency>

Gradle

Add the JitPack repository:

repositories {
    maven { url 'https://jitpack.io' }
}

Add the dependency:

implementation 'com.github.Render-Screenshot:rs-java:v1.0.0'

Requirements

• Java 11 or higher

Quick Start

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.TakeOptions;

import java.nio.file.Files;
import java.nio.file.Path;

Client client = new Client("rs_live_xxxxx");

// Take a screenshot
byte[] image = client.take(
    TakeOptions.url("https://example.com").preset("og_card")
);

Files.write(Path.of("screenshot.png"), image);

Client

Constructor

import com.renderscreenshot.sdk.Client;

Client client = new Client(apiKey);
Client client = new Client(apiKey, baseUrl, timeout);

Methods

take(options)

Take a screenshot and return binary data.

byte[] image = client.take(
    TakeOptions.url("https://example.com").preset("og_card")
);

// Save to file
Files.write(Path.of("screenshot.png"), image);

Returns: byte[]

takeJson(options)

Take a screenshot and return JSON metadata.

ScreenshotResponse response = client.takeJson(
    TakeOptions.url("https://example.com").preset("og_card")
);

System.out.println(response.getUrl());     // CDN URL
System.out.println(response.getWidth());   // 1200
System.out.println(response.getHeight());  // 630
System.out.println(response.isCached());   // true/false

Returns: ScreenshotResponse

generateUrl(options, expiresAt)

Generate a signed URL for public embedding.

import java.time.Duration;
import java.time.Instant;

String signedUrl = client.generateUrl(
    TakeOptions.url("https://example.com").preset("og_card"),
    Instant.now().plus(Duration.ofHours(24)) // 24 hours
);

// Use in HTML: <img src="${signedUrl}" />

Returns: String

batch(urls, options) / batchAdvanced(requests)

Process multiple screenshots in a batch.

import java.util.Arrays;
import java.util.List;

// Simple batch
List<String> urls = Arrays.asList(
    "https://example1.com",
    "https://example2.com"
);

BatchResponse results = client.batch(urls,
    TakeOptions.url("").preset("og_card")
);

// Advanced batch with per-URL options
List<Client.BatchRequest> requests = Arrays.asList(
    new Client.BatchRequest("https://example1.com",
        TakeOptions.url("https://example1.com").preset("og_card")),
    new Client.BatchRequest("https://example2.com",
        TakeOptions.url("https://example2.com").width(1920))
);

BatchResponse results = client.batchAdvanced(requests);

Returns: BatchResponse

getBatch(batchId)

Get the status of a batch job.

BatchResponse status = client.getBatch("batch_abc123");
System.out.println(status.getCompleted() + "/" + status.getTotal());

Returns: BatchResponse

presets() / preset(id)

Get available presets.

List<Preset> presets = client.presets();
Preset ogCard = client.preset("og_card");

devices()

Get available device presets.

List<Device> devices = client.devices();

TakeOptions

Fluent builder for screenshot options.

Creating Options

import com.renderscreenshot.sdk.TakeOptions;

// From URL
TakeOptions options = TakeOptions.url("https://example.com");

// From HTML
TakeOptions options = TakeOptions.html("<h1>Hello World</h1>");

Viewport Options

TakeOptions.url("...")
    .width(1200)           // Viewport width
    .height(630)           // Viewport height
    .scale(2.0)            // Device scale factor (1-3)
    .mobile();             // Enable mobile emulation

Capture Options

TakeOptions.url("...")
    .fullPage()            // Capture full scrollable page
    .element(".hero")      // Capture specific element
    .format("png")         // png, jpeg, webp, pdf
    .quality(90);          // JPEG/WebP quality (1-100)

Wait Options

TakeOptions.url("...")
    .waitFor("networkidle")      // load, networkidle, domcontentloaded
    .delay(2000)                 // Additional delay (ms)
    .waitForSelector(".loaded")  // Wait for selector
    .waitForTimeout(30000);      // Max wait time (ms)

Presets & Devices

TakeOptions.url("...")
    .preset("og_card")           // Use a preset
    .device("iphone_14_pro");    // Emulate a device

Content Blocking

TakeOptions.url("...")
    .blockAds()                  // Block ad networks
    .blockTrackers()             // Block analytics
    .blockCookieBanners()        // Auto-dismiss cookie popups
    .blockChatWidgets()          // Block chat widgets
    .blockUrls(Arrays.asList("*.ads.com/*"))   // Block URL patterns
    .blockResources(Arrays.asList("font"));    // Block resource types

Browser Emulation

TakeOptions.url("...")
    .darkMode()                  // Enable dark mode
    .reducedMotion()             // Prefer reduced motion
    .mediaType("print")          // screen or print
    .userAgent("Custom UA")      // Custom user agent
    .timezone("America/New_York")
    .locale("en-US")
    .geolocation(40.7128, -74.006);

Network Options

import java.util.Map;
import java.util.HashMap;

Map<String, String> headers = new HashMap<>();
headers.put("X-Custom", "value");

TakeOptions.url("...")
    .headers(headers)
    .authBasic("user", "pass")
    .authBearer("token")
    .bypassCsp();

Cache Options

TakeOptions.url("...")
    .cacheTtl(86400)             // Cache TTL in seconds
    .cacheRefresh();             // Force refresh

PDF Options

TakeOptions.url("...")
    .format("pdf")
    .pdfPaperSize("a4")          // a4, letter, legal, etc.
    .pdfLandscape()
    .pdfMargin("1in")
    .pdfPrintBackground()
    .pdfHeader("<div>Header</div>")
    .pdfFooter("<div>Page <span class=\"pageNumber\"></span></div>");

Storage Options (BYOS)

TakeOptions.url("...")
    .storageEnabled()
    .storagePath("{year}/{month}/{hash}.{ext}")
    .storageAcl("public-read");

Cache Management

// Get cached screenshot
byte[] image = client.cache.get("cache_xyz789");

// Delete single entry
client.cache.delete("cache_xyz789");

// Bulk purge by keys
CacheManager.PurgeResponse result = client.cache.purge(
    Arrays.asList("cache_abc", "cache_def")
);
System.out.println("Purged: " + result.getPurged());

// Purge by URL pattern
client.cache.purgeUrl("https://mysite.com/blog/*");

// Purge by storage path pattern
client.cache.purgePattern("screenshots/2024/*");

// Purge by date
client.cache.purgeBefore(Instant.parse("2024-01-01T00:00:00Z"));

Webhook Helpers

import com.renderscreenshot.sdk.Webhook;
import com.renderscreenshot.sdk.Webhook.WebhookEvent;

// Verify signature
boolean isValid = Webhook.verify(payload, signature, timestamp, secret);

// Parse event
WebhookEvent event = Webhook.parse(payload);
if ("screenshot.completed".equals(event.getType())) {
    System.out.println("Screenshot completed: " + event.getData());
}

// Extract headers (case-insensitive)
String[] headers = Webhook.extractHeaders(requestHeaders);
String signature = headers[0];
String timestamp = headers[1];

Error Handling

import com.renderscreenshot.sdk.RenderScreenshotException;

try {
    byte[] image = client.take(TakeOptions.url("..."));
} catch (RenderScreenshotException e) {
    System.out.println(e.getHttpStatus());  // 400, 429, etc.
    System.out.println(e.getCode());        // "invalid_url", "rate_limited"
    System.out.println(e.getMessage());     // Human-readable message
    System.out.println(e.isRetryable());    // true/false

    if (e.isRetryable() && e.getRetryAfter() != null) {
        Thread.sleep(e.getRetryAfter() * 1000L);
        // Retry the request...
    }
}

Error Codes

Links

• JitPack package
• GitHub repository
• API Reference