Commons body params

All render methods share three body properties: doppio, launch and page. Let's look at each of them:

☝️ Keep in mind, most parameters are optional.

About params

The parameters we expose are modeled from Puppeteer API.

`doppio`

{
  "doppio": {
    "presignedUrl": "string",
    "contentDisposition": "inline"
  }
}

The presignedUrl property defines the URL we will use to upload your document into your S3 bucket. For more information about how it works, please read Upload to your S3 bucket. If not set, the document will be stored temporarily in our own S3 bucket.

The contentDisposition property determines how the uploaded file is presented to the user. It can be set to inline (to display the document within the browser) or attachment (to prompt the user to download the file). If this property is not specified, the upload proceeds without setting this header, and will default according to the bucket's default behavior or setting.

When using a custom presigned URL, ensure that your bucket supports setting this header.

☝️ This property can also be used without a presigned URL.

Property details:

Property name	Type	Description
`presignedUrl`	string	S3 upload URL `Optional`
`contentDisposition`	string	"inline" or "attachment" `Optional`

`launch`

{
  "launch": {
    "defaultViewport": {
      "width": 0,
      "height": 0,
      "deviceScaleFactor": 0,
      "isMobile": true,
      "hasTouch": true,
      "isLandscape": true
    }
  }
}

The launch object exposes properties from Puppeteer's BrowserConnectOptions

Properties details:

Property name	Type	Description
`defaultViewport`	`Viewport`	Sets the viewport for each page. `Optional`

`defaultViewport` properties:

Property name	Type	Default value	Description
`width`	number	1920	The page width in pixels. `Optional`
`height`	number	1080	The page height in pixels. `Optional`
`deviceScaleFactor`	number	1	Specify device scale factor. Set value from 1 minimum to maximum 2. See devicePixelRatio for more info. `Optional`
`isMobile`	boolean	false	Whether the meta viewport tag is taken into account. `Optional`
`hasTouch`	boolean	false	Specify if the viewport supports touch events. `Optional`
`isLandscape`	boolean	false	Specify if the viewport is in landscape mode. `Optional`

`page`

Most of the properties are optional 😌

{
  "page": {
    "goto": {
      "url": "https://doc.doppio.sh",
      "options": {
        "waitUntil": ["load"],
        "referer": "https://doc.doppio.sh"
      }
    },
    "setContent": {
      "html": "PHA+ZG9wcGlvLnNoPC9wPg==",
      "options": {
        "waitUntil": ["networkidle0"]
      }
    },
    "setJavaScriptEnabled": true,
    "emulateMediaType": "print",
    "setExtraHTTPHeaders": {},
    "emulateTimezone": "America/New_York",
    "authenticate": {
      "username": "thisisausername",
      "password": "thisisapassword"
    },
    "setCookies": [],
    "setUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 13_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.5 Safari/605.1.15",
    "setLocalStorageItems": [],
    "waitForFunction": {
      "pageFunction": "() => !document.querySelector('.loading')",
      "options": { "timeout": 10000 }
    },
    "waitForSelector": {
      "selector": "#invoice-ready",
      "options": { "timeout": 10000, "visible": true }
    },
    "pdf": { ... },
    "screenshot": { ... },
  }
}

The page property defines the page your want to render, how to access it and other render options. Some properties varies depending on whether you want to render a PDF or a screenshot.

Property name	Type	Description
`goto`	`Goto`	Your document URL source, if available online.
`setContent`	`SetContent`	Your document HTML content source in base64, if not.
`setJavaScriptEnabled`	boolean	Whether or not to enable JavaScript on the source page. Enabled by default. `optional`
`setUserAgent`	string	Sets a custom User-Agent header. `optional`
`emulateMediaType`	string	Changes the CSS media type of the page. The only allowed values are `screen`, `print` and `null`. Passing `null` disables CSS media emulation. `optional`
`emulateTimezone`	string	Changes the timezone of the page by providing the timezone id (`America/New_York`, `Europe/Paris`, `Asia/Tokyo`, ...). `optional`
`setExtraHTTPHeaders`	Record<string, string>	An object containing additional HTTP headers to be sent with every request. All header values must be strings. `optional`
`authenticate`	`Credentials`	Provides credentials for HTTP authentication. `optional`
`setCookies`	array of Network.CookieParam	Cookies list. Format follows Protocol.Network.CookieParam without experimental features. `optional`
`setLocalStorageItems`	array of { key: string, value: string }	This is Doppio specific. `optional`
`waitForFunction`	waitForFunctionParameters	Waits for a function to finish evaluating in the page's context. `optional`
`waitForSelector`	waitForSelectorParameters	Wait for the selector to appear in page. `optional`
`pdf`	PDFOptions	Options to configure PDF generation. Only available for PDF render. `optional`
`screenshot`	ScreenshotOptions	Options to configure screenshot generation. Only available for screenshot render. `optional`

