1. Zakeke
  2. How To's
  3. 3D Digital Asset Manager & AR Viewer

Integrating Zakeke 3D DAM via Frontend Kit

Help 3D DAM & AR Viewer
Updated

Integrating Zakeke 3D DAM via Frontend Kit

What is it?

The Zakeke Frontend Integration Kit is a simple solution to enable quick integrations with third-party systems (for example PIMs or similar) with minimal effort.

By including our JS script in your document, we will register a Web Component that you can use throughout your application. Since we are using browser standards, our solution is completely framework agnostic and can be used with ease in every modern (and classic, or monolithic) web application.

The web component completely manages authentication, asset management and more, the only additional thing that needs to be done is to listen to the events emitted by the component and react to them (usually by saving the provided values and updating some state on the page)

 

How to use it?

Please include the following script in the header of your index.html:

src="https://relay.dam.zakeke.com/kit/zakeke-integration-kit.js"></script>

Now you can use the component directly:

<zakeke-dam iconSize="24" label="Connect to Zakeke" asset=""></zakeke-dam>

Please note that for web components the closing tag is mandatory. The attributes of the component are as follows:

  • iconSize: string, size in pixels for the Zakeke icon in the button
  • label: string, the button label
  • asset: string, a JSON stringifyied object representing the asset to be uploaded. Only the code field is mandatory. The asset object can have the following attributes.
    • code: mandatory, string, this is the main identifier for the asset, we use this value to check if an asset was already uploaded. This value cannot be changed by the user (this usually is an SKU or a system definite unique value, for example a UUID).
    • name: optional, string, the name of the asset. Can be changed by the user, if not provided the user will be prompted to insert it during the asset creation process.
    • images: optional, array of strings, a list of URLs to images to use in case of the creation of a request for services (usually product images are provided here).
    • modelUrl: optional, string, URL to a GLB file. If set during the upload process the default value for the file field will be this file.

Example usage (in a react environment):

<zakeke-dam
              ref={buttonRef}
              iconSize="24"
              label="Connect to Zakeke"
                asset={JSON.stringify({
                code: product.identifier,
                name: product.name,
                modelUrl: "url/to/asset.glb",
                images: ["url/to/image_1.jpg", "url/to/image_2.jpg"],
              })}
></zakeke-dam>

If you’re using Typescript and React you can type the component on JSX using the following type declaration:

declare module "react/jsx-runtime" {
  namespace JSX {
    interface IntrinsicElements {
      "zakeke-dam": {
        iconSize: string;
        label: string;
        asset: string;
        className?: string;
        ref?: RefObject;
      };
    }
  }
}

 

Events

The web component emits a set of different events that can be used to perform different actions, for example saving asset data in a local database.

Event listeners can be registered on the component in the same way you would register an event listener on every other HTML tag. Assuming the following implementation:

<zakeke-dam iconSize="32" label="Zakeke" id="zakeke-button" asset='{"code": 
"invio-request2pc+7231", "name": "Testing from webcomponent 1"}'></zakeke-dam>

You can register events in the following way:

document.querySelector('#zakeke-button')?.addEventListener('zakeke:dam:sync', (ev) => {
    console.debug('the zakeke dam sync event was emitted', ev)
  })

In a React environment, you can leverage the use of ref objects and register event listeners in the useEffect hook. Assuming the following implementation:

<zakeke-dam
          ref={buttonRef}
          iconSize="24"
          label="Connect to Zakeke"
          asset={JSON.stringify({
            code: product.identifier,
            name: product.name,
            modelUrl: "url/to/asset.glb",
            images: ["url/to/image_1.jpg", "url/to/image_2.jpg"],
          })}
></zakeke-dam>

You can use the hook to register event listeners:

const buttonRef = useRef(null);

useEffect(() = {
    buttonRef.current?.addEventListener("zakeke:dam:sync", eventSyncHandler);
    buttonRef.current?.addEventListener("zakeke:dam:estimate", eventEstimateHandler);

    return () = {
      buttonRef.current?.removeEventListener("zakeke:dam:sync",eventSyncHandler);
      buttonRef.current?.removeEventListener("zakeke:dam:estimate",eventSyncHandler);
    };
  }, []);

We highly recommend using a cleanup function to clean up registered event listeners.

The events emitted by the web component are the following:

  • zakeke:dam:sync - is the event emitted when the “Sync asset” button is clicked or when the Asset has finished creating (this event is not fired directly after asset upload because an async step has to be completed before).
  • zakeke:dam:estimate - is emitted when the “Sync service” button is clicked or when the Request for service was correctly created. In this case, the event is immediately fired.

