# Iframes

What both iframes share: the tag, the item, your brand, the HUD options and the messages they post to your page. The SDK draws its viewer in an iframe too, so part of this page holds for it.

## Embed an iframe

Both iframes are the same tag at their own address. The viewer fills the iframe: give it the size you want. Below 768 px wide, it switches to its compact mobile layout. Once you have a key, the [builder](https://render.vskin.gg/builder) writes the tag for you with it and your settings.

```html
<iframe
    id="item-viewer"
    title="CS2 item viewer"
    src="https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&cert=80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A"
    width="800"
    height="500"
    style="border: 0; color-scheme: normal"
    allow="fullscreen; clipboard-write"
></iframe>
```

Pick the one that fits your page:

[Basic iframe](https://render.vskin.gg/docs/iframe-basic): A simple, minimal HUD around the item. Perfect for showing what a skin looks like in the game.

[Advanced iframe](https://render.vskin.gg/docs/iframe-advanced): A fuller HUD with advanced features, from first-person view to sticker placement. Perfect for trying out combos and crafts.

> Several viewers can run in 3D on the same page, SDK viewers included, to compare two items side by side for instance. Each one holds its own 3D memory: open a viewer when a visitor asks for an item, remove it when they move on, and keep to two or three at once, fewer on phones. If the browser runs out and stops a viewer’s 3D, that viewer shows its backdrop with a “View in 3D” button until a visitor clicks it.

## Choose the item

Name the item in one of two ways: by its certificate, which carries the whole item, or field by field. If both are present, `cert` wins.

### With a certificate

`cert` is the item's certificate, a hex string that Steam's public inventory API returns for every item, as the asset property whose `propertyid` is 6. Recent inspect links also end with it; older ones carry none. It is the best choice: a single value that carries the whole item exactly as it is in the game, from its skin, pattern seed and wear to its StatTrak™, name tag, stickers and charm. The example is a StatTrak™ AK-47 | Inheritance (Field-Tested) with Hydro Wave and Hydro Stream stickers and the Pinch O' Salt charm.

```url
https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&cert=80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A
```

### Field by field

`def` (defindex) and `paint` (paint kit index) name the skin and are both required. Add only what you need: `seed`, `float`, `stattrak`, `kills`, `name`, `stickers` and `charm`. Stickers take an id and a slot here; their wear and position come only with a certificate or through the SDK. The example describes the same AK-47 | Inheritance with two of its stickers.

```url
https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&def=7&paint=1171&seed=470&float=0.3272&stattrak=1&kills=1&stickers=7924:1,7923:2&charm=12:85594
```

An agent is named by its defindex with `paint=0`, like a weapon without a skin, and wears patches by slot. Here, Sir Bloody Miami Darryl with two patches:

```url
https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&def=4726&paint=0&patches=4550:0,4553:1
```

The SDK names items the same two ways: `cert`, or `defIndex` and `paintIndex` with the fields you need.

[Every option in URL options](https://render.vskin.gg/docs/url-options)

## Match your brand

Both iframes take your colors through the `theme-*` options when you have the Brand option, and your visitors' language through `lang`. `backdrop=false` lets your page show behind the item, and `watermark=false` removes the watermark, ours or yours.

```url
https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&theme-primary=ff7a00&lang=fr&backdrop=false&watermark=false
```

With the Brand option, `backdrop-image` and `watermark-image` show one of your own backdrops and watermarks at the showroom, in place of ours; a map keeps its own scenery. You upload and name them in your [dashboard](https://render.vskin.gg/dashboard) or in the [builder](https://render.vskin.gg/builder), up to 5 of each when your plan has Brand and fewer otherwise: your dashboard shows how many. A key shows them when its plan has Brand. Your test key has Brand without a subscription, and with one, you can give it such a plan in your dashboard. An address names each one by its id. An id that is not one of your files, or that your key's plan does not open, is ignored, and the viewer shows ours.

```url
https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&backdrop-image=bkg_your_backdrop_id&watermark-image=wmk_your_watermark_id
```

**Backdrops and watermarks** follow the same rules: a PNG, JPEG or WebP of up to 5 MB, at the resolution you choose, with at most 8,000 pixels on a side and 40 megapixels in all. Each covers the viewer, cropped from its center, the watermark over the backdrop and behind the item. We show your watermark as you made it: for a see-through one, upload a transparent PNG or WebP. To fit your images to your viewers, preview them at their size in the [builder](https://render.vskin.gg/builder).

We convert each file to WebP, at most 2,560 pixels on its long side. Anyone who has the link to a file can see it: upload nothing private.

## Shape the HUD

Hide the whole HUD with `hud=false`, or one element with its own option, such as `hud-item-card=false`. Each iframe draws its own elements, listed on its page. When the viewer is 768 px wide or more, `hud-size` scales the HUD.

```url
https://embed.render.vskin.gg/v1/iframe-basic?key=pk_prod_your_key&hud-item-card=false&hud-size=small
```

> These options only hide elements. Which elements exist depends on your plan.

[Every feature, where it works and its plan, in Features and plans](https://render.vskin.gg/docs/features)

## Listen to the iframe

Both iframes post these messages to your page. Listening is optional.

- `ready`: The viewer has loaded and was not refused.
- `view`: The 3D renderer has started. Sent once per page load.
- `refused`: The service refused to open the viewer. `refusalCode` gives the reason, as a code, and `family` says who can fix it.

```js
const iframe = document.getElementById('item-viewer');

window.addEventListener('message', (event) => {
    if (event.source !== iframe.contentWindow) return;
    const { source, type, family, refusalCode } = event.data ?? {};
    if (source !== 'vskin-render') return;

    if (type === 'refused') {
        console.warn('Viewer refused:', family, refusalCode);
    }
});
```

[Each code and its fix in Errors](https://render.vskin.gg/docs/errors)