⚠️ WARNING

goTo and setContent properties can't be use at the same time. They are mutually exclusive. At least one of them must be set.

💡 TIP

All HTTP header names are lowercased (HTTP headers are case-insensitive, so this shouldn’t impact your server code).

ℹ INFO

page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.

-> LINKS

For PDF configuration see PDF params.
For screenshot configuration see screenshot params.

`goto` properties:

Property name	Type	Description
`url`	string	URL to navigate the page to. The URL should include the scheme, e.g. `https://`
`options`	`GotoOptions`	Navigation Parameter. `optional`

`setContent` properties:

Property name	Type	Description
`html`	string	Your page HTML encoded as base64
`options`	`SetContentOptions`	Navigation Parameter. `optional`

`GotoOptions` properties:

Exposes some properties of Puppeteer's page.goTo method options.

Property name	Type	Description
`waitUntil`	array of strings	Wait for puppeteer life cycle events. Possible values are `load`, `domcontentloaded`, `networkidle0` and `networkidle2`. `optional`
`referer`	string	The referer. Will override the one set in `setExtraHTTPHeaders`. `optional`

`SetContentOptions` properties:

Exposes some properties of Puppeteer's page.goTo method options.

Property name	Type	Description
`waitUntil`	array of strings	Wait for puppeteer life cycle events. Possible values are `load`, `domcontentloaded`, `networkidle0` and `networkidle2`. `optional`

`authenticate` properties:

Credentials to pass to Puppeteer's page.authenticate method.

Property name	Type	Description
`username`	string	User name credential.
`password`	string	Password credential.

`waitForFunction` properties:

Exposes some properties of Puppeteer's page.waitForFunction method waitForFunction.

Property name	Type	Description
`pageFunction`	string	Function to be evaluated in the page. Must return a truthy value when the condition is met (e.g. `"() => document.readyState === 'complete'"`).
`options`	`FrameWaitForFunctionOptions`	Optional `timeout` (ms), `polling` (`'raf'`, `'mutation'` or number in ms). See FrameWaitForFunctionOptions.

Timeout

waitForFunction can fail with a timeout if the condition is never satisfied. Set a realistic timeout in options and ensure your page can reach the condition (e.g. loading finishes, data is rendered).

Common use cases:

Wait until loading is done: "pageFunction": "() => !document.querySelector('.loading')" — capture only after the loading indicator is removed.
Wait for app-ready flag (SPA): "pageFunction": "() => window.__APP_READY__ === true" — if your app sets a global when it has finished rendering.
Wait for a minimum number of items: "pageFunction": "() => document.querySelectorAll('.list-item').length >= 10" — e.g. for a list or table that loads asynchronously.

`waitForSelector` properties:

Exposes some properties of Puppeteer's page.waitForSelector method waitForSelector.

Property name	Type	Description
`selector`	string	CSS selector of the element to wait for (e.g. `"#content"`, `".chart-container"`, `"[data-rendered]"`).
`options`	`WaitForSelectorOptions`	Optional `timeout` (ms), `visible` (wait until element is visible), `hidden` (wait until element is hidden). See WaitForSelectorOptions.

Timeout

waitForSelector can fail with a timeout if the selector never appears (or never becomes visible/hidden). Use a timeout that fits your page load time.

Common use cases:

Wait for content before PDF/screenshot: "selector": "#invoice" or "selector": ".report-ready" — ensure the main content exists before capture.
Wait for a chart or iframe: "selector": "canvas" or "selector": ".dashboard-loaded" — useful when the page draws content after data is fetched.
Wait for loading to disappear: "selector": ".spinner", "options": { "hidden": true, "timeout": 10000 } — capture only after the spinner is gone.

Commons body params #

doppio #

Property details: #

launch #

Properties details: #

defaultViewport properties: #

page #

goto properties: #

setContent properties: #

GotoOptions properties: #

SetContentOptions properties: #

authenticate properties: #

waitForFunction properties: #

waitForSelector properties: #