Class Visitor

Create an instance of Visitor class with a given id and optional attributes and session credentials.

Example

const visitor = await new Visitor(topia, id, urlSlug, { attributes: { moveTo: { x: 0, y: 0 } }, credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" } });

Hierarchy (View Summary)

User
- Visitor

Implements

VisitorInterface

Index

Assets

fetchAssets

fetchAssets(): Promise<void | ResponseType>
Returns all assets owned by User when an email address is provided.

Returns Promise<void | ResponseType>
Example
```
await user.fetchAssets();
const userAssets = user.assets;
```
Inherited from User.fetchAssets
- Defined in controllers/User.ts:314

fetchPlatformAssets

fetchPlatformAssets(): Promise<object | ResponseType>
Returns all platform assets.

Returns Promise<object | ResponseType>
Returns the platform assets or an error response.
Example
```
const assets = await user.fetchPlatformAssets();
```
Inherited from User.fetchPlatformAssets
- Defined in controllers/User.ts:343

Avatars

addAvatar

addAvatar(formData: FormData): Promise<void | ResponseType>

Add a new avatar

Parameters

formData: FormData

Returns Promise<void | ResponseType>

Example

const animationMeta = {
  "emote": { "loop": false, "x": 0, "y": 0, "hideLoop": true }
}

const spriteSheetJSON = {
  "animations": {
    "emote": [
      "emote/1.png"
    ]
  },
  "frames": {
    "emote/1.png": {
      "frame": {
       "x": 1911,
       "y": 778,
       "w": 58,
       "h": 91
     },
     "rotated": true,
     "trimmed": true,
     "spriteSourceSize": {
       "x": 50,
       "y": 33,
       "w": 58,
       "h": 91
     },
     "sourceSize": {
       "w": 159,
       "h": 159
     }
   }
 },
 "spriteSheetTypeMeta": {
   "nameplate": {
     "x": 0,
     "y": -70
   }
 },
 "meta": {
   "image": "spriteSheets%2FTvHNjgoMkiErDNSrVqHU%2FspriteSheet.png?alt=media",
   "format": "RGBA8888",
   "size": {
     "w": 2006,
     "h": 1099
   },
   "scale": "1"
 }
}

const formData = new FormData();
formData.append('animationMeta', animationMeta);
formData.append('name', "ExampleAvatarName");
formData.append('spriteSheetJSON', spriteSheetJSON);
formData.append('expression_dance', expression_dance);
formData.append('expression_emote', expression_emote);
formData.append('expression_sit', expression_sit);
formData.append('expression_stand', expression_stand);
formData.append('expression_transport', expression_transport);
formData.append('preview', preview);
formData.append('spriteSheet', spriteSheet);
formData.append('unityPackage', unityPackage);
await user.uploadAvatarFiles("exampleAvatarId", formData);

deleteAvatar

deleteAvatar(avatarId: string): Promise<void | ResponseType>
Update avatar and sprite sheet records and upload files to existing sprite sheet and avatar storage buckets
Parameters
- avatarId: string
Returns Promise<void | ResponseType>
Example
```
await user.deleteAvatar("exampleAvatarId");
```
Inherited from User.deleteAvatar
- Defined in controllers/User.ts:291

fetchAvatars

fetchAvatars(): Promise<void | ResponseType>
Returns all avatars owned by User

Returns Promise<void | ResponseType>
Returns the avatars or an error.
Example
```
const avatars = await user.fetchAvatars();
```
Inherited from User.fetchAvatars
- Defined in controllers/User.ts:101

updateAvatar

updateAvatar(avatarId: string, formData: FormData): Promise<void | ResponseType>

Update avatar and sprite sheet records and upload files to existing sprite sheet and avatar storage buckets

Parameters

avatarId: string
formData: FormData

Returns Promise<void | ResponseType>

Example

const animationMeta = {
  "emote": { "loop": false, "x": 0, "y": 0, "hideLoop": true }
}

const spriteSheetJSON = {
  "animations": {
    "emote": [
      "emote/1.png"
    ]
  },
  "frames": {
    "emote/1.png": {
      "frame": {
       "x": 1911,
       "y": 778,
       "w": 58,
       "h": 91
     },
     "rotated": true,
     "trimmed": true,
     "spriteSourceSize": {
       "x": 50,
       "y": 33,
       "w": 58,
       "h": 91
     },
     "sourceSize": {
       "w": 159,
       "h": 159
     }
   }
 },
 "spriteSheetTypeMeta": {
   "nameplate": {
     "x": 0,
     "y": -70
   }
 },
 "meta": {
   "image": "spriteSheets%2FTvHNjgoMkiErDNSrVqHU%2FspriteSheet.png?alt=media",
   "format": "RGBA8888",
   "size": {
     "w": 2006,
     "h": 1099
   },
   "scale": "1"
 }
}

const formData = new FormData();
formData.append('animationMeta', animationMeta);
formData.append('name', "ExampleAvatarName");
formData.append('spriteSheetJSON', spriteSheetJSON);
formData.append('expression_dance', expression_dance);
formData.append('expression_emote', expression_emote);
formData.append('expression_sit', expression_sit);
formData.append('expression_stand', expression_stand);
formData.append('expression_transport', expression_transport);
formData.append('preview', preview);
formData.append('spriteSheet', spriteSheet);
formData.append('unityPackage', unityPackage);
await user.uploadAvatarFiles("exampleAvatarId", formData);

Data Objects

fetchDataObject

fetchDataObject(
 appPublicKey?: string,
 appJWT?: string,
 sharedAppPublicKey?: string,
 sharedAppJWT?: string,
): Promise<void | ResponseType>
Retrieves the data object for a visitor.
Parameters
- OptionalappPublicKey: string
- OptionalappJWT: string
- OptionalsharedAppPublicKey: string
- OptionalsharedAppJWT: string
Returns Promise<void | ResponseType>
Returns the data object or an error response.
Example
```
const dataObject = await visitor.fetchDataObject();
```
Implementation of VisitorInterface.fetchDataObject
Overrides User.fetchDataObject
- Defined in controllers/Visitor.ts:390

incrementDataObjectValue

incrementDataObjectValue(
 path: string,
 amount: number,
 options?: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 },
): Promise<void | ResponseType>
Increments a specific value in the data object for a visitor by the amount specified. Must have valid interactive credentials from a visitor in the world.
Parameters
- path: string
- amount: number
- options: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 } = {}
Returns Promise<void | ResponseType>
Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
Example
```
await visitor.incrementDataObjectValue("key", 1);
```
Implementation of VisitorInterface.incrementDataObjectValue
Overrides User.incrementDataObjectValue
- Defined in controllers/Visitor.ts:511

