Documentation

Everything you need to integrate XRNet into your projects

Select Your Platform

Choose a platform to see tailored SDK documentation.

Introduction

The XRNet SDK is a React-based library that enables you to integrate 3D model viewing and customization capabilities into your applications. Built on top of Three.js and React Three Fiber, it provides a powerful and flexible way to display interactive 3D content.

Key Features:

Interactive 3D model viewer with AR support
Customizable model editor
Model recommendation service integration
TypeScript support with full type definitions
Material-UI integration

Installation

Install the XRNet SDK via npm or yarn:

bash

npm install @xrnet/sdk

# or with yarn
yarn add @xrnet/sdk

# or with pnpm
pnpm add @xrnet/sdk

Peer Dependencies

Make sure you have the following peer dependencies installed:

bash

npm install react@^18.3.1 react-dom@^18.3.1 \
  @mui/material@^5.x @mui/icons-material@^5.x \
  @emotion/react@^11.x @emotion/styled@^11.x \
  react-query@^3.x

Quick Start

Get started with a basic 3D model viewer in just a few lines of code:

tsx

import React from 'react';
import { XRNetViewer, XRNetEnvironment } from '@xrnet/sdk';

const App: React.FC = () => {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <XRNetViewer 
        id="your-model-property-id" 
        apiKey={{ publicKey: "your-api-key" }}
      />
    </div>
  );
};

export default App;

XRNetViewer Component

The XRNetViewer component displays 3D models with interactive controls and AR support.

Props

Prop	Type	Required	Description
id	string	No	The 3D model property ID to fetch and display
properties	XRNetProperties	No	Directly pass properties bypass fetching
apiKey	XRNetAPIKey	No	Your XRNet API credentials
environment	XRNetEnvironment	No	API environment (Defaults to PROD)

Example

tsx

import React, { useState } from 'react';
import { XRNetViewer, XRNetEnvironment } from '@xrnet/sdk';

const MyComponent: React.FC = () => {
  const [isOpen, setIsOpen] = useState<boolean>(false);

  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>
        Toggle 3D Model
      </button>
      
      {isOpen && (
        <div style={{ height: '500px', width: '100%', border: '1px solid #ccc' }}>
          <XRNetViewer 
            id="your-model-property-id"
            apiKey={{ publicKey: "your-public-key" }}
          />
        </div>
      )}
    </div>
  );
};

export default MyComponent;

XRNetEditor Component

The XRNetEditor component provides an interactive editor for customizing 3D models with real-time preview.

Props

Prop	Type	Required	Description
apiKey	XRNetAPIKey	Yes	Your XRNet API credentials
search	string	No	Search query for models
environment	XRNetEnvironment	No	API environment (Defaults to PROD)
productName	string	No	Name of the product
existingImages	File[]	No	Images of existing model
theme	'light' \| 'dark'	No	Editor color theme
onModelSelect	(id: string) => void	No	Callback when model selected
onPreview	(url: string) => void	No	Callback when preview updates

Example

tsx

import React from 'react';
import { XRNetEditor, XRNetEnvironment } from '@xrnet/sdk';

const ModelEditor: React.FC = () => {
  return (
    <div>
      <XRNetEditor
        search="Gaming Chair"
        apiKey={{ publicKey: "your-public-key" }}
        productName="Gaming Chair"
        onModelSelect={(id) => {
          console.log('Selected model:', id);
        }}
        onPreview={(url) => {
          console.log('Preview URL:', url);
        }}
      />
    </div>
  );
};

export default ModelEditor;

React Hooks

useXrModelRecommendationService

A React Query hook for fetching recommended 3D models from the XRNet API.

tsx

import React from 'react';
import { useXrModelRecommendationService } from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const ModelGallery: React.FC = () => {
  const { data, isLoading, error } = useXrModelRecommendationService({
    start: 0,
    length: 10,
    search: "chair",
    order: "DESC"
  });

  if (isLoading) {
    return <div>Loading models...</div>;
  }

  if (error) {
    return <div>Error loading models</div>;
  }

  return (
    <div>
      <h2>Recommended Models ({data?.totalCount ?? 0})</h2>
      <div className="grid grid-cols-3 gap-4">
        {data?.data.map((model: XRModel) => (
          <div key={model.id}>
            <h3>{model.name}</h3>
            <p>{model.description}</p>
          </div>
        ))}
      </div>
    </div>
  );
};

export default ModelGallery;

Parameters

