Usercentrics

Usercentrics is a Consent Management Platform (CMP) used to collect, store, and signal end-user consent for third-party scripts under GDPR, CCPA, and the IAB TCF v2 framework.

Nuxt Scripts ships useScriptUsercentrics() so you can boot the CMP v3 ("Web CMP") loader, expose typed access to the window.__ucCmp programmatic API, and wire other registry scripts' consent triggers directly to Usercentrics' UC_UI_CMP_EVENT browser event.

export default defineNuxtConfig({
  scripts: {
    registry: {
      usercentrics: {
        trigger: 'onNuxtReady',
      }
    }
  }
})

const { proxy } = useScriptUsercentrics()

<script setup lang="ts">
const { proxy } = useScriptUsercentrics()

// noop in development, ssr
// just works in production, client
function handleAction() {
  // use proxy methods here
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

The composable comes with the following defaults:

• Trigger: Client Script will load when Nuxt is hydrating.
• Bundle / proxy: off The CMP is the consent surface itself, so it must hit the vendor origin directly. It is also exempt from consent gating.

You can access the ucCmp object as a proxy directly or await the $script promise. It's recommended to use the proxy for any void / Promise-returning calls.

const { proxy } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})
function showSettings() {
  proxy.ucCmp.showSecondLayer()
}

const { onLoaded } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})
onLoaded(({ ucCmp }) => {
  ucCmp.showFirstLayer()
})

Drive consent triggers from Usercentrics

Pair consent.onConsentChange(...) with useScriptTriggerConsent to load any third-party script the moment the user opts in via the Usercentrics banner.

<script setup lang="ts">
import { ref } from 'vue'

const { consent } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})

const analyticsGranted = ref(false)

if (import.meta.client) {
  consent.onConsentChange(async (detail) => {
    if (detail.type === 'ACCEPT_ALL' || detail.type === 'SAVE') {
      const details = await window.__ucCmp!.getConsentDetails()
      analyticsGranted.value = !!details?.services?.['your-template-id']?.consent?.status
    }
    else if (detail.type === 'DENY_ALL') {
      analyticsGranted.value = false
    }
  })
}

useScriptGoogleAnalytics({
  id: 'G-XXXXXXX',
  scriptOptions: {
    trigger: useScriptTriggerConsent({ consent: analyticsGranted }),
  },
})
</script>

<template>
  <button @click="consent.showSecondLayer()">
    Privacy settings
  </button>
</template>

onConsentChange returns a teardown function so you can unsubscribe inside onScopeDispose. The callback receives the raw UC_UI_CMP_EVENT detail (e.g. { type: 'ACCEPT_ALL' | 'DENY_ALL' | 'SAVE', ... }).

Open the consent UI

__ucCmp's methods are no-ops until the CMP API is ready. Use consent.whenReady() to await it, or call the helpers on consent directly (they no-op while the CMP boots):

<script setup lang="ts">
const { consent } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})

async function logConsent() {
  const cmp = await consent.whenReady()
  console.log(await cmp.getConsentDetails())
}
</script>

<template>
  <button @click="consent.showFirstLayer()">
    Show banner
  </button>
  <button @click="consent.acceptAll()">
    Accept all
  </button>
  <button @click="consent.denyAll()">
    Reject all
  </button>
</template>

Auto Blocking

If your Usercentrics ruleset uses Auto Blocking (rather than Manual Blocking), set autoblocker: true to inject the autoblocker module ahead of the loader:

useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
  autoblocker: true,
})

Example

Loading Usercentrics through app.vue when Nuxt is ready.

<script setup lang="ts">
useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
  scriptOptions: {
    trigger: 'onNuxtReady'
  }
})
</script>

Partytown

Do not run Usercentrics under Partytown. The __ucCmp API is method-heavy and unsafe to forward across the worker boundary, and the CMP needs main-thread DOM access to render its UI overlays.