Tag | Matterport SDK
Usage of the SDK constitutes your agreement with the Matterport SDK Agreement. Email developers@matterport.com with any questions.

Index

Types

AllowableActions

AllowableActions: object

The actions that can be taken when interacting with a tag

Type declaration

  • docking: boolean

    Whether the tag can be docked

  • navigating: boolean

    Whether navigation towared the tag will occur when clicked

  • opening: boolean

    Whether the tag can be opened via a mouse hover

  • sharing: boolean

    Whether the tag has a share button

Attachment

Attachment: object

Things such as media, etc that can be attached to a Tag. Attachments are the new equivalent to Media in Mattertags.

Type declaration

Descriptor

Descriptor: object

A subset of the TagData used when adding Tags. Most properties are optional except those used for positioning: anchorPosition, stemVector.

Type declaration

  • anchorPosition: Vector3
  • Optional attachments?: string[]
  • Optional color?: Color
  • Optional description?: undefined | string
  • Optional iconId?: undefined | string
  • Optional id?: undefined | string
  • Optional label?: undefined | string
  • Optional opacity?: undefined | number
  • stemVector: Vector3
  • Optional stemVisible?: undefined | false | true

EditableProperties

EditableProperties: object

Type declaration

  • description: string
  • label: string

GlobalVariableMap

GlobalVariableMap: object

Map the globals we provide in your sandbox to other names.

Type declaration

  • Optional docked?: undefined | string
  • Optional off?: undefined | string
  • Optional on?: undefined | string
  • Optional send?: undefined | string
  • Optional tag?: undefined | string

OpenOptions

OpenOptions: object

Type declaration

  • force: boolean

    Force the tag open regardless of whether its allowed from previous calls to Tag.allowAction

OpenTags

OpenTags: object

Type declaration

  • docked: string | null

    The id of the tag that is currently docked.

  • hovered: string | null

    The id of the tag that is currently being previewed or hovered over.

  • selected: Set<string>

    The set of ids of tags that are currently "stuck" open like from a click action. Currently, this is limited to just one tag.

PositionOptions

PositionOptions: object

Type declaration

SandboxOptions

SandboxOptions: object

Type declaration

  • globalVariableMap: Tag.GlobalVariableMap

    A map for the three global functions we provide in your sandbox. Only needs to be used if scripts you are importing also have a global send, on, off, tag, or docked.

  • name: string

    A human readable name that will be used as the src in the attachments collection.

  • size: Size

    The size of the sandbox to display Providing 0 as one of the dimensions will instead use the default: 150px for height, 100% for width.

StemHeightEditOptions

StemHeightEditOptions: object

Type declaration

  • stemHeight: number
  • stemVisible: boolean

TagData

TagData: object

Type declaration

  • anchorPosition: Vector3
  • attachments: string[]

    The ids of the attachments currently attached to this tag

  • color: Color
  • description: string
  • discPosition: Vector3
  • fontId: string

    Read-only Font Awesome id for icons set in workshop, e.g. "face-grin-tongue-squint" This value does not change if Tag.editIcon is used. This value is an empty string if no fontId was set.

  • id: string
  • keywords: string[]
  • label: string
  • roomId: string
  • stemHeight: number
  • stemVector: Vector3
  • stemVisible: boolean

Properties

attachments

embed
bundle

Introduced 3.1.68.12-7-g858688944a

An observable collection of the Attachment.

mpSdk.Tag.attachments.subscribe({
  onAdded: function (index, item, collection) {
    console.log('An attachment was added to the collection', index, item, collection);
  },
  onCollectionUpdated(collection) {
    console.log('The entire collection of attachments', collection);
  },
});

data

embed
bundle

Introduced 3.1.68.12-7-g858688944a

An observable collection of Tag data that can be subscribed to.

When first subscribing, the current set of Tags will call the observer's onAdded for each Tag as the data becomes available.

mpSdk.Tag.data.subscribe({
  onAdded(index, item, collection) {
    console.log('Tag added to the collection', index, item, collection);
  },
  onRemoved(index, item, collection) {
    console.log('Tag removed from the collection', index, item, collection);
  },
  onUpdated(index, item, collection) {
    console.log('Tag updated in place in the collection', index, item, collection);
  },
  onCollectionUpdated(collection) {
    console.log('The full collection of Tags looks like', collection);
  }
});

openTags

embed
bundle

Introduced 23.2.1

An observable state of that tags that are hovered, selected, or docked. A Tag can be in all three states at once. A docked tag is also always considered selected.

