Assets Storage

Asset Uploads

Overview

The Asset Upload API allows you to upload user assets (3D models, images, videos, and audio) to the ReactVision platform. Once uploaded, assets receive a unique URL and asset ID that can be linked to geospatial anchors or cloud anchors, enabling persistent AR experiences where content automatically loads when an anchor is resolved.

Requires the ReactVision provider. Asset uploads are only available when using the ReactVision provider (the default in v2.53.0). You must have configured your rvApiKey and rvProjectId — see ReactVision Studio Setup for details.

---

Setup

Asset uploads require the ReactVision provider to be configured. See the Provider Setup guide for full instructions on configuring your rvApiKey and rvProjectId.

---

API Reference

rvUploadAsset(assetType, filename, data, appUserId)

Uploads a file to ReactVision storage and returns a URL and asset ID.

Parameters

Parameter	Type	Description
assetType	string	The type of asset being uploaded. See Supported Asset Types below.
filename	string	The name of the file including extension (e.g. "statue.glb", "photo.jpg").
data	any	The file data to upload (e.g. a base64-encoded string or file buffer).
appUserId	string	Your application's user identifier. Used to associate the upload with a specific user in your app.

Returns

Promise<ViroUploadAssetResult>

TypeScript

{
  success: boolean;
  url?: string;       // The public URL where the asset is hosted
  assetId?: string;   // A unique identifier for the uploaded asset
  error?: string;
}

Supported Asset Types

assetType	Description	Common Formats
"3d-model"	3D model files for rendering in AR scenes	.glb, .gltf, .vrx
"image"	Image files for textures, markers, or UI overlays	.jpg, .png, .webp
"video"	Video files for playback in AR scenes	.mp4, .mov
"audio"	Audio files for spatial audio or ambient sound	.mp3, .wav, .aac

---

Usage

Uploading an Asset

tsx

const uploadModel = async () => {
  const result = await arSceneNavigator.rvUploadAsset(
    "3d-model",
    "statue.glb",
    fileData,        // your file data
    "user-12345"     // your app's user ID
  );

  if (result.success) {
    console.log("Asset URL:", result.url);
    console.log("Asset ID:", result.assetId);
  } else {
    console.error("Upload failed:", result.error);
  }
};

Linking an Asset to a Geospatial Anchor

After uploading, use the returned asset ID to associate the asset with a geospatial anchor via rvUpdateGeospatialAnchor:

tsx

// 1. Upload the asset
const uploadResult = await arSceneNavigator.rvUploadAsset(
  "3d-model",
  "statue.glb",
  fileData,
  "user-12345"
);

// 2. Create a geospatial anchor
const anchorResult = await arSceneNavigator.createGeospatialAnchor(
  37.7749,
  -122.4194,
  10.0,
  [0, 0, 0, 1]
);

// 3. Link the asset to the anchor
if (uploadResult.success && anchorResult.success) {
  await arSceneNavigator.rvUpdateGeospatialAnchor(
    anchorResult.anchor.anchorId,
    uploadResult.assetId,  // sceneAssetId
    null,                  // sceneId (optional)
    "My AR Statue"         // name (optional)
  );
}

Linking an Asset to a Cloud Anchor

You can also attach an uploaded asset to a cloud anchor via rvAttachAssetToCloudAnchor:

tsx

// 1. Upload the asset
const uploadResult = await arSceneNavigator.rvUploadAsset(
  "3d-model",
  "decoration.glb",
  fileData,
  "user-12345"
);

// 2. Host a cloud anchor
const cloudResult = await arSceneNavigator.hostCloudAnchor(localAnchorId, 30);

// 3. Attach the asset to the cloud anchor
if (uploadResult.success && cloudResult.success) {
  await arSceneNavigator.rvAttachAssetToCloudAnchor(
    cloudResult.cloudAnchorId,
    uploadResult.url,        // asset URL from upload
    fileData.length,         // file size in bytes
    "decoration.glb",       // display name
    "3d-model",             // asset type
    "user-12345"            // app user ID
  );
}

When another user resolves the cloud anchor, the linked asset will automatically load at the anchor's position.

---

Best Practices

1. Validate File Size Before Uploading

Large assets can cause slow uploads and high memory usage on mobile devices. Compress 3D models and images where possible.

2. Use Meaningful Filenames

Filenames are stored alongside the asset metadata. Using descriptive names makes it easier to manage assets in ReactVision Studio.

3. Associate Assets with Users

Always pass a consistent appUserId so that you can query and manage a user's uploaded assets through the ReactVision Studio dashboard.

4. Handle Upload Errors

Network conditions on mobile devices can be unreliable. Always check the success field and provide retry logic or user feedback on failure.

tsx

const uploadWithRetry = async (assetType, filename, data, userId, retries = 3) => {
  for (let i = 0; i < retries; i++) {
    const result = await arSceneNavigator.rvUploadAsset(assetType, filename, data, userId);
    if (result.success) return result;
    console.warn(`Upload attempt ${i + 1} failed, retrying...`);
  }
  throw new Error("Upload failed after multiple attempts");
};

---

Troubleshooting

"Upload failed" or network errors

• Verify your rvApiKey and rvProjectId are correctly configured
• Check that the device has an active internet connection
• Ensure the file data is valid and not empty

"Invalid asset type"

• Confirm you are using one of the supported assetType values: "3d-model", "image", "video", "audio"

"Not authorized"

• Your ReactVision API key may be invalid or expired
• Visit ReactVision Studio to verify your credentials

Asset not appearing at anchor

• Ensure the asset was successfully linked via rvUpdateGeospatialAnchor or rvAttachAssetToCloudAnchor
• Check that the anchor itself has been successfully created or hosted
• Verify the asset URL is accessible