Overview

Your organization pastes its measurement IDs once in the console, attaches them to an app, and the SDK loads them. No tag manager snippet in your repo, no pixel IDs in your environment variables, and the conversion events BuildBase already observes - signup, login, checkout, payment - fire without you writing them.

'use client';

import { ApiVersion } from '@buildbase/sdk';
import { SaaSOSProvider } from '@buildbase/sdk/react';

<SaaSOSProvider
  serverUrl={serverUrl}
  version={ApiVersion.V1}
  orgId={orgId}
  auth={{ clientId, redirectUrl }}
  tracking={{}}
>
  {children}
</SaaSOSProvider>;

If you already have the provider from the Quickstart, the only new thing is tracking={{}}. That is the whole integration for a product app, apart from passing your visitors' consent. tracking={{}} takes the defaults. Leave the prop out and nothing is fetched and nothing is installed.

Start here

1. Add your tags under Settings › Tracking & Tags, and attach them to your app under Auth › Clients. A tag in the library that is attached to nothing loads nowhere.
2. Install @buildbase/sdk 0.0.68 or later.
3. Turn tracking on with tracking={{}}, as above, or with <BuildBaseTracking> on a page without the provider.
4. Pass consent. Render your banner from the manifest and restore the stored answer on every load - see Consent. Until you do, only consent-aware Google tags load, in denied mode.
5. Check it works - see Verify.
6. Optionally, report sales from a server - see Server-side conversions.

Sign-up, login, checkout and purchase are then reported for you, and so is the funnel between them. Events of your own are one track() call - see Events.

Where the three values come from

The Connect your app panel under Settings › Tracking & Tags shows the code on this page with all three filled in for the app you pick, and lists the tags that will load there.

A marketing site, without the provider tree

SaaSOSProvider is a deep context tree - auth, workspaces, billing, quotas - which is right for a product app and wrong for a static marketing page that only wants GA4. The /tracking entry point carries no UI dependencies, so it can sit in a root layout without moving the bundle.

'use client';

import { BuildBaseTracking } from '@buildbase/sdk/tracking';

<BuildBaseTracking serverUrl={serverUrl} orgId={orgId} clientId={clientId}>
  <CookieBanner />
  {children}
</BuildBaseTracking>;

Wrap the page, not just a corner of it. useTracking() - your banner's consent.set, and track() from any component - only reaches the tracker from inside it. Outside, it is a silent no-op.

Why the auth client is the unit

An auth client is what an app is, and it is what decides which tags load here rather than on your other properties. Your marketing site, your app and your docs each have their own client, so each can carry its own set - while sharing the entries that should be shared.

That sharing matters more than it looks. Subdomains of one product are a single site for tracking purposes: Google writes its cookies on the registrable domain, so a visitor who clicks an ad on example.com and signs up on app.example.com is one user and one attributed conversion - but only if both subdomains carry the same measurement ID and the same Google Ads tag. Define those once in the library and attach them to every client.

What arrives in the browser

The SDK asks the server what this client is configured with, and the server answers with only what is installable - an entry whose ID has not been filled in yet is a placeholder, not a misconfiguration, and is left out.

{
  "enabled": true,
  "scripts": [
    {
      "key": "ga4:G-XXXXXXXXXX",
      "provider": "ga4",
      "providerId": "G-XXXXXXXXXX",
      "consentCategory": "analytics"
    },
    {
      "key": "meta_pixel:123456789012345",
      "provider": "meta_pixel",
      "providerId": "123456789012345",
      "consentCategory": "marketing"
    }
  ],
  "consent": {
    "manifest": [
      {
        "key": "ga4:G-XXXXXXXXXX",
        "name": "Google Analytics 4",
        "vendor": "Google LLC",
        "category": "analytics",
        "privacyUrl": "https://policies.google.com/privacy"
      }
    ]
  }
}

An app with nothing attached gets enabled: false and installs nothing. So does an unknown client id - the two answers are identical on purpose, so an anonymous caller cannot probe which client ids are real.

What the SDK does with it

1. Captures the campaign parameters this page arrived with, before anything else.
2. Pushes Consent Mode v2 defaults - all four signals denied - before any Google tag exists.
3. Installs the analytics-category tags. Marketing-category tags wait for consent.
4. Fires a pageview on each SPA navigation, and the conversion events it observes.

Nothing about this wraps the vendors. After Meta loads, window.fbq is Meta's own fbq, and posthog, clarity, gtag and the rest are equally yours to call directly. See Events for what the SDK fires on your behalf and how to add your own.

Next

• Events - what fires for you, and how to send your own.
• Consent - the manifest your banner renders from.
• Providers - the fourteen tags, and the CSP they need.
• Server-side conversions - the sales no browser sees: a closed tab, a renewal, a refund.