# Best practices

This section describes recommended practices for using the VirtualCar360 documentation and platform. It covers Player, Player 360, configuration, video, certificates and API integration.

## Choose the right integration method

| Scenario | Recommended solution |
|  --- | --- |
| Embed a ready-made vehicle presentation | Player |
| Show smooth 360° rotation | Player 360 |
| Configure embedded behavior | Customization |
| Display generated vehicle videos | Video |
| Display vehicle certificates | Certificate |
| Build a custom gallery or import data | API |


Tip
If you do not need to build a custom gallery, start with the Player. It is the fastest and simplest integration method.

## Recommended implementation process

1. Choose Player, Player 360 or API.
2. Obtain an API key or group key.
3. Prepare a test environment.
4. Test the integration on selected vehicles.
5. Check edge cases such as missing gallery, missing video, missing hotspots and multiple galleries.
6. Configure the Player appearance.
7. Verify desktop, tablet and mobile views.
8. Check performance on offer listings.
9. Deploy to production.
10. Monitor issues and report unusual cases to support.


## Player and Player 360

- Embed using `iframe`.
- Use responsive containers.
- Use `loading="lazy"` on listings.
- Avoid loading too many Players at once.
- Use Player 360 primarily on vehicle detail pages.
- Remember that AI-generated Player 360 frames do not contain hotspots.


## API

- Use backend proxy for API calls.
- Store API keys in environment variables or secret storage.
- Do not log full URLs containing `key`.
- Use cache for frequently requested data.
- Use pagination for list endpoints.
- Handle `400`, `404` and `500` responses.
- Do not assume every vehicle has a gallery, video, hotspot or certificate.


## Video

- Contact support to enable video generation.
- Confirm whether videos should be generated automatically.
- Configure YouTube before production deployment if required.
- Handle `video = null`.
- Do not assume every gallery has a YouTube link.


## Certificate

- Retrieve certificates through backend when using the Certificate API.
- Use `widget` for embedded website views.
- Use `onepage` for a standalone certificate page.
- Use `pdf` for downloadable documents.
- Handle multiple languages.
- Do not treat temporary PDF URLs as permanent links.


## Documentation consistency

- Use the same section names in Markdown pages and API Reference.
- Avoid internal controller names in public documentation.
- Group endpoints by business function.
- Include request examples and response examples.
- Use consistent placeholders such as `YOUR_API_KEY`.
- Keep OpenAPI as the source for API Reference and Markdown pages as integration guidance.


## Testing checklist

Test:

- a vehicle with one gallery,
- a vehicle with multiple galleries,
- a vehicle with video,
- a vehicle without video,
- a vehicle with hotspots,
- a vehicle without hotspots,
- a vehicle with certificate,
- invalid VIN,
- invalid registration number,
- missing access to a location,
- desktop and mobile layouts,
- slower network connections.