`,
styles: [
`
.app-container {
max-width: 1200px;
margin: 0 auto;
padding: 20px;
}
`,
],
})
export class AppComponent {
configuratorId = 'configurator-id';
onConfiguratorStateChange(data: ConfiguratorEnvelope): void {
console.log('Configurator state changed:', data);
// Update your application state based on configurator changes
}
onConfiguratorError(error: string): void {
console.error('Configurator error:', error);
// Handle errors (show notifications, log to analytics, etc.)
}
}
```
**To Use This Component:**
1. Install the package: `npm install @3dsource/metabox-front-api@latest`
2. Import the component in your Angular module
3. Replace `'configurator-id'` with your actual configurator ID
4. Replace placeholder IDs with your real product, material, and slot IDs
5. Customize the styling by modifying the component styles
## Troubleshooting
### Common Issues
#### 1. Configurator Not Loading
**Symptoms:** Blank screen, iframe not appearing, loading indefinitely
**Root Causes & Solutions:**
| Issue | Diagnostic | Solution |
| --------------------------- | ------------------------------------ | --------------------------------------------------------- |
| Invalid configurator ID | Browser console shows 404 errors | Verify configurator ID in Metabox admin |
| Container not found | `Error: Container element not found` | Ensure element exists before calling `integrateMetabox()` |
| HTTP instead of HTTPS | Mixed content warnings | Use HTTPS or test on localhost |
| Container has no dimensions | Invisible iframe (0x0) | Set explicit width/height on container element |
| CORS/iframe blocking | X-Frame-Options errors | Check domain allowlist in Metabox settings |
**Diagnostic Code:**
```typescript
const containerId = 'embed3DSource';
const container = document.getElementById(containerId);
if (!container) {
throw new Error(`Container #${containerId} not found`);
}
// Verify container has dimensions
const rect = container.getBoundingClientRect();
if (rect.width === 0 || rect.height === 0) {
console.warn('⚠️ Container has no dimensions');
}
if (location.protocol !== 'https:' && location.hostname !== 'localhost') {
console.warn('⚠️ HTTPS required for Unreal Engine streaming');
}
integrateMetabox('configurator-id', containerId, (api) => {
console.log('✅ Configurator loaded');
});
```
#### 2. Commands Not Working
**Symptoms:** Commands sent but no visual changes in configurator
**Common Mistakes:**
| Mistake | Problem | Solution |
| -------------------------- | ----------------- | ----------------------------------------------- |
| Sending before API ready | Commands ignored | Only send in `apiReadyCallback` |
| Wrong product/material IDs | Entity not found | Verify IDs from `configuratorDataUpdated` event |
| Wrong slot ID | Material rejected | Verify slot IDs from configurator data |
**Correct Pattern:**
```typescript
integrateMetabox('configurator-id', 'container', (api) => {
// ✅ Correct: Commands sent after API ready
api.sendCommandToMetabox(new SetProduct('product-id'));
api.sendCommandToMetabox(new SetProductMaterial('slot-id', 'material-id'));
});
// ❌ Wrong: Command sent too early
// api.sendCommandToMetabox(new SetProduct('product-id'));
```
### Getting Help
If you're still experiencing issues:
1. Check the browser console for error messages
2. Verify your configurator ID in a separate browser tab
3. Test with a minimal example to isolate the issue
4. Contact support with: browser version, configurator URL, console errors, and steps to reproduce
## Tips & Tricks
- **Debounce rapid commands.** Avoid sending too many commands in quick succession — debounce material or product changes (e.g., 300 ms).
- **Responsive container.** Set the configurator container to responsive dimensions (`width: 100%; height: 100%;`) and adjust with media queries for mobile.
- **Events work in all modes.** `configuratorDataUpdated`, `screenshotReady`, and other events fire in both default and standalone mode — use them to keep your UI synchronized.
- **Wait for API ready.** Only send commands inside the `apiReadyCallback`. Commands sent before initialization are silently ignored.
- **Validate IDs from events.** Use the `configuratorDataUpdated` event payload to discover valid product, material, and slot IDs rather than hardcoding them.
- **HTTPS is required.** The iframe URL enforces HTTPS. HTTP URLs will be rejected. Use `localhost` for local development.
- **Pin CDN versions in production.** Replace `@latest` with a specific version to avoid unexpected breaking changes.
---
For more examples and advanced usage, visit
our [documentation site](https://preview.3dsource.com/front-libraries/master/basic-configurator-api-doc/).