mpSdk.Tag.openTags.subscribe({
  prevState: {
    hovered: null,
    docked: null,
    selected: null,
  },
  onChanged(newState) {
    if (newState.hovered !== this.prevState.hovered) {
      if (newState.hovered) {
        console.log(newState.hovered, 'was hovered');
      } else {
        console.log(this.prevState.hovered, 'is no longer hovered');
      }
    }
    if (newState.docked !== this.prevState.docked) {
      if (newState.docked) {
        console.log(newState.docked, 'was docked');
      } else {
        console.log(this.prevState.docked, 'was undocked');
      }
    }

    // only compare the first 'selected' since only one tag is currently supported
    const [selected = null] = newState.selected; // destructure and coerce the first Set element to null
    if (selected !== this.prevState.selected) {
        if (selected) {
            console.log(selected, 'was selected');
        } else {
            console.log(this.prevState.selected, 'was deselected');
        }
    }

    // clone and store the new state
    this.prevState = {
      ...newState,
      selected,
    };
  },
});

Methods

add

  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Add one or more Tags to Showcase. Each input Tag supports setting the label, description, color or icon, anchorPosition, stemVector, and attachments.

    Two properties are required:

    • anchorPosition, the point where the tag connects to the model
    • stemVector, the direction, aka normal, and height that the Tag stem points

    See Pointer.intersection for a way to retrieve a new anchorPosition and stemVector.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session. They also do not have "share" buttons as they associated with them.

    mpSdk.Tag.add({
     label: 'New tag',
     description: 'This tag was added through the Matterport SDK',
     anchorPosition: {
       x: 0,
       y: 0,
       z: 0,
     },
     stemVector: { // make the Tag stick straight up and make it 0.30 meters (~1 foot) tall
       x: 0,
       y: 0.30,
       z: 0,
     },
     color: { // blue disc
       r: 0.0,
       g: 0.0,
       b: 1.0,
     },
    }, {
     label: 'New tag 2',
     anchorPosition: {
       x: 1,
       y: 2,
       z: 3,
     },
     stemVector: {
       x: ,
       y: ,
       z: ,
     }
    });
    

    Parameters

    • Rest ...tags: Tag.Descriptor[]

      The descriptors for all Tags to be added.

    Returns Promise<string[]>

    A promise that resolves with the array of ids for the newly added Tags.

allowAction

  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Sets the allowed "default" Showcase actions on a Tag from occurring: hover to open billboard, click to navigate to view. If an action is ommited from the actions argument, it will be considered false by default.

    const tagIds: string[]; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    
    // prevent navigating to the tag on click
    const noNavigationTag = tagIds[0];
    mpSdk.Tag.allowAction(noNavigationTag, {
      opening: true,
      // implies navigating: false, etc
    });
    
    // prevent the billboard from showing
    const noBillboardTag = tagIds[1];
    mpSdk.Tag.allowAction(noBillboardTag, {
      navigating: true,
      // implies opening: false, etc
    });
    
    const noActionsTag = tagIds[2];
    mpSdk.Tag.allowAction(noActionsTag, {
      // implies opening: false and navigating: false, etc
    });
    

    Parameters

    • id: string

      The id of the Tag to change the allowed actions

    • actions: Partial<Tag.AllowableActions>

      The set of actions allowed on the Tag

    Returns Promise<void>

attach

  • attach(tagId: string, ...attachmentIds: string[]): Promise<void>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Attach Attachment to a Tag.

    const tagId: string; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    const attachmentIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.registerAttachment` or through `mpSdk.Tag.attachments`
    
    mpSdk.Tag.attach(tagId, ...attachmentIds);
    // or
    mpSdk.Tag.attach(tagId, attachmentId[0], attachmentId[1]);
    

    Parameters

    • tagId: string
    • Rest ...attachmentIds: string[]

    Returns Promise<void>

    A promise that resolves when the Attachment is added to the Tag

close

  • close(id: string): Promise<void>
  • embed
    bundle

    Introduced 23.2.1

    Close a tag and its billboard or dock.

    const tagId: string; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    mpSdk.Tag.open(tagId);
    mpSdk.Tag.close(tagId);
    

    Parameters

    • id: string

    Returns Promise<void>

detach

  • detach(tagId: string, ...attachmentIds: string[]): Promise<void>
  • embed
    bundle

    Introduced 3.1.70.10-0-ge9cb83b28c

    Detach Attachment from a Tag.

    const tagId: string; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    const attachmentIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.registerAttachment` or through `mpSdk.Tag.attachments`
    
    mpSdk.Tag.detach(tagId, ...attachmentIds);
    // or
    mpSdk.Tag.detach(tagId, attachmentId[0], attachmentId[1]);
    

    Parameters

    • tagId: string
    • Rest ...attachmentIds: string[]

    Returns Promise<void>

