fingerlydocs
fingerly.io Log inDashboard
Guides

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.

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.

Set up

  1. 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.

  2. 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:

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

  3. 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.

  4. Step 4: Point the browser SDK at it

    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

StatusMeaningWhat 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.
  • 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

ProxyHosted subdomain
Runs onYour own host, at one pathFingerly, under a subdomain of yours
Proxy keyYes, as a server secretNone. Fingerly terminates the connection, so it sees the visitor's address directly.
What blockers can followNothing: the request never leaves your host from the browser's point of viewThe CNAME, for DNS-level blockers and extensions that resolve names
Browser SDK endpointsThe path, such as /k7x2qm4aThe 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 does all of this from code.

Last updated