# Quickstart

Build your own HUD and your own features around the viewer. The SDK drives it from your code, with typed commands, live state and events, and no dependencies.

## Install

> The SDK comes with the Native plan, on quote. To try it on your own machine, give your test key the Native plan in your [dashboard](https://render.vskin.gg/dashboard): the builder's sandbox keys do not open it. To subscribe, contact us on [Discord](https://discord.com/invite/vURPrA8ppg) or at [contact@vskin.gg](mailto:contact@vskin.gg).

Install the package from npm:

```shell
npm install @vskin/sdk
```

Or load it with a script tag. This address always serves the latest 1.x, so fixes reach you with nothing to change. Do not add an `integrity` attribute: the file changes with each release. To pin a version, install from npm.

```html
<div id="viewer" style="width: 800px; height: 500px"></div>
<script src="https://embed.render.vskin.gg/v1/embed.js"></script>
<script>
    VskinSdk.createViewer({
        container: document.getElementById('viewer'),
        key: 'pk_prod_your_key',
    });
</script>
```

## Create a viewer

Give it an element with a size, and your key. It resolves once the viewer answers; the `ready` event follows when the item is on screen. The viewer shows no loading state or failure message of its own: show your loading state until `ready`, then whenever the `progress` event says it is loading, and your own message on `unavailable` and `error`.

```ts
import { createViewer } from '@vskin/sdk';

// The viewer fills this element: give it a size.
const container = document.getElementById('viewer')!;

const viewer = await createViewer({
    container,
    key: 'pk_prod_your_key',
    weapon: { cert: "80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A" },
});
```

The viewer is an iframe on our origin, created inside that element. Naming the item, several viewers on one page and the refusal families work as for the iframes.

[See it live on Magpie, a demo store](https://magpie.demo.render.vskin.gg)

[Read more in Iframes](https://render.vskin.gg/docs/iframes)

## Drive the viewer

Every command returns a promise. Listen to events to follow what the visitor does.

```ts
await viewer.setView({ view: 'firstPerson' });
await viewer.setStickers({
    stickers: [{ id: 7924, slot: 1 }, { id: 7923, slot: 2 }],
});
await viewer.setCharm({ charm: { id: 12, pattern: 85594 } });
await viewer.setWatermark({
    watermark: { type: 'custom', id: 'wmk_your_watermark_id' },
});

viewer.on('change', () => {
    console.log(viewer.state.stickers);
});
```

Commands, options and state are typed, so your editor lists them as you write.

[Every command in Viewer API](https://render.vskin.gg/docs/sdk/api)

## Any framework

The SDK also gives the viewer as an element, `vskin-render-viewer`, that any framework, or a page alone, can write. The script tag above defines it; from npm, import `@vskin/sdk/element` once. Give the element a size, and your key in `viewer-key`.

```html
<vskin-render-viewer
    viewer-key="pk_prod_your_key"
    style="width: 800px; height: 500px"
></vskin-render-viewer>

<script>
    const element = document.querySelector('vskin-render-viewer');

    element.addEventListener('vskin-render-ready', ({ detail }) =>
        detail.viewer.setWeapon({ weapon: { cert: "80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A" } }),
    );
</script>
```

It takes the options of `createViewer`: a simple one as an attribute or a property, an object such as `weapon` as a property. It reads them once, when it enters the page, and after that only follows changes to `locale`: drive the viewer through the handle that `vskin-render-ready` hands over; the element's `viewer` property holds the same handle. `vskin-render-error` tells why a viewer could not start, a refusal included. Removed from the page, the element destroys its viewer; back in, it starts a new one.

### Vue

Tell Vue's compiler, once, that the element is not one of its components, with `isCustomElement`. Vue then hands it its properties.

```ts
// vite.config.ts
export default defineConfig({
    plugins: [
        vue({
            template: {
                compilerOptions: {
                    isCustomElement: (tag) => tag === 'vskin-render-viewer',
                },
            },
        }),
    ],
});
```

```html
<script setup lang="ts">
import '@vskin/sdk/element';
import type { RenderViewerReadyDetail } from '@vskin/sdk';

const weapon = { cert: "80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A" };

const onReady = ({ detail }: CustomEvent<RenderViewerReadyDetail>) =>
    detail.viewer.setView({ view: 'firstPerson' });
</script>

<template>
    <vskin-render-viewer
        viewer-key="pk_prod_your_key"
        :weapon="weapon"
        @vskin-render-ready="onReady"
        style="width: 800px; height: 500px"
    />
</template>
```

### Angular

Allow the element in each component that writes it, with `CUSTOM_ELEMENTS_SCHEMA`.

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@vskin/sdk/element';
import type { RenderViewerReadyDetail } from '@vskin/sdk';

@Component({
    selector: 'app-item-viewer',
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    template: `
        <vskin-render-viewer
            viewer-key="pk_prod_your_key"
            [weapon]="weapon"
            (vskin-render-ready)="onReady($event)"
            style="width: 800px; height: 500px"
        ></vskin-render-viewer>
    `,
})
export class ItemViewerComponent {
    protected readonly weapon = { cert: "80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A" };

    protected onReady(event: Event): void {
        const { detail } = event as CustomEvent<RenderViewerReadyDetail>;
        void detail.viewer.setView({ view: 'firstPerson' });
    }
}
```

### Svelte

Nothing to set: Svelte hands the element its properties.

```html
<script lang="ts">
    import '@vskin/sdk/element';
    import type { RenderViewerReadyDetail } from '@vskin/sdk';

    const weapon = { cert: "80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A" };

    const onReady = ({ detail }: CustomEvent<RenderViewerReadyDetail>) =>
        detail.viewer.setView({ view: 'firstPerson' });
</script>

<vskin-render-viewer
    viewer-key="pk_prod_your_key"
    {weapon}
    onvskin-render-ready={onReady}
    style="width: 800px; height: 500px"
></vskin-render-viewer>
```

On a page your server renders, show the element in the browser only, for instance inside `ClientOnly` with Nuxt. An element the server writes starts as soon as the browser defines it, before your framework hands it its properties. With Next.js, use the React component in a client component: it starts the viewer in the browser only.

[The element's options and events in Viewer API](https://render.vskin.gg/docs/sdk/api#render-viewer-element)

## React

The React component owns the viewer's lifecycle. It reads its props once, at mount, except `locale`: drive the viewer through the handle `onViewer` receives, and catch a refusal with `onError`. Your key goes in `viewerKey`, since React reserves `key`.

```tsx
import { RenderViewer } from '@vskin/sdk/react';

export const ItemViewer = () => (
    <RenderViewer
        viewerKey="pk_prod_your_key"
        weapon={{ cert: "80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A" }}
        onViewer={({ viewer }) => viewer.setView({ view: 'firstPerson' })}
        onError={({ error }) => console.warn(error.code)}
        style={{ width: 800, height: 500 }}
    />
);
```

## Handle a refusal

When the service refuses the viewer, `createViewer` rejects at once with the family of the refusal and its code, `refusalCode`. The iframe stays in your container and shows a notice with that code, in the `locale` you passed, English by default. To hide it, empty the container.

```js
try {
    await createViewer({ container, key: 'pk_prod_your_key' });
} catch (error) {
    if (error.code === 'refused') {
        console.warn('Viewer refused:', error.family, error.refusalCode);
    }
}
```

The error's `family` says who can fix it.

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