@getuserfeedback/adapters

@getuserfeedback/adapters publishes external-system translation layers built on top of the public widget protocol.

GTM

The @getuserfeedback/adapters/gtm entrypoint is the authoritative source for Google Tag Manager template generation. It owns:

• GTM color scheme normalization logic
• GTM template parameter generation
• GTM runtime source generation
• GTM permission generation
• GTM importable template.tpl file generation
• GTM template defaults, help text, and option labels
• the canonical loader script base URL pattern

Public exports

Template inputs and init translation:

• GTM_CONSENT_TYPES
• isGtmConsentType(value)
• normalizeGtmThemeInput(input)
• resolveDefaultConsentFromGtm(input)
• buildInitOptionsFromGtmTemplate(input)

Types:

• GtmConsentType
• GtmConsentValue
• GtmConsentState
• GtmTemplateInput

Template generation:

• DEFAULT_GTM_LOADER_SCRIPT_BASE_URL
• buildGtmTemplateParameters(options?)
• buildGtmRuntimeSource(options?)
• buildGtmPermissions(options?)
• buildGtmTemplateInfo(options?)
• buildGtmTemplateParts(options?)
• buildGtmTemplateArtifact(options?)
• buildGtmTemplateFileSource(options?)

Consent behavior

The GTM template no longer exposes consent settings in its UI.

• The template follows GTM Consent Mode directly.
• getuserfeedback defaultConsent scopes are inferred from GTM's standard consent signals only.
• analytics.measurement follows analytics_storage.
• There is no custom consent remapping UI or runtime path.
• If no GTM consent state is available, the adapter leaves defaultConsent unset.

Color scheme behavior

Generated GTM color scheme support accepts:

• fixed light
• fixed dark
• fixed system
• host-sync via protocol auto-detect attributes
• GTM variable-driven values
• comma-separated auto-detect attribute lists

The adapter normalizes all of these into protocol-valid colorScheme.

Identity behavior

The generated template supports:

• Intelligent mode, which reads common data-layer keys for user ID, email, phone, first name, and last name
• Custom mode, which lets GTM explicitly map a main identity and traits
• Disabled mode, which skips identify entirely

Generate GTM output

import {
	buildGtmTemplateArtifact,
	buildGtmTemplateFileSource,
} from "@getuserfeedback/adapters/gtm";

const artifact = buildGtmTemplateArtifact({
	loaderScriptBaseUrl: "https://cdn.getuserfeedback.com/widget/loader/v1",
});

const templateFile = buildGtmTemplateFileSource({
	loaderScriptBaseUrl: "https://cdn.getuserfeedback.com/widget/loader/v1",
});

Use the package script to write a local importable file:

bun run generate:gtm-template

For the sandbox-backed GTM smoke:

bun run generate:gtm-template:sandbox-hybrid

buildGtmTemplateArtifact() returns the rendered GTM sections. buildGtmTemplateFileSource() returns a full importable template.tpl.

Verifying GTM template changes

When edits in this package change GTM template generation or runtime behavior, the usual verification path spans more than this package:

• Regenerate the hybrid upload artifact from packages/adapters.
• Run bun run test in packages/adapters.
• Run the real GTM smoke e2e from packages/widget-browser-tests:

bun run test:playwright:substrate-sandbox -- src/tests/gtm-smoke.e2e.ts

That browser test lives outside this package because it exercises the uploaded GTM template against the sandbox host, local CDN/API endpoints, and a real GTM container. It typically expects GTM_CONTAINER_ID to be set in packages/widget-browser-tests/.env.local.

What the GTM repo should still own

After importing the published package, the GTM repo should only own:

• brand thumbnail and base64 image assets
• metadata.yaml
• publishing and release workflow

It should not rebuild parameters, runtime source, permissions, file assembly, or GTM-specific init payload translation.

Customizing the loader base URL

Pass loaderScriptBaseUrl to:

• buildGtmRuntimeSource
• buildGtmPermissions
• buildGtmTemplateParts
• buildGtmTemplateArtifact
• buildGtmTemplateFileSource

The same base URL is used to derive the runtime loader URL and the inject_script permission pattern.

Pass runtimeEndpoints when you need the generated template to point loader bootstrap at non-default core and api endpoints.

Versioning expectations

Any change that affects generated GTM output is a public package change and should be versioned accordingly. This includes:

• parameter shape or defaults
• runtime behavior
• permission generation
• color scheme normalization
• identity lookup behavior
• consent derivation behavior

Release notes should call out template-affecting changes explicitly.