Asset-Upload SDK

The @sdk/asset-upload package is a composition of the existing @sdk/upload and @sdk/upload-bridge packages to simplify the process of syncing an asset to the HxDR platform. It provides a simple API to upload assets.

Installation

To install this package, you need to have access to the private @sdk npm scope.

Begin by installing the @sdk/asset-upload package using your preferred package manager:

npm install @sdk/asset-upload

Asset Upload Lifecycle

An asset can consist of multiple files, such as a 3D model with textures. The asset upload lifecycle consists of the following steps that have to be executed against the HxDR Platform API:

Create Asset: Create a new asset on the HxDR Platform.
For each file of an asset do:
- Create File: Attach a file to the asset. This can be done multiple times for each file that should be part of the asset.
- Upload File: Upload the file(s) to the HxDR Platform.
- Finalize File: Finalize the file(s), marking them as fully uploaded.
Finalize Asset: Finalize the asset after all files have been uploaded.

Usage

The @sdk/asset-upload package provides the asset upload service and therefore a simple API to follow the upload lifecycle.

import { AssetUploadService, UploadDestinationMapper } from '@sdk/asset-upload';
import { Result } from '@sdk/core';
import myAssetMapper from './my-asset-mapper'; // Provided by `@sdk/asset-core`
import myConnectClient from './my-connect-client'; // Provided by `@sdk/connect`
 
const assetUploadService = new AssetUploadService(myConnectClient, myAssetMapper, new UploadDestinationMapper());
 
function createAssetFromFiles(files: File[], name: string): Promise<void> {
  const createAssetResult = await assetUploadService.createAsset({
    name,
  });
 
  if (Result.isOk(createAssetResult)) {
     await Promise.all(files.map(async (file) => {
       const createFileResult = await assetUploadService.createAssetFile({
           fileName: file.name,
           fileSize: file.size,
           assetId: createAssetResult.value.id
       });
 
       if (Result.isOk(createFileResult)) {
         // Use `@sdk/upload` to upload the file here
         await assetUploadService.finalizeFile(uploadFileResult.value);
       }
     });
    await assetUploadService.finalizeAsset(createAssetResult.value.id);
  }
}

In this example, the createAssetFromFiles function creates a new asset on the HxDR Platform and uploads the provided files to it, following the lifecycle outlined above.

React Integration

This package privides a set of React tool that abstract the process of uploading an asset even further.

npm install @sdk/asset-upload-react

To enable the asset upload service within a React application, wrap your app with the AssetUploadProvider and utilize the useAssetUpload hook for easy access:

💡

The AssetUploadProvider has a few dependencies on other providers, so make sure to keep it itself wrapped in these. ConnectProvider from @sdk/connect-react, NotificationProvider from @sdk/notification and AssetProvider from @sdk/asset-core

import { AssetUploadProvider } from '@sdk/asset-upload-react';
 
function Root() {
  return (
    <AssetUploadProvider onStorageLimitReached={() => throw Error('Storage Limit Reached')}>
      <App />
    </AssetUploadProvider>
  );
}

After wrapping your app with the AssetUploadProvider, you can use a set of hooks to interact with the asset upload service:

useAssetUploadDestinations: To get the destination (project and folders) of currently uploading assets.
useAssetUploadState: To get the current state of the asset upload service, like upload percentage and speed.
useAssetUploadStateListener: To get realtime upload state updates for a specific asset.
useAssetUploadOperations: To interact with the asset upload service, like starting, pausing, or canceling an upload.

Asset Renderer Router