Google Maps

Configure the map

Copy the map's iframe embed URL. Choose the category matching its use in your application; this example uses functionality permission.

export const embedCategory = 'functionality' as const;
export const embedURL =
	'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
export const embedTitle = 'Map showing our office location';
export const embedAspectRatio = '4 / 3';

Replace the example URL with the complete embed URL for your map. Keep the address and a directions link outside the consent-gated embed.

Add the embed to your framework

Create src/embed-config.ts using the configuration on this page, then select your framework. Keep the existing consent setup, its policy and preferences UI. These examples do not create a second consent provider.

'use client';

import { ConsentGate } from 'c15t/next';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}

Browser helper for Astro and JavaScript

Only the Astro and JavaScript examples need this helper. It creates the iframe when permission allows it, keeps an existing player mounted across unrelated snapshot updates, and removes it on revocation.

import {
	embedCategory,
	embedURL,
	embedTitle,
	embedAspectRatio,
} from './embed-config';

type EmbedKernel = {
	getSnapshot: () => {
		effectivePermissions: Record<typeof embedCategory, boolean>;
	};
	subscribe: (listener: () => void) => () => void;
};

export function mountConsentEmbed(
	container: HTMLElement,
	kernel: EmbedKernel,
	openPreferences: () => void
) {
	const render = () => {
		if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
			if (container.querySelector('iframe')) return;
			const frame = document.createElement('iframe');
			frame.src = embedURL;
			frame.title = embedTitle;
			frame.loading = 'lazy';
			frame.allowFullscreen = true;
			Object.assign(frame.style, {
				width: '100%',
				aspectRatio: embedAspectRatio,
				minHeight: '200px',
				border: '0',
			});
			container.replaceChildren(frame);
		} else {
			if (container.querySelector('button')) return;
			const button = document.createElement('button');
			button.type = 'button';
			button.textContent = 'Open privacy settings to view this content';
			button.onclick = openPreferences;
			container.replaceChildren(button);
		}
	};

	render();
	const unsubscribe = kernel.subscribe(render);
	return () => {
		unsubscribe();
		container.replaceChildren();
	};
}

Keep a transcript, address or other useful alternative outside the embed. loading="lazy" is a performance hint; the consent condition controls whether the iframe exists at all. A denied category may be fixed by policy, so opening preferences does not guarantee that the visitor can grant it.

Gate existing iframe markup

For markup that uses data-category and data-src, the createIframeBlocker module from c15t/modules/iframe-blocker promotes data-src only when the category has consent and the URL resolves to HTTP or HTTPS. Relative URLs resolve against the iframe document's base URL. Malformed URLs and other schemes, including javascript:, data: and blob:, remain in data-src without loading. Correct the URL and call processAllIframes() to retry.

Keep the initial URL in data-src, without src, so the browser cannot load it before the blocker runs. The module does not sanitize arbitrary HTML or modify iframes without data-category.

Verify before and after permission

On a fresh opt-in session, inspect Network and confirm the iframe has not requested the map. Grant the category and confirm the map mounts. Revoke it and check the frame returns to its blocked state. Keep useful fallback information, such as the address and directions link, available outside the map.

For a JavaScript Maps SDK instead of an iframe, register a category-gated script and manage the widget's cleanup. Do not use this iframe recipe as evidence that an independently loaded Maps SDK is blocked.