Both these events are standard javascript CustomEvents and data is kept in the relative detail object.

For zakeke:dam:sync the contents of the detail are as follows:

type SyncEvent = CustomEvent<{ project:="project:" project;="Project;" asset:="asset:" asset="Asset" }="}">;

export type Project = {
  id: string;
  productId: string;
  productName: string;
  customCode: string;
  gifCustomCode: string;
  videoCustomCode: string;
  width?: number;
  height?: number;
  length?: number;
  description?: string;
  dimension?: string;
  startDate?: string;
  deadline?: string;
  endDate?: string;
  imageUrl?: string;
  attachmentUrl?: string;
};

export type Asset = {
  id: string;
  file3dName: string;
  type: "MESH" | "MESH_OPTIMIZED";
  description?: string;
  file3dUrl?: string;
  file3dSize?: number;
  file3dUploadDate?: string;
  hasFile3d: boolean;
  filePreviewUrl?: string;
  filePreviewSize?: number;
  fileEnvironmentUrl?: string;
  fileEnvironmentSize?: number;
  fileEnvironmentName?: string;
  hasFilePreview: boolean;
  hasFileEnvironment: boolean;
  viewerUrl?: string;
};

For zakeke:dam:estimate the contents of detail are as follows:

type EstimateEvent = CustomEvent<{ estimate:="estimate:" estimate="Estimate" }="}">;

type Estimate = {
  id: number;
  shortDescription?: string | null;
  deadline?: string | null;
  alternativeEmail?: string | null;
  description?: string | null;
  status: string;
  document?: string | null;
  acceptedAt?: string | null;
  rejectedAt?: string | null;
  remindedAt?: string | null;
  createdAt: string;
  updatedAt: string;
  item: {
    id: number;
    name: string;
    code: string;
    dimension?: string;
    description?: string;
  };
};

Information on the specific asset is contained in the item object (Estimate being the entire Request for Services).

 

Customization

The web component is structured as a simple button, so applying styles to it is straightforward:

<zakeke-dam iconSize="32" label="Zakeke" id="zakeke-button" asset='{"code": "invio-request2pc+7231", "name": "Testing from webcomponent 1"}'></zakeke-dam>

Assuming the same structure as before we can leverage the id on the button (or a class if you prefer) and apply classic CSS styles. The only detail to keep in mind is that html structure of the button content is composed of an img and span. The host of the button has therefore a display: flex assigned.

#zakeke-button {
  flex-direction: row;
  align-items: center;
  border: 1px solid #455b67;
  border-radius: 50px;
  padding: .25rem;
  margin-top: .5rem;
}

If you're using React and Styled Components you can also style it using styled components

const StyleZakekeButton = styled("zakeke-dam")`
  flex-direction: row;
  align-items: center;
  border: 1px solid #455b67;
  border-radius: 50px;
  padding: 0.25rem;
  margin-top: 0.5rem;
  margin-bottom: 1rem;
`;

And use it as any other component.

<StyleZakekeButton
              ref={buttonRef}
              iconSize="24"
              label="Connect to Zakeke"
              asset={JSON.stringify({
                code: product.identifier,
                name: product.name,
                modelUrl: "url/to/asset.glb",
                images: ["url/to/image_1.jpg", "url/to/image_2.jpg"],
              })}
></StyleZakekeButton>

You can also customize the contents of the welcome card of the sidebar by passing simple html content as a slot to the web component:

<zakeke-dam iconSize="32" label="Zakeke" id="zakeke-button" asset='{"code": "invio-request2pc+7231", "name": "Testing from webcomponent 1"}'>
<h4 class="twz-font-bold twz-mb-5">3D Dam & Ar Viewer><h4>
            <ul
              class="twz-list-disc twz-list-outside twz-ml-4 twz-space-y-4 twz-text-text-tertiary twz-text-sm"
            >
              <li>
                Store, organize and share your 3D models. Get custom quotes and
                monitor status>
              </li>
              <li>
                Embed the 3D/AR Viewer into your online store, PIM, B2B platform
                in minutes>
              </li>
              <li>
                Generate 360° GIFs and videos of your products automatically>
              </li>
            </ul>
</zakeke-dam>

Please keep in mind that, as per the rules of web components, the contents of a slot are styled following the page's styles and not the styles of the web component. Therefore you need to style the contents of the slot according to your desire.

Was this article helpful?
0 out of 0 found this helpful

Articles in this section

See more