dock

  • embed
    bundle

    Introduced 23.2.1

    Open a tag in the docked view.

    const tagId: string; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    mpSdk.Tag.dock(tagId);
    

    Parameters

    Returns Promise<void>

editBillboard

  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Edit the text content in a Tag's billboard.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    mpSdk.Tag.editBillboard(id, {
      label: 'This is a new title',
      description: 'This image was set dynamically by the Showcase sdk',
    });
    

    Parameters

    • id: string

      the id of the Tag to edit

    • properties: Partial<Tag.EditableProperties>

      A dictionary of properties to set

    Returns Promise<void>

editColor

  • editColor(id: string, color: Color): Promise<void>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Edit the color of a Tag's disc.

    const tagIds: string[]; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    
    // change the first Tag to yellow
    mpSdk.Tag.editColor(tagIds[0], {
      r: 0.9,
      g: 0,
      b: 0.9,
    });
    

    Parameters

    • id: string

      The id of the Tag to edit

    • color: Color

      The new color to be applied to the Tag disc

    Returns Promise<void>

editIcon

  • editIcon(tagId: string, iconId: string): Promise<void>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Change the icon of the Tag disc. Icons can be registered asset textures or font ids provided by the player. Supported font ids can be found at https://matterport.github.io/showcase-sdk/tags_icons_reference.html.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    // change the icon of the Tag using the id used in a previous `Asset.registerTexture` call
    mpSdk.Tag.editIcon(id, 'customIconId');
    
    // change the icon of the Tag to a font id.
    mpSdk.Tag.editIcon(id, 'public_buildings_apartment');
    

    Parameters

    • tagId: string

      The id of the Tag to edit

    • iconId: string

      The id of the icon to apply

    Returns Promise<void>

editOpacity

  • editOpacity(id: string, opacity: number): Promise<void>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Edit the opacity of a Tag.

    A completely transparent/invisible Tag is still interactable and will respond to mouse hovers and clicks.

    const tagIds: string[]; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    // make the first Tag invisible
    mpSdk.Tag.editOpacity(tagIds[0], 0);
    
    // make another Tag transparent
    mpSdk.Tag.editOpacity(tagIds[1], 0.5);
    
    // and another completely opaque
    mpSdk.Tag.editOpacity(tagIds[2], 1);
    

    Parameters

    • id: string

      The id of the Tag to edit

    • opacity: number

      The target opacity for the Tag in the range of [0, 1]

    Returns Promise<void>

editPosition

  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Move and reorient a Tag.

    See Pointer.intersection for a way to retrieve a new anchorPosition and stemVector.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    const tagId: string; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    
    mpSdk.Tag.editPosition(tagId, {
     anchorPosition: {
       x: 0,
       y: 0,
       z: 0,
     },
     stemVector: { // make the Tag stick straight up and make it 0.30 meters (~1 foot) tall
       x: 0,
       y: 0.30,
       z: 0,
     },
    });
    

    Parameters

    • id: string

      The id of the Tag to reposition

    • options: Partial<Tag.PositionOptions>

      The new anchorPosition, stemVector and/or roomId to associate the tag with.

    Returns Promise<void>

editStem

  • embed
    bundle

    Introduced 3.1.70.10-0-ge9cb83b28c

    Edit the stem of a Tag

    const tagId: string = tagData[0].id; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    
    // make the first Tag have an invsible stem
    mpSdk.Tag.editStem(tagId, {stemVisible: false});
    
    // make another Tag have a long stem
    mpSdk.Tag.editStem(tagId, {stemHeight: 1});
    

    Parameters

    Returns Promise<void>

open

  • embed
    bundle

    Introduced 23.2.1

    Open a tag and display its billboard. Opening a second tag will close the first.

    mpSdk.Tag.open(tagId);
    
    // if the tag has had its `dock` option removed through a call to `Tag.allowAction`, it can be `force`d open
    mpSdk.Tag.allowAction(tagId, {
      opening: false,
    });
    mpSdk.Tag.open(tagId,
      force: true,
    });
    

    Parameters

    Returns Promise<void>

registerAttachment

  • registerAttachment(...srcs: string[]): Promise<string[]>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Register a new Attachment that can later be attached as media to a Tag.

    Custom HTML can be added as an attachment through the use of registerSandbox instead.

    // register a couple of attachments to use later
    const [attachmentId1, attachmentId2] = mpSdk.Tag.registerAttachment(
      'https://[link.to/media]',
      'https://[link.to/other_media]',
    );
    

    Parameters

    • Rest ...srcs: string[]

      The src URLs of the media

    Returns Promise<string[]>

    A promise that resolves to an array of ids associated with the newly added Attachments

