Skip to content
VSkin Render

SDK

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: the builder's sandbox keys do not open it. To subscribe, contact us on Discord or at 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 (opens in a new tab)Read more in 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

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

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