> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trackplay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain Whitelist

> Control which domains can embed and stream your TrackPlay videos

TrackPlay's domain whitelist feature allows you to control which websites can embed and stream your videos. This provides security and prevents unauthorized use of your content on unwanted domains.

<Note>
  Domain whitelisting is available for workspace owners and admins. When no domains are configured, videos can be embedded anywhere.
</Note>

## How It Works

### Default Behavior

* **No domains configured**: Videos can be embedded on any website
* **Domains configured**: Only whitelisted domains can stream videos
* **Blocked domains**: Show a user-friendly "Video Unavailable" message

### Validation Process

1. Video starts playing immediately for the best user experience
2. Domain validation runs asynchronously in the background
3. The validation request is sent to `https://e.trackplay.io/check`
4. If the domain is not whitelisted, video playback is stopped and blocked
5. If validation fails (network issues), videos continue playing as fallback

## Managing Your Whitelist

### Accessing Domain Settings

1. Navigate to your workspace settings
2. Click the **"Domain Whitelist"** tab
3. Add, edit, or remove domains as needed

### Adding Domains

<Steps>
  <Step title="Click Add Domain">
    Click the **"+ Add domain to whitelist"** button
  </Step>

  <Step title="Enter Domain">
    Enter the exact domain name (e.g., `example.com`)

    * Do not include `http://` or `https://`
    * Subdomains must be added separately
  </Step>

  <Step title="Add Description">
    Optionally add a description to help identify the domain
  </Step>

  <Step title="Save">
    Click **"Add Domain"** to save the whitelist entry
  </Step>
</Steps>

### Domain Format Examples

| ✅ Correct Format        | ❌ Incorrect Format       |
| ----------------------- | ------------------------ |
| `example.com`           | `https://example.com`    |
| `www.example.com`       | `http://www.example.com` |
| `subdomain.example.com` | `example.com/page`       |
| `shop.mystore.com`      | `*.example.com`          |

<Warning>
  Each subdomain must be added separately. Adding `example.com` does **not** automatically allow `www.example.com` or `shop.example.com`.
</Warning>

## Managing Existing Domains

### Edit Domain

* Click the **"Edit"** button next to any domain
* Modify the hostname, description, or active status
* Click **"Update Domain"** to save changes

### Deactivate Domain

* Edit the domain and uncheck **"Active"**
* Inactive domains will block video playback
* Useful for temporarily restricting access

### Remove Domain

* Click the **"Remove"** button next to any domain
* Confirm the deletion in the popup
* Domain will be permanently removed from whitelist

## Integration Considerations

### Player Behavior

When a domain is blocked:

* Video starts playing normally for optimal user experience
* Domain validation happens asynchronously in the background
* If domain is not whitelisted, video playback is stopped and shows:

```
Video Unavailable
This video cannot be played from this domain. Contact the video owner for access.
```

The validation component:

* Destroys HLS instance to stop streaming
* Resets video element source
* Shows user-friendly blocked overlay
* Tracks 'domain-blocked' event for analytics

### Error Handling

If domain validation fails due to network issues:

* Videos will play normally (fail-safe approach)
* Error is logged to browser console
* Consider implementing retry logic in your integration

### Development & Testing

During development, you may want to:

1. Add `localhost` to your whitelist
2. Add your staging domain
3. Test blocked domain behavior on unauthorized domains

## Common Use Cases

### E-commerce Store

```
✅ Allowed Domains:
- mystore.com
- www.mystore.com  
- checkout.mystore.com
```

### Marketing Campaign

```
✅ Allowed Domains:
- campaign.example.com
- landing.marketing.com
- partner-site.com
```

### Content Protection

```
❌ Block unauthorized use on:
- Competitor websites
- Spam/malicious sites
- Unauthorized resellers
```

## Troubleshooting

### Videos Not Playing

1. **Check domain whitelist**: Ensure the current domain is added
2. **Verify subdomain**: `www.example.com` ≠ `example.com`
3. **Check domain status**: Ensure domain is marked as "Active"

### Common Issues

| Issue                           | Solution                                     |
| ------------------------------- | -------------------------------------------- |
| Video blocks on `www` subdomain | Add both `example.com` and `www.example.com` |
| Development site blocked        | Add `localhost` or your dev domain           |
| Staging environment blocked     | Add staging domain to whitelist              |

### Getting Help

If you encounter issues:

* Check browser console for validation errors
* Verify domain format matches exactly
* Contact support with your workspace code and domain details

<Info>
  Domain validation logs are available in your workspace analytics for monitoring and debugging purposes.
</Info>