Analytics de

Analytics und Google Tag Manager

🌐 Diese Seite auf: English · Português · Español · Français · Deutsch

Analytics in eQuantic.UI ist eine Fähigkeit, kein Skript, das man einklebt: Eine Seite verlangt IAnalytics, so wie sie eine Kamera verlangt, und erfährt nie, wer zuhört. Das Paket eQuantic.UI.Gtm ist ein INSTALLER: Ein Aufruf verdrahtet einen Google-Tag-Manager-Container mit dieser Fähigkeit, Ende zu Ende.

Seit 0.2.0-preview.29

---

Installation

using eQuantic.UI.Gtm;

builder.Services.AddUI(options => options
    .ScanAssembly(typeof(Program).Assembly)
    .UseGtm("GTM-XXXXXXX"));

Dieser eine Aufruf installiert drei Dinge in die HTML-Shell:

1. Das offizielle Container-Snippet: dieselben Bytes, die Google dokumentiert, nur dort parametrisiert, wo GTM sie selbst als Schablone behandelt.
2. Die Installer-Deklaration (window.__EQ_ANALYTICS__): das, was die IAnalytics-Realisierung der Runtime armiert. Ohne Installer ist das Tracking von Bauart eine stille Nulloperation.
3. SPA-Seitenaufrufe: Der Client-Router kündigt jede bestätigte Navigation an (eq:navigate), und die Shell macht daraus page_view-Pushes, die page_path und page_title tragen, die eigenen Feldnamen von GA4. Den ersten Laden sieht der Container selbst; dies sind die Navigationen, die er nicht sehen kann.

Die Container-Id wird beim Start validiert: Eine vertippte Id installiert einen Container, der stillschweigend nichts sammelt, und das entdeckt man im leeren Bericht des nächsten Monats, früh zu verweigern ist also das freundlichere Scheitern.

Aus einer Seite tracken

public override VisualNode Build(ComponentContext context)
{
    _analytics = context.GetService<IAnalytics>();
    // …
}

private async Task Submit()
{
    // …nachdem der Server ja gesagt hat:
    _analytics?.Track("sign_up");
    _analytics?.Track("purchase", new Dictionary<string, object?>
    {
        ["value"] = 42,
        ["currency"] = "EUR",
    });
}

Track ist per Kontrakt Fire-and-forget, denn Analytics darf eine Seite nie warten lassen. Ereignisnamen sind IHR Vokabular (sign_up, begin_checkout); das Framework erfindet keinen und stellt keinem ein Präfix voran. Auf dem Server ist derselbe Aufruf eine Nulloperation: SSR ist kein Nutzer, und eine Seite, die beim Rendern trackte, würde ihre eigenen Crawler zählen.

Ein Container je Anwendung, mit Absicht

Ein GTM-Container lädt in das DOKUMENT und entlädt sich nie, in einer SPA kann es also keinen "Container je Seite" geben. Für Variation je Route sind die eigenen Trigger des Containers da: Der automatische page_view trägt page_path genau dafür, dass das Marketing Tags je Route auslösen kann, ohne dass die Anwendung sich ändert, und das ist der ganze Sinn eines Tag-Managers.

Was es gibt, ist der Fall Agentur plus Kunde: Rufen Sie UseGtm einmal je Container auf. Der zweite Aufruf fügt nur sein Snippet hinzu; beide reiten auf demselben dataLayer (GTMs eigene Regel für mehrere Container, beim Start erzwungen).

Optionen

.UseGtm("GTM-XXXXXXX", gtm => gtm
    .WithDataLayerName("eqData")          // wenn ein anderes Skript `dataLayer` schon besitzt
    .WithoutSpaPageViews()                // der Container nutzt stattdessen GA4s History-Trigger
    .WithEnvironment("auth…", "env-9")    // GTM-Umgebungen (gtm_auth / gtm_preview)
    .WithConsent())                       // den Container erst nach der Zustimmung laden

Schalten Sie WithoutSpaPageViews() ein, wenn der Container History-Änderungen selbst verfolgt, sonst wird dieselbe Navigation zweimal gezählt.

Zustimmung (DSGVO / LGPD)

Status: ausgeliefert in 0.2.0-preview.46.

Beide Regelwerke sagen dasselbe über Analytics-Cookies: nichts wird gesetzt, bevor die Besucherin ja sagt, und ein "nein" wird erinnert. Drei Teile machen das wahr, ohne dass die Anwendung eine Zeile JavaScript schreibt:

• IConsent: eine Fähigkeit wie jede andere (context.GetService<IConsent>()): State ist Unknown, Granted oder Denied; Grant() / Deny() speichern die Antwort. Im Web lebt sie in EINEM Cookie, eq-consent, ein Jahr lang, und eine Änderung wird auf dem Dokument als eq:consent angekündigt. Auf dem Server wird derselbe Cookie aus der Anfrage GELESEN, sodass das erste Paint einer wiederkehrenden Besucherin kein Banner enthält, und der SSR-Durchgang die Antwort kennt, die der Browser hält.
• CookieConsent(policyHref): die Karte, die fragt. Nur gezeichnet, solange die Antwort unbekannt ist, und in dem Moment verschwunden, in dem sie gegeben wird; zwei Buttons (annehmen / ablehnen) und der Link zur Datenschutzerklärung, alles lokalisiert (EN, pt-BR, es) und jedes überschreibbar. Es ist eine Karte, keine Ebene: Setzen Sie sie dorthin, wo die Shell sie will (ein Pinned am Fuß der Seite ist ihr üblicher Ort).
• UseGtm(id, gtm => gtm.WithConsent()): Der Installer bindet den Container an die Antwort. Der Head deklariert die denied-Voreinstellungen von Googles Consent Mode, und das Skript des Containers wird nur geholt, wenn der Cookie granted sagt, oder in dem Moment, in dem eq:consent es sagt. Eine Besucherin, die ablehnt oder nie antwortet, lädt überhaupt keinen Tag-Manager herunter. Track()-Aufrufe, die zwischenzeitlich erfolgen, liegen im dataLayer-Array, das der Container nachspielt, wenn die Zustimmung später kommt.

builder.Services.AddUI(o => o.ScanAssembly(typeof(Program).Assembly)
    .UseGtm("GTM-XXXXXXX", gtm => gtm.WithConsent()));

// irgendwo, das jede Seite rendert, am Fuß ihrer Shell:
Pinned(CookieConsent("/privacy"))

Standardmäßig aus: Ein Installer, der schon ohne Fragen lief, läuft weiter. Ihn einzuschalten ist die Entscheidung der Anwendung, gepaart mit der Karte und einer Richtlinienseite hinter dem Link, denn eine Zustimmungskarte ohne Richtlinie dahinter ist ein Versprechen, das die Website nicht halten kann.

Was absichtlich fehlt

• Das <noscript>-iframe aus Googles Installationsanweisungen. Es misst Nutzer, deren Browser kein JavaScript ausführen, und so ein Nutzer bekommt hier überhaupt keine Anwendung: Es gibt nichts zu messen.
• Eine native Realisierung. IAnalytics löst heute in einem Photon-Fenster zu einer Nulloperation auf; die mobilen Analytics-Brücken kommen mit der nativen Spur.

---

Verwandt

• Server-Integration: AddUI, die Shell, und wo UseGtm hängt.
• Fähigkeiten: das Muster des Verlangens-per-Schnittstelle, dem IAnalytics folgt.