setDataObject

setDataObject(
 dataObject: undefined | null | object,
 options?: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 },
): Promise<void | ResponseType>
Sets the data object for a visitor.
Parameters
- dataObject: undefined | null | object
- options: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 } = {}
Returns Promise<void | ResponseType>
Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
Example
```
await visitor.setDataObject(
 { itemsCollected: 0 },
 {
 analytics: [{ analyticName: "resets"} ],
 lock: { lockId: `${assetId}-${itemsCollected}-${new Date(Math.round(new Date().getTime() / 10000) * 10000)}` },
 },
);

const { itemsCollected } = visitor.dataObject;
```
Implementation of VisitorInterface.setDataObject
Overrides User.setDataObject
- Defined in controllers/Visitor.ts:433

updateDataObject

updateDataObject(
 dataObject: object,
 options?: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 },
): Promise<void | ResponseType>
Updates the data object for a visitor.
Parameters
- dataObject: object
- options: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 } = {}
Returns Promise<void | ResponseType>
Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
Example
```
const theme = "exampleTheme";

await visitor.updateDataObject({
 [`${theme}.itemsCollectedByUser`]: { [dateKey]: { count: 1 }, total: 1 },
});

const { exampleTheme } = visitor.dataObject;
```
Implementation of VisitorInterface.updateDataObject
Overrides User.updateDataObject
- Defined in controllers/Visitor.ts:475

Dropped Assets

