# Technical Implementation Guide
*Audience: engineers deploying and integrating the Relyance Consent Agent.*
## 1. Providing a login recording for authenticated scans
Do this first, before installing the agent, if any of your domains need to be scanned behind a login wall (a customer portal, an authenticated app shell, etc.). The Domain Analyzer can crawl those pages (see the [Admin Configuration Guide](/docs/consent-management/admin-configuration-guide/#scanning-behind-authentication)) - configuring it is entirely an admin task in the platform, but producing the **login recording** for form-based logins is a small, one-time engineering task:
1. Open Chrome DevTools → the **Recorder** panel.
2. Start a new recording and step through the actual login flow: navigate to the login page, enter credentials, submit, and land on an authenticated page.
3. Stop the recording and export it as JSON.
4. Hand the exported JSON file to the admin configuring the domain - they upload it in the Authentication step of the Add/Edit Domain wizard, where Relyance replays it to sign in before crawling.
Basic Auth (no recording needed) is also supported for domains protected only by an HTTP Basic auth prompt. Everything else here - selecting the auth method, entering credentials, testing, scan scheduling, and notifications - is configured by admins directly in the platform; no code changes are required. If none of your domains sit behind a login, skip ahead to installing the agent below.
## 2. Overview
The **Consent Agent** is a single JavaScript file your team embeds on every page of a domain. Once loaded, it:
- Looks up the current domain against your Relyance configuration and applies the correct consent rules automatically - **the script itself is identical across every domain you manage**; there's no per-domain build.
- Detects the visitor's region and determines which Region Group (and therefore which consent model, banner, and behavior) applies.
- Renders the consent banner, preference center, and related UI.
- Blocks or allows cookies, scripts, storage writes, and network requests based on the visitor's actual consent state.
- Emits events your own code can listen to, and exposes a small JS API for things like reopening the preference center.
- Can forward consent state into a third-party tag manager such as Google Tag Manager via a short integration script (see §14) - native, automatic dataLayer updates from the agent are planned for a future release.
Get your exact install snippet from **Domain Detail → Agent tab → Deploy the Consent Agent** in the Relyance platform - copy it directly rather than hardcoding a URL from documentation, since the exact script host can differ by environment and data-residency region (e.g., EU vs. US hosting).
## 3. Installation
Place the script tag in ``, **as early as possible** - before any other tag manager, analytics, or third-party script. This is the single most important rule in this guide: if other scripts load before the agent, they can fire before consent is evaluated, defeating the purpose of the integration.
```html
My Site
...
```
The agent initializes itself automatically on load - there's no manual `init()` call required.
### Next.js
A plain `
```
**The agent fails to initialize.** Confirm `data-relyance-consent-appId` is present and correct - the agent throws immediately and does nothing further if it's missing.
**Consent doesn't persist across subdomains.** Confirm the domain configured in Relyance for this property matches the parent domain you expect cookies to be scoped to (not a specific subdomain).
## 14. Google Tag Manager (GTM) integration
**This section is optional.** The agent already blocks non-consented scripts, cookies, storage, network requests, pixels, and beacons natively (§6) - you don't need a GTM integration for enforcement to work. This pattern is most relevant if you're **not** running with `data-relyance-zero-fire-mode="true"` (so script/iframe blocking isn't active at the interceptor level, §4) and want your tag manager itself to be consent-aware, or if your team simply prefers gating tags through GTM triggers rather than relying solely on the agent's native blocking. If you are using zero-fire mode, treat this as a nice-to-have rather than a requirement.
The agent does not yet push consent state into a tag manager's dataLayer automatically - that native integration is planned for a future release. Until then, forwarding consent to Google Tag Manager (or any dataLayer-driven tag manager) is a small integration you add yourself, using a utility already exposed by the agent. This section documents that pattern.
### Reading consent state programmatically
The agent exposes a lower-level storage utility, separate from the `window.Relyance` API described in §7, for reading the visitor's full consent object directly:
```js
const consentStatus = Relyance.agent.relyanceConsentStorageService.readConsentFromBrowser();
```
This returns the same underlying consent record described in §5 (the `rly_consent` cookie payload), but as a live JS object rather than something you decode yourself. A representative response:
```json
{
"model": "CONSENT_MODEL_OPTIONS_OPT_IN",
"consentPurposes": [
{
"purposeId": "PROCESSING_ACTIVITY_STRICTLY_NECESSARY",
"name": "Strictly Necessary",
"visible": true,
"checked": true,
"alwaysActive": true
},
{
"purposeId": "PROCESSING_ACTIVITY_MARKETING",
"name": "Marketing",
"visible": true,
"checked": false,
"alwaysActive": false
},
{
"purposeId": "69388d52666af3da8b53a9e8",
"name": "Preferences",
"visible": true,
"checked": false,
"alwaysActive": false
},
{
"purposeId": "69388d72666af3da8b53a9ea",
"name": "Analytics",
"visible": true,
"checked": false,
"alwaysActive": false
}
],
"timestamp": 1781217123777,
"consentStorageEnabled": true,
"isDefaultConsent": true
}
```
| Field | Meaning |
|---|---|
| `purposeId` | Identifier for the consent category. Well-known categories use a `PROCESSING_ACTIVITY_*` constant (matching the keys used in the `RELYANCE_CONSENT_UPDATE` event, §8); custom categories use a MongoDB-style ObjectId string instead - map these to readable names yourself. |
| `name` | Human-readable category label, as configured in your Relyance account. |
| `checked` | `true` if the visitor has consented to this category, `false` if denied. |
| `alwaysActive` | `true` for categories (e.g., Strictly Necessary) that can't be toggled off. |
| `isDefaultConsent` | `true` means the visitor hasn't interacted with the banner yet - this is the state on first page load, before any explicit choice. |
Because custom categories are keyed by ObjectId rather than a named constant, you'll need to maintain a small map from those IDs to your own dataLayer key names - see the implementation script below.
### Pushing consent to the dataLayer
Add this script after the Relyance Consent Agent script tag. It pushes an initial `RelyanceConsentLoaded` event on load, then re-pushes on every consent change:
```html
```
The `try/catch` matters here: if this script runs before the agent has finished initializing, `Relyance.agent` may not exist yet. For a more deterministic first push, gate the initial call on `Relyance.isInitialized` or the `RELYANCE_AGENT_INITIALIZED` event (§7-8) instead of relying solely on the catch block.
### Setting up GTM
**1. Create a Data Layer Variable per consent category** (Variables → User-Defined Variables → New → Data Layer Variable), named to match each key from the map above:
| GTM variable name | Data layer key |
|---|---|
| DLV - Relyance Consent Necessary | `relyance_consent_necessary` |
| DLV - Relyance Consent Marketing | `relyance_consent_marketing` |
| DLV - Relyance Consent Preferences | `relyance_consent_preferences` |
| DLV - Relyance Consent Analytics | `relyance_consent_analytics` |
| DLV - Relyance Is Default Consent | `relyance_is_default_consent` |
**2. Create an Active and a Blocking trigger per category.** Both are Custom Event triggers matching `RelyanceConsentLoaded|RelyanceConsentUpdated` with regex matching enabled:
- **Active** (e.g., "Consent Active - Analytics"): fires when `DLV - Relyance Consent Analytics` equals `true`.
- **Blocking** (e.g., "Consent Blocked - Analytics"): fires when it does not equal `true`.
The Strictly Necessary category typically doesn't need this pattern, since it's always `true`.
**3. Apply the triggers to each tag.** On the tag you want to gate (e.g., a GA4 Configuration tag), add the Active trigger under Triggering, then add the matching Blocking trigger as an **exception**. The tag will only fire once the required consent is `true`, and will stop firing again if consent is later revoked.
**Suggested category-to-tag mapping:**
| Consent category | Typical tag types | dataLayer key |
|---|---|---|
| Strictly Necessary | Security, authentication, load balancing - no blocking needed | `relyance_consent_necessary` |
| Marketing | Google Ads, Meta Pixel, LinkedIn Insight, Bing Ads, TikTok Pixel | `relyance_consent_marketing` |
| Preferences | Chat widgets, A/B testing, language/region preferences | `relyance_consent_preferences` |
| Analytics | GA4, Adobe Analytics, Hotjar, Heap | `relyance_consent_analytics` |
### Handling mid-session consent changes
When a visitor updates their choices through the preference center, the agent dispatches `RELYANCE_CONSENT_UPDATE` (§8). The script above listens for it and pushes a `RelyanceConsentUpdated` event with the refreshed flags - so make sure every trigger's event-name regex includes both `RelyanceConsentLoaded` and `RelyanceConsentUpdated`, or tags won't re-evaluate when a visitor changes their mind mid-session.
### Default-deny state before the agent loads
Tags can otherwise fire during the brief window before the agent (and this script) has run. Push an explicit deny-by-default state at the very top of ``, before both the GTM snippet and the Relyance agent script:
```html
```
Defaulting every non-essential category to `false` means no tracking occurs until a visitor has explicitly consented - the recommended posture under GDPR and other opt-in regulations (see the [Legal and Compliance Guide](/docs/consent-management/legal-and-compliance-guide/#the-four-consent-models)).
### Testing the integration
- **GTM Preview mode:** load your site with Preview active, select the `RelyanceConsentLoaded` event in the debug panel, and confirm each `DLV - Relyance Consent *` variable shows the expected value, and that gated tags appear under Tags Fired or Tags Not Fired as expected.
- **Mid-session update:** with Preview still active, open the preference center, change a category, and confirm a `RelyanceConsentUpdated` event appears with the updated variable value and the relevant tags re-firing or getting blocked.
- **Browser console:** inspect pushed events directly with `window.dataLayer.filter(e => e.event && e.event.startsWith('Relyance'))`, and cross-check against the raw object from `Relyance.agent.relyanceConsentStorageService.readConsentFromBrowser()`.
### GTM integration troubleshooting
| Symptom | Likely cause / fix |
|---|---|
| `readConsentFromBrowser()` returns `undefined` | The agent hasn't finished loading yet. Confirm the Relyance script tag loads before your dataLayer push script, and gate the call on `RELYANCE_AGENT_INITIALIZED` if it's still unreliable. |
| GTM Data Layer Variables are empty | Variable names are case-sensitive - confirm they exactly match the keys pushed by your script. Inspect the `RelyanceConsentLoaded` event's Variables tab in Preview mode. |
| Tags fire before consent is given | Add the default-deny push above, before the GTM snippet in ``. |
| Tags don't re-fire after a consent update | Confirm your trigger's event-name regex includes `RelyanceConsentUpdated`, and that `RELYANCE_CONSENT_UPDATE` is actually firing on preference save (log it directly: `Relyance.agent.addEventListener('RELYANCE_CONSENT_UPDATE', console.log)`). |
| Tags never fire, even after consent is granted | Check that the `purposeId` values in `RELYANCE_PURPOSE_MAP` match your account's actual processing activities - log the raw consent object and cross-check the IDs. |
## Related reading
- [Overview and Implementation Guide](/docs/consent-management/overview-and-implementation-guide/) - where this fits in the overall rollout
- [Admin Configuration Guide](/docs/consent-management/admin-configuration-guide/) - configuring the platform side (Region Groups, Tracking Technology Management, Interface Builder, Domain Analyzer scheduling and authentication)
- [Consent Logs and Reporting](/docs/consent-management/consent-logs-and-reporting/) - what gets logged and how to export it