# Hosted subdomain

> For a site that can run no proxy: point one subdomain of yours at Fingerly with a CNAME, and the browser SDK posts to it. Weaker than a proxy, and why.

Last updated: 2026-09-25

A hosted subdomain is for a site that can run no proxy at all, such as a hosted shop or a page builder that lets you add a DNS record but no code on the server. You add one subdomain of your site, such as `k7.shop.example`, point it at Fingerly with a `CNAME`, and Fingerly serves the browser SDK's calls on it, at a random path.

> **Weaker than a proxy:** It is a fallback, not a proxy. Browser extensions cannot see through a CNAME, so most content blockers see only your own name. But DNS-level blockers, and extensions that resolve names, such as uBlock Origin on Firefox, follow the record to Fingerly and can block it there. A [proxy](https://docs.fingerly.io/docs/proxy-integrations) on your own host has nothing to follow: use one if you can.

## Set up

### Step 1: Add the subdomain

In the dashboard, open **Integration > Proxy keys** and choose **Add subdomain** under **Hosted subdomain**. Enter a new name on your site that means nothing, such as `k7.shop.example`. Keep the random path it offers, or type your own.

The dashboard shows whether hosted subdomains are available on your deployment. Owners and admins manage them, as they do proxies.

### Step 2: Create the DNS record

At your DNS host, create one `CNAME` from the subdomain to the target the dashboard shows. It prints the record for you:

```text DNS
k7.shop.example.  CNAME  <the target the dashboard shows>.
```

### Step 3: Wait for the certificate

A certificate for the subdomain is issued automatically once the record resolves, usually within minutes. Fingerly checks every pending subdomain every 30 seconds; **Check now** in the subdomain's menu checks at once. The subdomain is served as soon as it is **Active**.

### Step 4: Point the browser SDK at it

```ts fingerly.ts
import { load } from '@fingerly/web-js'

const fingerly = await load({
  apiKey: 'fly_pk_production_…',
  endpoints: 'https://k7.shop.example/q3v8wz1p',   // https://<subdomain><path>
})
```

The full URL, the subdomain followed by its path. **Show setup** in the subdomain's menu prints this line with your own values.

## Statuses

| Status | Meaning | What to do |
| --- | --- | --- |
| **Waiting for DNS** (`pending`) | The record does not resolve yet, or the certificate is still being issued. | Check the record at your DNS host. It is usually a few minutes after the record is in place. |
| **Active** (`active`) | The subdomain serves the browser SDK. | Nothing. |
| **Failed** (`failed`) | The certificate could not be issued. The dashboard shows the reason. | Fix what the reason says, then remove the subdomain and add it again. |

## Names

- It must be a subdomain, such as `k7.shop.example`, never the domain itself: a `CNAME` cannot sit on `shop.example`.
- Choose a label that means nothing. A new label containing a word blockers match is refused, such as `fp`, `metrics`, `tracking`, `analytics`, `telemetry`, `collect`, `events`, `pixel`, `beacon`, `ads`, `log`, `stats`, `sdk`, `visitor`, `fraud`, `device`, `bot`, `fingerprint` or `fingerly`: the same list as [proxy paths](https://docs.fingerly.io/reference/management/proxy-keys#paths).
- Each name can be added once, by one organization.
- The path follows the rules of a proxy path, and is random unless you type one.

## How it differs from a proxy

|  | Proxy | Hosted subdomain |
| --- | --- | --- |
| Runs on | Your own host, at one path | Fingerly, under a subdomain of yours |
| Proxy key | Yes, as a server secret | None. Fingerly terminates the connection, so it sees the visitor's address directly. |
| What blockers can follow | Nothing: the request never leaves your host from the browser's point of view | The `CNAME`, for DNS-level blockers and extensions that resolve names |
| Browser SDK `endpoints` | The path, such as `/k7x2qm4a` | The full URL, such as `https://k7.shop.example/q3v8wz1p` |

The public key's allowed origins stay your pages' origins, such as `https://shop.example`, not the subdomain. Only the subdomain's own path is answered, only to `POST` and CORS preflights, and nothing in the response names Fingerly. The subdomain is tied to your organization, so a public key from another organization is refused on it.

## Remove a subdomain

**Remove** in the subdomain's menu stops serving it at once and drops its certificate. Delete the `CNAME` at your DNS host afterwards. The [management API](https://docs.fingerly.io/reference/management/hosted-domains) does all of this from code.