fingerlydocs
fingerly.io Log inDashboard
SDKs

Google Cloud Run proxy

A small Cloud Run service behind your external Application Load Balancer, answering the one path the dashboard issued and forwarding the browser SDK's calls.

A small Cloud Run service that your external Application Load Balancer routes one path to. It answers the path the dashboard issued, on your own domain, and forwards only the browser SDK's submissions to Fingerly. It is not an open proxy: the upstream is a constant in the code, and every other path and method is refused. Version 1.0.0.

Set up

  1. Step 1: Create the proxy

    In the dashboard, open Integration > Proxy keys and choose New proxy. Pick the environment of the public key it will forward, and Google Cloud under How it runs. Copy the proxy key it shows once, and note the path it issued, such as /k7x2qm4a.

    The dashboard then prints the steps below, filled in with your proxy's own path and key. They stay under Show setup in the proxy's menu, without the key, which is never shown again.

  2. Step 2: Save the service

    Save server.mjs in an empty folder, with its package.json beside it. Buildpacks build the service from package.json, so no Dockerfile is needed. It needs Node 20 or newer.

    server.mjs is a small Node service with no dependencies: the built-in HTTP server and fetch. It reads FINGERLY_PROXY_KEY, FINGERLY_PATH, FINGERLY_CLIENT_IP_SOURCE and PORT (default 8080), and refuses to start when the address source is not one it knows. The dashboard prints it; copy it from there.

    package.json
    {
  "name": "first-party-relay",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.mjs"
  },
  "engines": {
    "node": ">=20"
  }
}

  3. Step 3: Store the proxy key

    In Secret Manager, readable by the service's runtime service account.

    Terminal
    printf '%s' 'fly_px_production_…' | gcloud secrets create first-party-relay-key --data-file=-
gcloud secrets add-iam-policy-binding first-party-relay-key \
  --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor

  4. Step 4: Deploy

    From the folder. The ingress setting means only your load balancer can reach the service.

    Terminal
    gcloud run deploy site-relay --source . --region=europe-west1 \
  --ingress=internal-and-cloud-load-balancing --allow-unauthenticated \
  --set-env-vars=FINGERLY_PATH=/k7x2qm4a \
  --set-secrets=FINGERLY_PROXY_KEY=first-party-relay-key:latest

  5. Step 5: Add it to your load balancer

    A serverless network endpoint group and a backend service. Use the scheme your load balancer already uses: EXTERNAL_MANAGED for the global external Application Load Balancer, EXTERNAL for the classic one.

    Terminal
    gcloud compute network-endpoint-groups create site-relay-neg \
  --region=europe-west1 --network-endpoint-type=serverless \
  --cloud-run-service=site-relay
gcloud compute backend-services create site-relay-backend \
  --global --load-balancing-scheme=EXTERNAL_MANAGED
gcloud compute backend-services add-backend site-relay-backend \
  --global --network-endpoint-group=site-relay-neg \
  --network-endpoint-group-region=europe-west1

  6. Step 6: Route the path to it

    In the URL map that serves your site. If your host has no path matcher yet:

    Terminal
    gcloud compute url-maps add-path-matcher URL_MAP --global \
  --path-matcher-name=site --default-service=YOUR_SITE_BACKEND \
  --new-hosts=www.example.com --path-rules=/k7x2qm4a=site-relay-backend

    If it has one, add a path rule for /k7x2qm4a with the backend site-relay-backend to it instead: export the map with gcloud compute url-maps export, add the rule and import it back, or use Load balancing > your load balancer > Edit > Routing rules in the console.

  7. Step 7: Point the browser SDK at the path

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

const fingerly = await load({
  apiKey: 'fly_pk_production_…',
  endpoints: '/k7x2qm4a',
})

    The SDK posts both of its calls to the path exactly as given. Once pages use it, the proxy's row in Proxy keys shows it last seen, running gcp-cloud-run/1.0.0, with its requests over the last 30 days.

How the visitor's address is trusted

The load balancer appends <client-ip>,<load-balancer-ip> to X-Forwarded-For, and vouches for nothing before them. The service sends the second-to-last entry as x-fingerly-client-ip, so entries a visitor writes on the left are ignored. That is its default address source, xff:2.

It holds only while every request arrives through the load balancer, which is what --ingress=internal-and-cloud-load-balancing enforces. If you put another proxy in front of the load balancer, the second-to-last entry is that proxy: set FINGERLY_CLIENT_IP_SOURCE to match, as described for the container.

What it sends and relays

Upstream, to https://api.fingerly.io/api/v1/ingest and nowhere else, on headers built from scratch: content-type, x-api-key, Idempotency-Key when present, and the x-fingerly-* headers the proxy sets itself (the proxy key, the visitor's address, the page origin, the user agent and x-fingerly-proxy-version: gcp-cloud-run/1.0.0). Cookies, Authorization and any x-fingerly-* header a visitor sends never leave.

Other methods answer 405 with Allow: POST, and other paths 404. Bodies over 1 MiB are refused with 413, redirects are not followed, and a missing or malformed key answers 503 rather than forwarding anything. With FINGERLY_PATH unset, the service answers 404 to everything.

Back to the page: the API's status and body, with only content-type, x-request-id, ratelimit-limit, ratelimit-remaining and retry-after, plus cache-control: no-store. Nothing relayed names Fingerly.

Last updated