fetchInteractiveWorldsByKey

fetchInteractiveWorldsByKey(
interactivePublicKey: string,
): Promise<object | ResponseType>
Retrieves ids of all dropped assets in all worlds with a matching interactivePublicKey.
Parameters
- interactivePublicKey: string
Returns Promise<object | ResponseType>
Returns the urlSlugs of worlds where the Public Key is found or an error response.
Example
```
await user.fetchInteractiveWorldsByKey("interactivePublicKeyExample");
const interactiveWorlds = user.interactiveWorlds;
```
Inherited from User.fetchInteractiveWorldsByKey
- Defined in controllers/User.ts:453

Expressions

getExpressions

getExpressions(
__namedParameters: { getUnlockablesOnly?: boolean; name?: string },
): Promise<ResponseType>
Get expressions
Parameters
- __namedParameters: { getUnlockablesOnly?: boolean; name?: string }
Returns Promise<ResponseType>
Returns an array of expressions or an error response.
Example
```
await visitor.getExpressions({ getUnlockablesOnly: true, });
```
Overrides User.getExpressions
- Defined in controllers/Visitor.ts:266

grantExpression

grantExpression(
__namedParameters: { id?: string; name?: string },
): Promise<ResponseType>
Grant expression to a visitor by id or name.
Parameters
- __namedParameters: { id?: string; name?: string }
Returns Promise<ResponseType>
Returns { success: true } if the expression was granted successfully or an error response.
Example
```
await visitor.grantExpression({ id: "exampleExpressionId" });
await visitor.grantExpression({ name: "exampleExpressionName" });
```
- Defined in controllers/Visitor.ts:297

Other

constructor

new Visitor(
    topia: Topia,
    id: number,
    urlSlug: string,
    options?: VisitorOptionalInterface,
): Visitor
Parameters
- topia: Topia
- id: number
- urlSlug: string
- options: VisitorOptionalInterface = ...
Returns Visitor
Overrides User.constructor
- Defined in controllers/Visitor.ts:33

credentials

credentials: undefined | InteractiveCredentials

`Optional`dataObject

dataObject?: null | object

`Readonly`id

id: number

`Optional`jwt

jwt?: string

`Optional`profile

profile?: Record<string, any>

`Optional`profileId

profileId?: null | string

requestOptions

requestOptions: object

topia

topia: Topia

urlSlug

urlSlug: string

`Optional`user

user?: User

adminWorlds

get adminWorlds(): { [key: string]: World }
Returns { [key: string]: World }
Inherited from User.adminWorlds
- Defined in controllers/User.ts:51

assets

get assets(): { [key: string]: Asset }
Returns { [key: string]: Asset }
Inherited from User.assets
- Defined in controllers/User.ts:55

scenes

get scenes(): { [key: string]: Scene }
Returns { [key: string]: Scene }
Inherited from User.scenes
- Defined in controllers/User.ts:59

worlds

get worlds(): { [key: string]: World }
Returns { [key: string]: World }
Inherited from User.worlds
- Defined in controllers/User.ts:63

checkInteractiveCredentials

checkInteractiveCredentials(): Promise<void | ResponseType>
Returns Promise<void | ResponseType>
Inherited from User.checkInteractiveCredentials
- Defined in controllers/User.ts:77

errorHandler

errorHandler(
    __namedParameters: {
        error?: unknown;
        message?: string;
        params?: object;
        sdkMethod?: string;
    },
): {
    data: {};
    message: string;
    method: string;
    params: object;
    sdkMethod: undefined
    | string;
    stack: string;
    stackTrace: Error;
    status: number;
    success: boolean;
    url: string;
}
Parameters
- __namedParameters: { error?: unknown; message?: string; params?: object; sdkMethod?: string }
Returns {
    data: {};
    message: string;
    method: string;
    params: object;
    sdkMethod: undefined | string;
    stack: string;
    stackTrace: Error;
    status: number;
    success: boolean;
    url: string;
}
Inherited from User.errorHandler
- Defined in controllers/SDKController.ts:97

fetchVisitor

