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:
npm install @vskin/sdkOr 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.
<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.
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 IframesDrive the viewer
Every command returns a promise. Listen to events to follow what the visitor does.
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 APIAny 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.
<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.
// vite.config.ts
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag === 'vskin-render-viewer',
},
},
}),
],
});<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.
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.
<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.
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.
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.
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.