Markdown (Eisvogel)

itknewsletteractivecampaign-anwenderdokumentation.md

---
title: "ItkNewsletterActiveCampaign"
subtitle: "Anwenderdokumentation"
author: ["André Fischer"]
date: "30-03-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "ItkNewsletterActiveCampaign"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Zweck

Du nutzt **ActiveCampaign** fürs E-Mail-Marketing, willst aber die **Anmeldung im Shopware-Look** mit **Double-Opt-In** und ggf. **mehreren Listen** behalten. Genau dafür ist dieses Plugin: Es hängt sich in Shopwares Newsletter-Flow ein, sammelt Zustimmungen sauber und spricht mit der **AC API v3**, ohne Vor- und Nachnamen zu übertragen – nur die **E-Mail**, soweit für Listen und Tags nötig.

Das Plugin verbindet Shopwares **Newsletter mit Double-Opt-In (DOI)** mit **ActiveCampaign (AC)**. Merkmale:

- **Mehrere Listen** pro Shop (JSON-Konfiguration mit Keys, Labels, AC-Listen-IDs)
- **Eine DOI-E-Mail** pro Anmeldevorgang (auch bei mehreren neu gewählten Listen)
- **Synchronisation nach DOI-Bestätigung** (erst dann werden Kontakte in AC auf den Listen „subscribed“)
- **Sofortige Abmeldung** in AC bei Entfernen einer Liste vor der Bestätigung
- **Zweite Checkbox** für App-/Web-Tracking-Zustimmung → setzt konfigurierbare **Contact-Tags** in AC nach DOI
- **Kundenkonto:** Seite `/account/newsletter-lists` zum Verwalten sichtbarer Listen, DOI erneut senden
- **Webhook** von AC zurück in Shopware bei Abmeldungen
- **Kategoriebezug:** Pro Kategorie kann über ein Custom Field nur **eine** Liste angeboten werden

**Datenschutz:** Es werden **keine** Vor-/Nachnamen an ActiveCampaign übermittelt – nur die **E-Mail-Adresse** für Listen und Tags.

---

## Diagramm: Von der Anmeldung bis ActiveCampaign

```mermaid
flowchart TD
  A[Anmeldung im Shop] --> B[DOI E-Mail]
  B --> C[Klick Bestaetigungslink]
  C --> D[Synchronisation zu AC Listen]
  D --> E[Kontakt subscribed]
```

# Konfiguration (Admin)

Pfad: **Erweiterungen → Meine Erweiterungen** → **Newsletter ActiveCampaign** → **Konfiguration** (pro Sales Channel).

## ActiveCampaign API

| Feld | Bedeutung |
|------|-----------|
| **Basis-URL** | z. B. `https://xxx.api-us1.com` *WICHTIG*: ohne Slash am Ende |
| **API-Token** | Aus dem AC-Admin (Entwickler / API) |
| **Webhook-Geheimnis** | Frei wählbar; muss in der Webhook-URL als **?secret=…** **oder** als Header **X-Itk-Newsletter-Webhook-Secret** übergeben werden |
| **Tracking-Tag Name** | Wird nach DOI gesetzt, wenn die **zweite** Zustimmungs-Checkbox aktiv war (exakter Tag-Name oder numerische Tag-ID in AC) |
| **No-Tracking-Tag Name** | Wenn zweite Checkbox **nicht** aktiv; Tracking-Tag wird entfernt und dieser Tag gesetzt (wenn konfiguriert) |

## Newsletter-Listen (JSON)

Array von Objekten mit mindestens:

- **key** – interner eindeutiger Schlüssel
- **label** – Anzeigename (kann als Textbaustein-Key übersetzt werden)
- **acListId** – Listen-ID in ActiveCampaign

Optional:

- **templateId** – UUID eines **Shopware**-E-Mail-Templates für DOI, **nur** wenn sich der Kunde **allein** für **diese eine** Liste anmeldet
- **redirectUrl** – nach DOI-Bestätigung (wird in Session gelegt und von Redirect-Subscriber ausgewertet)
- **hidden** – **1** / **true**: Liste auf Account-Seite und im CMS-Formular ausblenden (z. B. rein technische Listen)