fetchVisitor(): Promise<void | ResponseType>
Get a single visitor from a world

Returns Promise<void | ResponseType>
Returns details for a visitor in a world by id and urlSlug
Example
```
await visitor.fetchVisitor();
```
Implementation of VisitorInterface.fetchVisitor
- Defined in controllers/Visitor.ts:56

fireToast

fireToast(__namedParameters: FireToastInterface): Promise<void | ResponseType>
Display a message via a toast to a visitor currently in a world.
Parameters
- __namedParameters: FireToastInterface
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Example
```
await visitor.fireToast({
 groupId: "custom-message",
 title: "Hello World",
 text: "Thank you for participating!",
});
```
Implementation of VisitorInterface.fireToast
- Defined in controllers/Visitor.ts:123

moveVisitor

moveVisitor(
__namedParameters: MoveVisitorInterface,
): Promise<void | ResponseType>
Teleport or walk a visitor currently in a world to a single set of coordinates.
Parameters
- __namedParameters: MoveVisitorInterface
Returns Promise<void | ResponseType>
Returns { success: true } if the visitor was moved successfully.
Example
```
await visitor.moveVisitor({
 shouldTeleportVisitor: true,
 x: 100,
 y: 100,
});
```
Implementation of VisitorInterface.moveVisitor
- Defined in controllers/Visitor.ts:90

sendEmail

sendEmail(
__namedParameters: { html: string; subject: string; to: string },
): Promise<object | ResponseType>
Send an email
Parameters
- __namedParameters: { html: string; subject: string; to: string }
Returns Promise<object | ResponseType>
Returns { success: true } if the email is sent successfully or an error response.
Example
```
const html = `Hello World!This email is being sent from via SDK.`
await user.sendEmail({ html, subject: "Example", to: "example@email.io" });
```
Inherited from User.sendEmail
- Defined in controllers/User.ts:476

sendSignalToVisitor

sendSignalToVisitor(
signal: any,
): Promise<void | ResponseType & { answerSignal: any }>
Setup signal to visitor
Parameters
- signal: any
Returns Promise<void | ResponseType & { answerSignal: any }>
Example
```
await visitor.sendSignalToVisitor(iceServers);
```
- Defined in controllers/Visitor.ts:566

topiaPublicApi

topiaPublicApi(): AxiosInstance
Returns AxiosInstance
Inherited from User.topiaPublicApi
- Defined in controllers/SDKController.ts:93

turnAVOff

turnAVOff(): Promise<void | ResponseType>
Mute and turn video off for a visitor currently in a world.

Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Example
```
await visitor.turnAVOff();
```
- Defined in controllers/Visitor.ts:242

updatePublicKeyAnalytics

updatePublicKeyAnalytics(
analytics?: AnalyticType[],
): Promise<void | ResponseType>
Update analytics for a given public key. Must have valid interactive credentials from a visitor in the world.
Parameters
- Optionalanalytics: AnalyticType[]
Returns Promise<void | ResponseType>
Example
```
await visitor.updatePublicKeyAnalytics([{ analyticName: "joins", profileId, uniqueKey: profileId, urlSlug }]);
```
- Defined in controllers/Visitor.ts:546

Particle Effects

getAllParticles

getAllParticles(): Promise<ResponseType>
Get all particles available

Returns Promise<ResponseType>
Returns an array of particles or an error response.
Example
```
await visitor.getAllParticles();
```
- Defined in controllers/Visitor.ts:328

triggerParticle

triggerParticle(
__namedParameters: { duration?: number; id?: string; name?: string },
): Promise<string | ResponseType>
Trigger a particle effect on a visitor
Parameters
- __namedParameters: { duration?: number; id?: string; name?: string }
Returns Promise<string | ResponseType>
Returns { success: true } or a message if no particleId is found.
Example
```
await visitor.triggerParticle({ name: "Flame" });
```
- Defined in controllers/Visitor.ts:349

Scenes

fetchScenes

fetchScenes(): Promise<void | ResponseType>
Returns all scenes owned by User.

