@3dsource/metabox-front-api

MetaBox Basic Configurators API

This package provides an API for interacting with the MetaBox Basic Configurator using plain JavaScript.

Installation (for using with frameworks like Angular, React, etc.) This is the recommended method

npm install @3dsource/metabox-front-api@^1.0.0 --save

then

import { FromMetaBoxApiAction, GetFastRender, GetPdf, integrateMetaBox, saveImage, SetEnvironment, SetMaterial, SetProduct, ShowEmbeddedMenu, ShowOverlayInterface, SetEnvironmentMaterial, Communicator, ConfiguratorEnvelope } from '@3dsource/metabox-front-api';

OR work with direct import from NPM using CDN network unpkg.com or jsdelivr.net (you can also download package and use it locally):

import { FromMetaBoxApiAction, GetFastRender, GetPdf, integrateMetaBox, saveImage, SetEnvironment, SetMaterial, SetProduct, ShowEmbeddedMenu, ShowOverlayInterface, SetEnvironmentMaterial, Communicator, ConfiguratorEnvelope } from 'https://cdn.jsdelivr.net/npm/@3dsource/metabox-front-api@1.0.0';

Usage

1. Create HTML Structure

Ensure your HTML page has the following structure, where the MetaBox Configurator will be integrated. You MUST control CSS style of embed3DSource element to make the configurator responsive and fit your needs on your own.

<div id="embed3DSource">
  <!-- Your Configurator iframe will be embedded here -->
</div>

2. Include Required Scripts

Below is an example demonstrating how to use the MetaBox API functions:

Insert this code into your HTML file just before the closing </body> tag:

EXAMPLE:

HTML:

<script type="module">
  import { integrateMetaBox, SetEnvironment, ShowOverlayInterface, SetEnvironmentMaterial, SetMaterial, SetProduct, ShowEmbeddedMenu, GetFastRender, GetPdf, saveImage, Communicator, FromMetaboxApiAction } from 'https://cdn.jsdelivr.net/npm/@3dsource/metabox-front-api@1.0.0';

  class JsIntegrator {
    constructor() {
      const url = 'https://metabox.3dsource.com/metabox-configurator/basic/your-configurator-id?sidebar=false';
      integrateMetaBox(url, 'embed3DSource', (api) => this.apiReady(api));
    }

    apiReady(api) {
      api.addEventListener('basicConfiguratorDataWithState', (data) => {
        this.updateConfiguratorData(data);
      });
      api.addEventListener('fastRender', (data) => {
        saveImage(data, 'Render.png');
      });
      this.setupInitialState(api);
    }

    updateConfiguratorData(data) {
      // Use data on your own
    }

    setupInitialState(api) {
      api.sendCommandToMetaBox(new SetProduct('productId'));
      api.sendCommandToMetaBox(new SetEnvironment('environmentId'));
      api.sendCommandToMetaBox(new SetMaterial('productId', 'slotId', 'materialId'));
      api.sendCommandToMetaBox(new SetEnvironmentMaterial('productId', 'slotId', 'materialId'));
      api.sendCommandToMetaBox(new ShowEmbeddedMenu(false));
      api.sendCommandToMetaBox(new ShowOverlayInterface(false));
      api.sendCommandToMetaBox(new GetPdf());
      api.sendCommandToMetaBox(new GetFastRender('image/png', { x: 1024, y: 1024 }));
    }
  }

  new JsIntegrator();
</script>

TypeScript:

import { ConfiguratorEnvelope, UniversalConfigurator, integrateMetaBox, SetEnvironment, ShowOverlayInterface, SetEnvironmentMaterial, SetMaterial, SetProduct, ShowEmbeddedMenu, GetFastRender, GetPdf, saveImage, Communicator, FromMetaboxApiAction } from '@3dsource/metabox-front-api';

class TsIntegrator {
  constructor() {
    const url = 'https://metabox.3dsource.com/metabox-configurator/basic/your-configurator-id?sidebar=false';
    integrateMetaBox(url, 'embed3DSource', (api) => this.apiReady(api));
  }

  apiReady(api: Communicator) {
    api.addEventListener('basicConfiguratorDataWithState', (data) => {
      this.updateConfiguratorData(data);
    });
    api.addEventListener('fastRender', (data) => {
      saveImage(data, 'Render.png');
    });
    this.setupInitialState(api);
  }

  updateConfiguratorData(data: ConfiguratorEnvelope) {
    // Use data on your own
  }

  setupInitialState(api: Communicator) {
    api.sendCommandToMetaBox(new SetProduct('productId'));
    api.sendCommandToMetaBox(new SetEnvironment('environmentId'));
    api.sendCommandToMetaBox(new SetMaterial('productId', 'slotId', 'materialId'));
    api.sendCommandToMetaBox(new SetEnvironmentMaterial('productId', 'slotId', 'materialId'));
    api.sendCommandToMetaBox(new ShowEmbeddedMenu(false));
    api.sendCommandToMetaBox(new ShowOverlayInterface(false));
    api.sendCommandToMetaBox(new GetPdf());
    api.sendCommandToMetaBox(new GetFastRender('image/png', { x: 1024, y: 1024 }));
  }
}

new TsIntegrator();

Documentation for current example

integrateMetaBox

• Description: Integrates the MetaBox configurator into the specified container.

• Usage:

  integrateMetaBox(configuratorUrl: string, containerId: string, apiReadyCallback: (api: Communicator) => void);

SetEnvironment

• Description: Sets the environment by ID.

• Usage:

  api.sendCommandToMetaBox(new SetEnvironment(environmentId: string));

SetMaterial

• Description: Sets the material for a given product slot.

• Usage:

  api.sendCommandToMetaBox(new SetMaterial(productId: string, slotId: string, materialId: string));

SetEnvironmentMaterial

• Description: Sets the material for a given environment slot.

• Usage:

  api.sendCommandToMetaBox(new SetEnvironmentMaterial(productId: string, slotId: string, materialId: string));

SetProduct

• Description: Sets the product by ID.

• Usage:

  api.sendCommandToMetaBox(new SetProduct(productId: string));

ShowEmbeddedMenu

• Description: Toggles the embedded menu in the MetaBox configurator.

• Usage:

  api.sendCommandToMetaBox(new ShowEmbeddedMenu(visible: boolean));

ShowOverlayInterface

• Description: Toggles the overlay interface over Unreal viewport.

• Usage:

  api.sendCommandToMetaBox(new ShowOverlayInterface(visible: boolean));

GetFastRender

• Description: Retrieves a fast render of the current view.

• Usage:

  api.sendCommandToMetaBox(new GetFastRender(mimeType: string, size?: { x: number, y: number }));

GetPdf

• Description: Generates a PDF of the current view.

• Usage:

  api.sendCommandToMetaBox(new GetPdf());

saveImage

• Description: Saves the arrived rendered image to a file using utility function.

• Usage:

  saveImage(renderData: string, fileName: string): void;