**Validierung:** JSON muss syntaktisch korrekt sein – sonst werden keine Listen geladen.

---

# Ablauf für Kund:innen

1. **Anmeldung** (CMS-Formular, Footer, etc.): E-Mail + gewünschte Listen (+ optionale Tracking-Checkbox).
2. Shopware versendet **eine** DOI-Mail.
3. Nach Klick auf den Bestätigungslink: Plugin trägt den Kontakt in AC auf den gewählten Listen ein, pflegt Custom Fields am `newsletter_recipient`, setzt Tags, schreibt Audit-Log.
4. **Weiterleitung:** Wenn eine **redirectUrl** in der Konfiguration der betroffenen Liste gesetzt ist, kann der Kunde dorthin geleitet werden. Ohne eigene URL landet er je nach Kontext typischerweise wieder auf der Newsletter-/Account-Seite oder auf einer Standardseite des Shops.

---

# Kundenkonto

| URL | Funktion |
|-----|----------|
| **GET /account/newsletter-lists** | Übersicht, Toggle für sichtbare Listen, Status (aktiv / DOI ausstehend) |
| **POST /account/newsletter-lists** | Speichern der Auswahl |
| **POST /account/newsletter-lists/resend-doi** | Bestätigungsmail erneut senden |
| **GET /account/newsletter-lists-widget** | Fragment für die Profilseite (Sidebar) |

Der Link „Newsletter“ in der Account-Navigation erscheint nur, wenn **mindestens eine sichtbare Liste** existiert (Twig/Subscriber im Plugin).

---

# Webhook (ActiveCampaign → Shopware)

- **URL:** **POST https://<shop-domain>/itk-ac/newsletter/unsubscribe-webhook?secret=<euer-secret>**
- **Absicherung:** Secret muss mit der Plugin-Konfiguration übereinstimmen (Query oder Header).
- **Ohne Secret in der Config:** Antwort `503` `webhook_not_configured`.

In ActiveCampaign einen Automation/Webhook-Trigger konfigurieren, der bei Listen-Abmeldung die E-Mail (und idealerweise die Listen-ID) mitsendet.

---

# Kategorie-Feld

Custom Field an der **Kategorie** (Migration legt Set an): `itk_nl_category_list_id` (Auswahlfeld). Wert `__none__` oder leer = alle Listen im Formular; sonst nur die gewählte Liste (Key).

---

# CLI

| Befehl | Zweck |
|--------|--------|
| **php bin/console itk:ac:contact-tags <email>** | [Debugging] Zeigt alle Contact-Tags eines Kontakts in AC (Debug); Option `--sales-channel-id` für kanalspezifische API-Config |

---

# Logs

- **Audit-Log (CSV-Format):** `var/log/itk_newsletter_doi.log` – DOI, Account-Änderungen, Webhook-Events (über **NewsletterDoiConsentLogService**)
- **Weitere Fehler:** Shopware-Log nach Präfixen filtern (z. B. **[itk-ac]** je nach Implementierung)

---

# Typische Probleme

- **Nichts in AC nach Anmeldung:** Normal, solange DOI nicht bestätigt – erst **nach** Klick auf den Link.
- **403 Webhook:** Secret falsch oder Leerzeichen.
- **503 Webhook:** Secret in Shopware nicht gesetzt.
- **Falsche Liste in AC:** **acListId** oder Key-Zuordnung prüfen.
- **Tags fehlen:** Exakter Tag-Name in AC; zweite Checkbox im Formular wirklich aktiv?

---

# FAQ

**Warum sehe ich den Kontakt in AC erst nach dem DOI-Klick?**  
So ist der Ablauf definiert: vorher nur in Shopware, danach Listen-Status in AC.

**Kann ein Kunde nur eine Liste wählen?**  
Im Standard-Formular kommen mehrere Checkboxen; in **Kategorien** kann das Custom Field nur **eine** Liste pro Kategorie erzwingen – praktisch für thematische Landingpages.

**Webhook geht nicht:** Secret in AC und in Shopware identisch? HTTPS? Firewall?