Returns Promise<void | ResponseType>
Example
```
await user.fetchScenes();
const userScenes = user.scenes;
```
Inherited from User.fetchScenes
- Defined in controllers/User.ts:363

Worlds

fetchAdminWorldsByKey

fetchAdminWorldsByKey(): Promise<void | ResponseType>
Retrieves all worlds a user with matching API Key is an admin in, creates a new World object for each, and creates new map of Worlds accessible via user.adminWorlds.

Returns Promise<void | ResponseType>
Example
```
await user.fetchAdminWorldsByKey();
const adminWorlds = user.adminWorlds;
```
Inherited from User.fetchAdminWorldsByKey
- Defined in controllers/User.ts:424

fetchWorldsByKey

fetchWorldsByKey(): Promise<void | ResponseType>
Retrieves all worlds owned by user with matching API Key, creates a new World object for each, and creates new map of Worlds accessible via user.worlds.

Returns Promise<void | ResponseType>
```
{ urlSlug: new World({ apiKey, worldArgs, urlSlug }) }
```
Example
```
await user.fetchWorldsByKey();
const userWorlds = user.worlds;
```
Inherited from User.fetchWorldsByKey
- Defined in controllers/User.ts:396

iframes

closeIframe

closeIframe(droppedAssetId: string): Promise<void | ResponseType>
Close an iframe for a visitor currently in a world.
Parameters
- droppedAssetId: string
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Example
```
await visitor.closeIframe("droppedAssetId");
```
- Defined in controllers/Visitor.ts:219

openIframe

openIframe(__namedParameters: OpenIframeInterface): Promise<void | ResponseType>
Open an iframe in a drawer or modal for a visitor currently in a world.
Parameters
- __namedParameters: OpenIframeInterface
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Example
```
await visitor.openIframe({
 droppedAssetId: "droppedAssetId",
 link: "https://topia.io",
 shouldOpenInDrawer: true,
 title: "Hello World",
});
```
Implementation of VisitorInterface.openIframe
- Defined in controllers/Visitor.ts:158

reloadIframe

reloadIframe(droppedAssetId: string): Promise<void | ResponseType>
Reload an iframe for a visitor currently in a world.
Parameters
- droppedAssetId: string
Returns Promise<void | ResponseType>
Returns { success: true } or an error.
Example
```
await visitor.reloadIframe("droppedAssetId");
```
- Defined in controllers/Visitor.ts:194

Class Visitor

Example

Hierarchy (View Summary)

Implements

Index

Assets

Avatars

Data Objects

Dropped Assets

Expressions

Other

Particle Effects

Scenes

Worlds

iframes

Assets

fetchAssets

Returns Promise<void | ResponseType>

Example

fetchPlatformAssets

Returns Promise<object | ResponseType>

Example

Avatars

addAvatar

Parameters

Returns Promise<void | ResponseType>

Example

deleteAvatar

Parameters

Returns Promise<void | ResponseType>

Example

fetchAvatars

Returns Promise<void | ResponseType>

Example

updateAvatar

Parameters

Returns Promise<void | ResponseType>

Example

Data Objects

fetchDataObject

Parameters

Returns Promise<void | ResponseType>

Example

incrementDataObjectValue

Parameters

Returns Promise<void | ResponseType>

Remarks

Example

setDataObject

Parameters

Returns Promise<void | ResponseType>

Remarks

Example

updateDataObject

Parameters

Returns Promise<void | ResponseType>

Remarks

Example

Dropped Assets

fetchInteractiveWorldsByKey

Parameters

Returns Promise<object | ResponseType>

Example

Expressions

getExpressions

Parameters

Returns Promise<ResponseType>

Example

grantExpression

Parameters

Returns Promise<ResponseType>

Example

Other

constructor

Parameters

Returns Visitor

credentials

OptionaldataObject

Readonlyid

Optionaljwt

`Optional`dataObject

`Readonly`id

`Optional`jwt

`Optional`profile

`Optional`profileId

`Optional`user

Returns {
data: {};
message: string;
method: string;
params: object;
sdkMethod: undefined | string;
stack: string;
stackTrace: Error;
status: number;
success: boolean;
url: string;
}