Parameter	Type	Description
start	number	Starting index for pagination
length	number	Number of items per page
search	string	Search query
order	"ASC" \| "DESC"	Sort order

TypeScript Types

The SDK includes comprehensive TypeScript definitions for type safety.

typescript

import type { 
  XRModel, 
  XRNetProperties, 
  ModelViewerProps,
  XRNetAPIKey,
  XRNetEnvironment 
} from '@xrnet/sdk';

// XRModel interface
interface XRModel {
  id: string;
  name: string;
  model_urls: {
    glb: string;
    obj: string;
    usdz: string;
    fbx: string;
    gltf: string;
    stl: string;
    dae: string;
    [key: string]: string;
  };
  properties?: XRNetProperties[];
  description: string;
  tags: string[] | null;
  createdAt: string;
  updatedAt: string;
  sub_categories?: SubCategory[];
}

// XRNetProperties interface
interface XRNetProperties {
  id: string;
  props: {
    cameraState?: {
      position: [number, number, number];
      target: [number, number, number];
      zoom: number;
      rotation: [number, number, number];
    };
    sections: { [key: string]: string };
    [key: string]: unknown;
  };
  thumbnail: string | null;
  description: string | null;
  createdAt: string;
  updatedAt: string;
}

// Environment enum
enum XRNetEnvironment {
  DEV = 'dev',
  PROD = 'prod'
}

Advanced Usage

Complete Integration Example

Here's a complete example showing how to integrate the SDK with model recommendations and viewer:

tsx

import React, { useState, useCallback } from 'react';
import { 
  XRNetViewer, 
  useXrModelRecommendationService 
} from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const ProductShowcase: React.FC = () => {
  const [selectedModel, setSelectedModel] = useState<XRModel | null>(null);
  const [viewerOpen, setViewerOpen] = useState<boolean>(false);

  // Fetch recommended models
  const { data, isLoading, error } = useXrModelRecommendationService({
    start: 0,
    length: 20,
    search: "furniture",
    order: "DESC"
  });

  const handleViewModel = useCallback((model: XRModel) => {
    setSelectedModel(model);
    setViewerOpen(true);
  }, []);

  const handleCloseViewer = useCallback(() => {
    setViewerOpen(false);
  }, []);

  if (isLoading) {
    return <div>Loading 3D models...</div>;
  }

  if (error) {
    return <div>Error loading models. Please try again.</div>;
  }

  return (
    <div>
      <h1>3D Product Gallery</h1>
      
      {/* Model Grid */}
      <div className="grid grid-cols-4 gap-6">
        {data?.data.map((model: XRModel) => (
          <div key={model.id} className="model-card">
            <img 
              src={model.properties?.[0]?.thumbnail ?? '/placeholder.jpg'} 
              alt={model.name}
            />
            <h3>{model.name}</h3>
            <p>{model.description}</p>
            <button 
              onClick={() => handleViewModel(model)}
              type="button"
            >
              View in 3D
            </button>
          </div>
        ))}
      </div>

      {/* 3D Viewer */}
      <div style={{ position: 'relative', height: '500px' }}>
        {viewerOpen && (
          <button onClick={handleCloseViewer} style={{ position: 'absolute', zIndex: 10 }}>Close Viewer</button>
        )}
        {selectedModel && selectedModel.properties?.[0] && viewerOpen && (
          <XRNetViewer 
            id={selectedModel.properties[0].id} 
              // apiKey={{ publicKey: 'apikey' }} // pass key if needed 
          />
        )}
      </div>
    </div>
  );
};

export default ProductShowcase;

Configuration

Configure the SDK with your API credentials and environment settings.

typescript

import { XRNetEnvironment } from '@xrnet/sdk';
import type { XRNetAPIKey } from '@xrnet/sdk';

// Set environment (default is PROD)
const environment: XRNetEnvironment = XRNetEnvironment.PROD;

// Configure API credentials
const apiKey: XRNetAPIKey = {
  publicKey: process.env.XRNET_PUBLIC_KEY || 'your-public-key',
  privateKey: process.env.XRNET_PRIVATE_KEY // optional
};

// Example configuration object
interface XRNetConfig {
  apiKey: XRNetAPIKey;
  environment: XRNetEnvironment;
  baseURL?: string;
}

const config: XRNetConfig = {
  apiKey,
  environment,
  baseURL: 'https://api.xrnet.tech/v1'
};

Support & Resources

Need Help?

If you have questions or need assistance, reach out to us:

Email: support@xrnet.tech
GitHub: github.com/xrnet
NPM Package: @xrnet/sdk