# Data Layer (https://webmetic.de/docs/data-layer)

Mit dem Data Layer erfährt Ihr Server während eines Besuchs, welches Unternehmen dahintersteht, zum Beispiel die Bergquell Mineralbrunnen GmbH. Am Ende haben Sie:

- einen Data-Layer-Schlüssel
- eine Anfrage, die zur IP-Adresse eines Besuchs ID und Namen des Unternehmens liefert, oder `null`, wenn Webmetic keines kennt

Für Matomo steht das fertige [Matomo-Plugin](https://webmetic.de/docs/integrationen/matomo-plugin) bereit, das denselben Schlüssel nutzt.

## Bevor Sie beginnen [#bevor-sie-beginnen]

- **Dauer**: Schlüssel und erste Anfrage sind in wenigen Minuten eingerichtet.
- **Konto**: Sie brauchen ein Webmetic-Konto im Plan Enterprise.
- **Zugang**: Ihr Server muss `https://hub.webmetic.de` über das Internet erreichen.
- **Rechte**: Ein Admin erzeugt den Schlüssel. Andere Benutzer sehen das Fenster **API-Schlüssel** nicht und bitten einen Admin um den Schlüssel. Wenn ein Partner Ihr Konto betreut, entscheidet der Partner, ob **API** im Menü erscheint.
- **Plan**: Die serverseitige Erkennung gehört zum Plan [Enterprise](https://webmetic.de/docs/konto/plaene). Die Abfrage kostet derzeit keine Credits.

## Schlüssel erstellen [#schlüssel-erstellen]

Sie brauchen den Schlüssel aus der Karte **Data Layer**, denn der Schlüssel aus der Karte **Visitor Intelligence** funktioniert hier nicht.

Umgekehrt gilt der Data-Layer-Schlüssel nicht an den Endpunkten der API.

1. Öffnen Sie [**Menü** > **Integrationen** > **API**](https://app.webmetic.de/?menu=api_details). Das Fenster **API-Schlüssel** öffnet sich.
2. Wenn die Karte **Data Layer** den Text **Noch kein Schlüssel generiert.** zeigt, klicken Sie auf **Schlüssel generieren**. Webmetic zeigt den neuen Schlüssel.
3. Klicken Sie in der Karte **Data Layer** auf das Symbol **Kopieren**. Webmetic kopiert den ganzen Schlüssel, auch wenn er verdeckt ist.

![Die Karte Data Layer im Fenster API-Schlüssel mit verdecktem Schlüssel](https://webmetic.de/docs/media/de/light/api-schluessel-data-layer.webp)

Ihr Konto hat genau einen Data-Layer-Schlüssel, der für alle Ihre Websites gilt und nicht abläuft.

Klicken Sie nicht auf **Neu generieren**, wenn Sie den Schlüssel schon nutzen. Nach dem zweiten Klick gilt der alte Schlüssel sofort nicht mehr, auch nicht im Matomo-Plugin. Das lässt sich nicht rückgängig machen.

## Anfrage vom Server senden [#anfrage-vom-server-senden]

Senden Sie für jeden Besuch, dessen Unternehmen Sie wissen möchten, eine Anfrage an `GET https://hub.webmetic.de/dl` mit zwei Headern:

- `Authorization`: Ihr Data-Layer-Schlüssel, unverändert und ohne `Bearer` davor.
- `X-Data-Source`: die öffentliche IP-Adresse des Besuchs.

```bash tab="cURL" tab-group="lang"
curl "https://hub.webmetic.de/dl" \
  -H "Authorization: wmtc_IHR_API_SCHLUESSEL" \
  -H "X-Data-Source: 203.0.113.42"
```

```js tab="JavaScript" tab-group="lang"
// Node.js 18 or later, on your server
async function lookupCompany(visitorIp) {
  const res = await fetch('https://hub.webmetic.de/dl', {
    headers: {
      Authorization: 'wmtc_IHR_API_SCHLUESSEL',
      'X-Data-Source': visitorIp,
    },
    signal: AbortSignal.timeout(2000), // your own limit
  });
  if (!res.ok) throw new Error(`Webmetic /dl: ${res.status}`);
  return res.json(); // {"cid": "...", "cn": "..."} or null
}

lookupCompany('203.0.113.42').then((company) => console.log(company));
```

```python tab="Python" tab-group="lang"
import requests

def lookup_company(visitor_ip):
    res = requests.get(
        "https://hub.webmetic.de/dl",
        headers={
            "Authorization": "wmtc_IHR_API_SCHLUESSEL",
            "X-Data-Source": visitor_ip,
        },
        timeout=2,  # your own limit
    )
    res.raise_for_status()
    return res.json()  # {"cid": "...", "cn": "..."} or None

company = lookup_company("203.0.113.42")
```

JavaScript und Python brechen nach zwei Sekunden ab, damit Ihre Seite nicht auf die Antwort wartet. Sie wählen diesen Wert selbst.

Zum Testen brauchen Sie weder Enterprise noch ein Konto. Mit dem öffentlichen [Demo-Schlüssel](https://webmetic.de/docs/api/schnellstart#ohne-konto-testen) `wmtc_demo` und `X-Data-Source: 203.0.113.42` antwortet `/dl` mit dem erfundenen Beispielunternehmen Bergquell Mineralbrunnen GmbH, bei jeder anderen Adresse mit `null`.

Wenn `X-Data-Source` fehlt, prüft Webmetic die Adresse, von der die Anfrage kommt, also die Ihres Servers und nicht die des Besuchs.

Webmetic vergleicht die Adresse Zeichen für Zeichen. Bei einer falsch übernommenen Adresse antwortet `/dl` deshalb nicht mit einem Fehler, sondern mit `null`. Achten Sie auf diese Punkte:

- Wenn ein Proxy, ein Content Delivery Network (CDN) oder ein Load Balancer vor Ihrem Server steht, sieht Ihr Server dessen Adresse. Nehmen Sie die Adresse des Besuchs dann aus dem Header, den er weitergibt, zum Beispiel `X-Forwarded-For`.
- Wenn dieser Header mehrere Adressen enthält, senden Sie nur die des Besuchs.
- Senden Sie IPv4-Adressen ohne das Präfix `::ffff:`, das manche Server voranstellen.
- Senden Sie IPv6-Adressen in der üblichen Kurzschreibweise mit Kleinbuchstaben, wie die meisten Server sie liefern.

Jede Anfrage akzeptiert genau eine Adresse.

<Callout type="warn" title="Der Schlüssel gehört nicht in den Browser">
Rufen Sie `/dl` nie aus dem Browser oder einem Tag Manager auf. Der Schlüssel stünde dann im Code Ihrer Website, und alle, die Ihre Website öffnen, könnten ihn lesen. Wer den Schlüssel hat, fragt über Ihr Konto das Unternehmen hinter jeder beliebigen IP-Adresse ab.
</Callout>

## Antwort auswerten [#antwort-auswerten]

Wenn Webmetic ein Unternehmen zur Adresse kennt, antwortet `/dl` mit Status `200` und einem JSON-Objekt mit genau zwei Feldern:

```json
{
  "cid": "41ea486a9c95",
  "cn": "Bergquell Mineralbrunnen GmbH"
}
```

- `cid`: die ID des Unternehmens in Webmetic. Wenn das Unternehmen Ihre Website besucht hat, finden Sie es in der API unter derselben `company_id`.
- `cn`: der Name des Unternehmens. Er ist `null`, wenn Webmetic zur ID keinen Namen kennt.

Wenn Webmetic kein Unternehmen kennt, ist der Body `null`, ebenfalls mit Status `200`. Prüfen Sie im Code also den Body, nicht den Status.

`/dl` liefert keine Branche, Größe oder Domain.

`/dl` nennt jedes Unternehmen, das Webmetic zur Adresse kennt, auch wenn es Ihre Website noch nie besucht hat.

Eine Abfrage legt im Dashboard keinen Besuch und kein Unternehmen an. Die [Domain-Blacklist](https://webmetic.de/docs/konto/domain-blacklist) gilt für den Data Layer nicht.

## Antwort an den Tag Manager übergeben [#antwort-an-den-tag-manager-übergeben]

Wenn Ihre Tags in Google Tag Manager das Unternehmen brauchen, schreibt Ihr Server die Antwort beim Ausliefern der Seite in den `window.dataLayer`. Trotz des Namens schreibt Webmetic selbst nichts dort hinein.

Der Schlüssel bleibt dabei auf Ihrem Server, denn nur die Antwort gelangt in die Seite.

Webmetic gibt keine Ereignisse oder Variablen vor. Sie wählen die Namen selbst, zum Beispiel so:

```html
<script>
  // Rendered into the page by your server. Event and field names are your choice.
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'company_identified',
    company_id: '41ea486a9c95',
    company_name: 'Bergquell Mineralbrunnen GmbH',
  });
</script>
```

## Referenz [#referenz]

Weil `/dl` nicht in der generierten API-Referenz steht, finden Sie alle Angaben zum Endpunkt hier.

### Anfrage [#anfrage]

| Teil | Wert |
| --- | --- |
| Methode | `GET` |
| Adresse | `https://hub.webmetic.de/dl` |
| Header `Authorization` | Der Data-Layer-Schlüssel, ohne `Bearer` |
| Header `X-Data-Source` | Die öffentliche IP-Adresse des Besuchs, IPv4 ohne `::ffff:`. Ohne den Header gilt die Adresse, von der die Anfrage kommt |

### Antwort [#antwort]

| Fall | Status | Body |
| --- | --- | --- |
| Unternehmen erkannt | `200` | `{"cid": "41ea486a9c95", "cn": "Bergquell Mineralbrunnen GmbH"}` |
| Unternehmen ohne Namen | `200` | `{"cid": "41ea486a9c95", "cn": null}` |
| Kein Unternehmen | `200` | `null` |

### Fehler [#fehler]

Fehler am Data Layer haben einen kürzeren Body als die Endpunkte der API. `detail` ist hier ein Text und kein Objekt mit `error` und `message`, zum Beispiel `{"detail": "DATA_LAYER_KEY_MISSING"}`. Prüfen Sie bei `/dl` deshalb `detail` als Zeichenkette.

| Status | `detail` | Ursache | Was Sie tun |
| --- | --- | --- | --- |
| 403 | `DATA_LAYER_KEY_MISSING` | Die Anfrage hat keinen Header `Authorization` | Schicken Sie den Schlüssel im Header `Authorization` |
| 403 | `DATA_LAYER_KEY_INVALID` | Das Format stimmt nicht, zum Beispiel wegen `Bearer` davor oder eines Tippfehlers | Schicken Sie den Schlüssel unverändert |
| 403 | `DATA_LAYER_KEY_NOT_FOUND` | Kein Konto hat diesen Data-Layer-Schlüssel, zum Beispiel nach **Neu generieren** oder mit dem Schlüssel aus der Karte **Visitor Intelligence** | Kopieren Sie den aktuellen Schlüssel aus der Karte **Data Layer** |
| 405 | `Method Not Allowed` | Die Anfrage nutzt eine andere Methode als `GET` | Schicken Sie die Anfrage mit `GET` |
| 500 | `DATA_LAYER_KEY_DATABASE_ERROR` | Webmetic konnte den Schlüssel gerade nicht prüfen | Versuchen Sie es später erneut. Bleibt der Fehler, schreiben Sie dem [Support](https://webmetic.de/docs/konto/support) |

Die Fehler der API stehen unter [Fehler](https://webmetic.de/docs/api/fehler).

## Datenschutz [#datenschutz]

Auf welcher Rechtsgrundlage Sie die IP-Adressen Ihrer Besuche an Webmetic senden, klären Sie mit Ihrer Datenschutzberatung.

## Nächste Schritte [#nächste-schritte]

- [Matomo-Plugin](https://webmetic.de/docs/integrationen/matomo-plugin): Erkannte Unternehmen mit demselben Schlüssel direkt in Matomo sehen.
- [Authentifizierung](https://webmetic.de/docs/api/authentifizierung): Die drei API-Schlüssel und wofür jeder gilt.
- [Company](https://webmetic.de/docs/api/datenmodell/company): Alle Felder eines Unternehmens. `cid` heißt dort `company_id`.