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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/embed/customization/vanity-domains",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Setting up custom domains for embed

> Set up custom vanity domains for embedded Omni dashboards to enable first-party cookies and cohesive branding across content.

If you need to utilize first-party cookies or want to have cohesive branding across your content, custom vanity domains can be used for your embedded dashboards.

For example:

```typescript title="Vanity domain of analytics.blobsrus.com" theme={null}
const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "blobby@blobsrus.com",
  name: "Blobby",
  host: "analytics.blobsrus.com",
  secret: "abcdefghijklmnopqrstuvwxyz123456"
})
```

## Requirements

Custom domains are only available for embed use cases.

### Domain selection

The domain you select has a set of requirements:

* Only one vanity domain (or wildcard domain) is allowed per Omni organization.
* A vanity domain must have three or more parts. For example, `myapp.com` without `products` prepended will not be considered a valid vanity domain. Valid examples include `products.myapp.com` or `dev.products.myapp.com`.
* **You must use a new, dedicated subdomain:**
  * Omni needs to configure specific DNS records and SSL certificates for the domain.
  * The domain must be set up to proxy requests to Omni's infrastructure.
  * Existing endpoints serve different content and can't be repurposed for Omni embeds.
* **To support first-party cookies**, the top-level domain of the vanity must match the embedding page. For example, for an embedding page like `myapp.com`, the embedded vanity domain should be `omni.myapp.com`.

  However, if you provide an embedded vanity domain of `myapp.omni.com` in addition to an embedding page of `myapp.com`, you may still encounter third-party cookie limitations on some browsers like Safari or other iOS applications.

## Wildcard vanity domains

<Note>
  This feature is currently in beta. To have it enabled, contact Omni support. If you attempt to add a wildcard vanity domain and the feature isn't enabled, you'll receive a `Wildcard domains are not supported. Contact support to enable this feature.` error.
</Note>

Omni supports wildcard vanity domains (e.g., `*.omni.myapp.com`) for multi-tenant embedding scenarios. When using a wildcard domain:

* You must specify a specific host when generating embed URLs (e.g., `tenant1.omni.myapp.com`, `tenant2.omni.myapp.com`)
* The host must match the wildcard pattern configured for your organization
* When using the [URL builder](/embed/setup/test-urls), you'll need to provide a **Host** value that matches your wildcard domain pattern

```typescript title="Wildcard vanity domain of *.analytics.blobsrus.com" theme={null}
const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "blobby@blobsrus.com",
  name: "Blobby",
  host: "tenant1.analytics.blobsrus.com",
  secret: "abcdefghijklmnopqrstuvwxyz123456"
})
```

## Setup

<Note>
  **Organization Admin** permissions are required to configure custom (vanity) domains in Omni.
</Note>

<Steps>
  <Step title="Configure the domain in Omni">
    1. In Omni, navigate to **Settings > Embed**.
    2. In the **Vanity domain** field:
       * [**For wildcard domains**](#wildcard-vanity-domains), enter your wildcard domain with the `*.` prefix (e.g., `*.omni.myapp.com`)
       * **Otherwise**, enter your domain (e.g., `omni.myapp.com`)
    3. Click **Save** to apply the configuration.
  </Step>

  <Step title="Update your DNS configuration">
    1. Reach out to Omni support with the vanity domain you configured in step 1.
    2. Omni will provide DNS configuration details and ask that you update your DNS configuration.
    3. Notify Omni that your DNS update is complete.

    After Omni completes our internal setup and notifies you, your custom domain should be usable.
  </Step>
</Steps>

## Session validation

When users log into an embedded Omni instance through a vanity domain, Omni sets a JavaScript-accessible cookie named `__omni_embed_vanity_session`. This cookie allows you to check whether a valid session exists before initiating the login flow, enabling you to skip the server handshake when a session is already present.

### Cookie details

* **Cookie name**: `__omni_embed_vanity_session`
* **Accessibility**: JavaScript accessible
* **Max-Age**: Matches the actual Omni session cookie duration. Update through a session refresh call to maintain accuracy.
* **Domain scope**: Only available when your embedding page and vanity domain share the same parent domain. For example, if your embedding page is `app.myapp.com` and your vanity domain is `embed.myapp.com`, both share the parent domain `myapp.com`, so your page can read the cookie.

  However, if your embedding page is `app.example.com` and the vanity domain is `embed.myapp.com`, the cookie will not be accessible because the domains don't share a common parent. This cookie is not set on standard embed domains like `embed-omniapp.co`.

### Usage

You can check for the presence of this cookie before attempting to log in a user:

```javascript title="Check for existing session" theme={null}
function hasActiveSession() {
  return document.cookie.split('; ').some(cookie =>
    cookie.startsWith('__omni_embed_vanity_session=')
  );
}

// Skip login flow if session exists
if (hasActiveSession()) {
  // Load embedded content directly
  loadEmbeddedDashboard();
} else {
  // Initiate login flow
  performSSOHandshake();
}
```

### Limitations

In some cases, the `__omni_embed_vanity_session` cookie may be present even though the actual session has expired. If this occurs, the embedded Omni page will appear logged out. To handle this scenario, your application should be prepared to reinitiate the login flow when the embedded content indicates the user is not authenticated.