registerSandbox

  • embed
    bundle

    Introduced 3.1.70.10-0-ge9cb83b28c

    Register an HTML sandbox that diplays custom HTML and runs custom scripts as an attachment. Data can be sent and received from the sandbox by using the returned IMessenger.

    const htmlToInject = `
      <style>
        button {
          width: 100px;
          height: 50px;
        }
      </style>
      <button id='btn1'>CLICK ME</button>
      <script>
        var btn1 = document.getElementById('btn1');
        btn1.addEventListener('click', () => {
          // send data out of the sandbox
          window.send('buttonClick', 12345);
        });
        // receive data from outside of the sandbox
        window.on('updateButton', (newLabel, color) => {
          btn1.innerText = newLabel;
          btn1.style.backgroundColor = color;
        });
      </script>
    `;
    
    // create and register the sandbox
    const [sandboxId, messenger] = await mpSdk.Tag.registerSandbox(htmlToInject);
    // attach the sandbox to a tag
    mpSdk.Tag.attach(tagId, sandboxId);
    // receive data from the sandbox
    messenger.on('buttonClick', (buttonId) => {
      console.log('clicked button with id:', buttonId);
    });
    // send data to the sandbox
    messenger.send('I send messages', 'red');
    

    Parameters

    Returns Promise<[string, Tag.IMessenger]>

    An IMessenger that can be used to communicate with the sandbox by sending and receiving data

remove

  • remove(...ids: string[]): Promise<string[]>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Removes one or more Tags from Showcase.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    const tagIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    // remove one tag
    mpSdk.Tag.remove(tagIds[0]);
    
    // or remove multiple at the same time
    mpSdk.Tag.remove(...tagIds);
    

    Parameters

    • Rest ...ids: string[]

      The Tags' ids to be removed.

    Returns Promise<string[]>

    A promise with an array of Tag ids that were actually removed.

resetIcon

  • resetIcon(id: string): Promise<void>
  • embed
    bundle

    Introduced 3.1.68.12-7-g858688944a

    Resets the icon of the Tag disc back to its original icon.

    const tagIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
    
    // reset the icon of the first Tag to its original
    mpSdk.Tag.resetIcon(tagIds[0].id);
    

    Parameters

    • id: string

      The id of the Tag to reset

    Returns Promise<void>

toggleDocking

  • toggleDocking(enable?: undefined | false | true): Promise<void>
  • embed
    bundle

    Introduced 23.4.2

    Toggle the dock setting to hide dock buttons in all tags.

    Disabling the dock setting will remove the dock buttons from all tags. Enabling the dock setting does not automatically show the dock button in all tags. The dock button will only be displayed in a tag if both the dock setting is true and docking is allowed by the tag (see Tag.allowAction).

    // hide the dock buttons
    mpSdk.Tag.toggleDocking(false);
    
    // show the dock buttons
    mpSdk.Tag.toggleDocking(true);
    
    // toggle the current visibility of the dock buttons
    mpSdk.Tag.toggleDocking();
    

    Parameters

    • Optional enable: undefined | false | true

    Returns Promise<void>

toggleNavControls

  • toggleNavControls(enable?: undefined | false | true): Promise<void>
  • embed
    bundle

    Introduced 23.3.1

    Toggle the overhead navigation UI

    // hide the controls
    mpSdk.Tag.toggleNavControls(false);
    
    // show the controls
    mpSdk.Tag.toggleNavControls(true);
    
    // toggle the current visibility of the controls
    mpSdk.Tag.toggleNavControls();
    

    Parameters

    • Optional enable: undefined | false | true

    Returns Promise<void>

toggleSharing

  • toggleSharing(enable?: undefined | false | true): Promise<void>
  • embed
    bundle

    Introduced 23.4.2

    Toggle the share setting to hide share buttons in all tags.

    Disabling the share setting will remove the share buttons from all tags. Enabling the share setting does not automatically show the share button in all tags. The share button will only be displayed in a tag if both the share setting is true and sharing is allowed by the tag (see Tag.allowAction).

    // hide the share buttons
    mpSdk.Tag.toggleSharing(false);
    
    // show the share buttons
    mpSdk.Tag.toggleSharing(true);
    
    // toggle the current visibility of the share buttons
    mpSdk.Tag.toggleSharing();
    

    Parameters

    • Optional enable: undefined | false | true

    Returns Promise<void>