TheCruiserWiki

Eine ältere Version des Dokuments wurde geladen! Beim Speichern wird eine neue Version des Dokuments mit diesem Inhalt erstellt.

<WRAP tcw-page-header>
<WRAP tcw-page-header-main>
<WRAP tcw-page-title>
====== TCB Partnerlogos ======
</WRAP>

<WRAP tcw-page-back>
[[plugins:start|← Plugins]]
</WRAP>
</WRAP>

**TCB Partnerlogos** ist eine Eigenentwicklung für TheCruiserBlog.

Das Plugin dient zur Verwaltung und Ausgabe von Partnerlogos auf TheCruiserBlog.

===== Aktueller Stand =====

^ Version ^ Status ^ Einsatz ^
| 1.0.0 | produktiv | TheCruiserBlog |

===== Zweck =====

TCB Partnerlogos stellt auf TheCruiserBlog eine zentrale Verwaltung und Ausgabe von Partnerlogos bereit.

Partner werden im WordPress-Backend verwaltet. Die Ausgabe der ausgewählten Partner erfolgt über einen eigenen Shortcode und kann dadurch an der gewünschten Stelle innerhalb von TheCruiserBlog eingebunden werden.

Ziel des Plugins ist es, die Verwaltung der Partner von der eigentlichen Seitengestaltung zu trennen und die Partnerlogos zentral pflegen zu können.

===== Funktionsumfang =====

Version 1.0.0 unterstützt:

* Verwaltung mehrerer Partner
  * Partnername und Partnerlogo
  * optionale Ziel-URL
  * optionaler Kurztext
  * individuelles Aktivieren und Deaktivieren von Partnern
  * Priorität von 1 bis 10
  * prioritätsgewichtete Zufallsauswahl
  * optionale Sponsored-Kennzeichnung
  * interne Notizen zu einem Partner
  * konfigurierbare Ausgabe über einen Shortcode
  * optionale Anzeige von Partnername und Kurztext
  * responsive Darstellung der Partnerlogos
  * Unterstützung mehrerer Shortcode-Instanzen auf einer Seite
  * Erfassung von Einblendungen und Klicks
  * automatische Berechnung der Klickrate (CTR)
  * Zurücksetzen der Statistik für einzelne Partner
  * gemeinsames Zurücksetzen aller Statistikwerte
  * REST-basierte dynamische Partnerauswahl
  * administrative Direktänderung von Aktiv-Status und Priorität

Für die Frontend-Ausgabe werden nur aktive Partner mit vorhandenem Partnernamen und Partnerlogo berücksichtigt.

Die Auswahl der Partner erfolgt zufällig. Die hinterlegte Priorität beeinflusst dabei die Auswahlwahrscheinlichkeit, nicht jedoch die Position eines Logos innerhalb der Ausgabe.

===== Bedienung =====

Die Verwaltung erfolgt im WordPress-Backend über den Menüpunkt:

**TCB Partnerlogos**

Für jeden Partner können folgende Angaben hinterlegt werden:

Neu angelegte Partner sind zunächst inaktiv.

Ein Partner kann nur aktiviert werden, wenn ein Partnername und ein Partnerlogo vorhanden sind.

Wird das Logo eines bereits aktiven Partners entfernt, bleibt der Partner intern aktiv, wird jedoch nicht mehr im Frontend ausgegeben. Sobald wieder ein Logo hinterlegt ist, kann der Partner erneut an der Auswahl teilnehmen.

===== Einbindung =====

Die Ausgabe von TCB Partnerlogos erfolgt über den Shortcode:

<code>
[tcb_partnerlogos]
</code>

Ohne weitere Attribute werden standardmäßig maximal vier Partnerlogos angezeigt.

Für die individuelle Konfiguration stehen folgende Shortcode-Attribute zur Verfügung:

Beispiel:

<code>
[tcb_partnerlogos anzahl="6" hoehe="120" abstand="20" name="ja" text="nein"]
</code>

Dieses Beispiel zeigt maximal sechs Partnerlogos mit einer maximalen Logohöhe von 120 Pixeln und einem Abstand von 20 Pixeln. Der Partnername wird angezeigt, der Kurztext nicht.

Mehrere Instanzen des Shortcodes können unabhängig voneinander auf derselben Seite verwendet werden.

===== Zufallsauswahl und Priorität =====

Die im Frontend angezeigten Partner werden bei jedem Aufruf zufällig aus den verfügbaren aktiven Partnern ausgewählt.

Die hinterlegte Priorität von **1 bis 10** dient dabei als Gewichtung. Eine höhere Priorität erhöht die Wahrscheinlichkeit, dass ein Partner für die Ausgabe ausgewählt wird.

Ein Partner mit Priorität 10 besitzt beispielsweise die doppelte Auswahlchance gegenüber einem Partner mit Priorität 5.

Die Priorität beeinflusst ausschließlich die Wahrscheinlichkeit der Auswahl. Sie bestimmt nicht die Position des Partnerlogos innerhalb der Ausgabe.

Innerhalb einer einzelnen Shortcode-Ausgabe wird jeder Partner höchstens einmal angezeigt. Nach der gewichteten Auswahl wird auch die Reihenfolge der ausgewählten Partner zufällig bestimmt.

Stehen weniger geeignete Partner zur Verfügung als über das Shortcode-Attribut ''anzahl'' angefordert wurden, werden alle verfügbaren Partner angezeigt.

Als geeignet gelten aktive Partner mit vorhandenem Partnernamen und Partnerlogo.

===== Statistik =====

TCB Partnerlogos führt für jeden Partner eine interne Nutzungsstatistik.

Erfasst werden:

* **Einblendungen** – wie häufig ein Partnerlogo für die Frontend-Ausgabe ausgewählt wurde
  * **Klicks** – wie häufig auf ein verlinktes Partnerlogo geklickt wurde
  * **Klickrate (CTR)** – prozentuales Verhältnis zwischen Klicks und Einblendungen
  * **Statistik seit** – Zeitpunkt, seit dem die aktuellen Statistikwerte erfasst werden

Die Klickrate wird dynamisch aus Einblendungen und Klicks berechnet und nicht separat gespeichert.

Die Statistik kann für einen einzelnen Partner oder für alle Partner gemeinsam zurückgesetzt werden.

Beim Zurücksetzen werden Einblendungen und Klicks auf 0 gesetzt und der Zeitpunkt **Statistik seit** neu festgelegt.

Die Statistik dient ausschließlich als interne Nutzungsübersicht. Sie verwendet keine Besucheridentifikation, keine Cookies und kein externes Tracking.

Es findet keine Erkennung oder Filterung von Bots statt. Die Statistikwerte sind daher als interne Orientierungswerte und nicht als manipulationssichere Reichweiten- oder Abrechnungsstatistik zu verstehen.

===== Darstellung =====

Die Darstellung von TCB Partnerlogos ist für die Einbindung in das Erscheinungsbild von TheCruiserBlog ausgelegt.

Kennzeichnend sind:

* responsive Darstellung der Partnerlogos
  * flexible Anordnung der Logos über Flexbox
  * automatischer Zeilenumbruch bei begrenzter verfügbarer Breite
  * einstellbare Logohöhe und Abstände über den Shortcode
  * optionale Anzeige von Partnername und Kurztext
  * Hover-Effekt für die Partnerlogos
  * Berücksichtigung von ''prefers-reduced-motion'' für eine reduzierte Darstellung von Bewegungs- und Animationseffekten

Für die Frontend-Darstellung wird eine eigene CSS-Struktur verwendet. Externe CSS-Frameworks werden nicht benötigt.

===== Technische Umsetzung =====

TCB Partnerlogos 1.0.0 ist modular und objektorientiert als eigenständiges WordPress-Plugin aufgebaut.

Die Partner werden als interner, nicht öffentlicher Custom Post Type verwaltet.

Partnerdaten und Statistikwerte werden über WordPress-Metadaten gespeichert.

Die Frontend-Ausgabe erfolgt dynamisch über die WordPress REST API. Der Shortcode erzeugt zunächst den benötigten Ausgabebereich. Anschließend fordert JavaScript die für die jeweilige Ausgabe ausgewählten Partner vom Plugin an.

Dadurch wird verhindert, dass ein Seiten-Cache eine einmal erzeugte Zufallsauswahl dauerhaft zwischenspeichert und dadurch immer dieselben Partnerlogos angezeigt werden.

Für die REST-Kommunikation verwendet das Plugin den Namespace:

<code>
/wp-json/tcb-partnerlogos/v1/
</code>

Die öffentliche REST API liefert ausschließlich die für die Frontend-Ausgabe benötigten Daten. Interne Notizen, Prioritäten, Statistikwerte und andere Backend-Daten werden nicht an das Frontend übertragen.

Klicks auf Partnerlogos werden asynchron an das Plugin gemeldet. Das Öffnen der hinterlegten Ziel-URL ist dabei nicht vom Erfolg der Statistikübertragung abhängig.

Das Frontend verwendet Vanilla JavaScript ohne jQuery oder andere externe JavaScript-Bibliotheken.

===== Plugin-Struktur =====

TCB Partnerlogos 1.0.0 ist modular aufgebaut.

<code>
tcb-partnerlogos/
├── TCB_Partnerlogos.php
├── README.md
│
├── includes/
│   ├── Activator.php
│   ├── Admin.php
│   ├── Partner.php
│   ├── Plugin.php
│   ├── RestApi.php
│   ├── Shortcode.php
│   └── Statistics.php
│
└── assets/
    ├── css/
    │   └── partnerlogos.css
    │
    └── js/
        ├── admin-partnerlogos.js
        └── partnerlogos.js
</code>

Die einzelnen Komponenten übernehmen klar getrennte Aufgaben:

* ''TCB_Partnerlogos.php'' – Einstiegspunkt des Plugins, Definition der Konstanten, Autoloading und Initialisierung
  * ''Plugin.php'' – zentrale Koordination und Registrierung der Plugin-Komponenten
  * ''Partner.php'' – Partnerdaten, Custom Post Type, Metadaten und fachliche Regeln der Partnerverwaltung
  * ''Statistics.php'' – Verwaltung und Berechnung der Statistikwerte
  * ''RestApi.php'' – REST-Endpunkte für Frontend-Auswahl, Klickerfassung und administrative Änderungen
  * ''Shortcode.php'' – Registrierung, Validierung und Ausgabe des Shortcodes
  * ''Admin.php'' – Backend-Menüs, Partnerübersicht, Statistikseite, Info-Seite und administrative Aktionen
  * ''Activator.php'' – Aufgaben bei der Aktivierung des Plugins
  * ''partnerlogos.css'' – strukturelle Gestaltung der Frontend-Ausgabe
  * ''partnerlogos.js'' – Laden und Darstellen der Partnerlogos sowie Übermittlung von Klicks
  * ''admin-partnerlogos.js'' – direkte administrative Änderungen von Aktiv-Status und Priorität in der Partnerübersicht

===== Sicherheit und Datenschutz =====

TCB Partnerlogos ist für die interne Verwaltung durch Administratoren von TheCruiserBlog vorgesehen.

Administrative Funktionen sind durch die WordPress-Berechtigung ''manage_options'' geschützt. Schreibende administrative Aktionen verwenden zusätzlich WordPress-Nonces zum Schutz vor unberechtigten Anfragen.

Die öffentlichen REST-Endpunkte sind auf die für die Frontend-Ausgabe und Klickerfassung erforderlichen Funktionen beschränkt. Übermittelte Werte werden serverseitig geprüft und validiert.

Bei der Klickerfassung wird ausschließlich die interne Partner-ID an das Plugin übermittelt. Die hinterlegte Ziel-URL wird serverseitig aus den gespeicherten Partnerdaten ermittelt.

Partnerlinks werden in einem neuen Browser-Tab geöffnet.

Für die Links gelten folgende Attribute:

* normale Partnerlinks: ''rel="noopener"''
  * als Sponsored gekennzeichnete Partnerlinks: ''rel="noopener sponsored"''

Das Plugin verwendet:

* keine Cookies
  * keine Besucherkennungen
  * keine externen Tracking-Dienste
  * keine personenbezogenen Besucherprofile

Die interne Statistik erfasst ausschließlich aggregierte Einblendungen und Klicks der Partnerlogos.

===== Datenhaltung und Löschen =====

Das Deaktivieren eines Partners löscht keine Daten. Partnerdaten und Statistikwerte bleiben vollständig erhalten und stehen nach einer späteren erneuten Aktivierung weiterhin zur Verfügung.

Wird ein Partner über WordPress in den Papierkorb verschoben, bleiben seine Daten und bisherigen Statistikwerte ebenfalls erhalten. Währenddessen wird der Partner nicht für die Frontend-Ausgabe berücksichtigt.

Nach dem Wiederherstellen aus dem Papierkorb bleiben der vorherige Aktiv-Status und die Statistik erhalten. Ist der Partner aktiv und besitzt ein gültiges Partnerlogo, kann er wieder an der Frontend-Auswahl teilnehmen.

Erst beim endgültigen Löschen eines Partners werden dessen Partner- und Statistikdaten zusammen mit dem zugehörigen WordPress-Datensatz dauerhaft entfernt.

Das Deaktivieren oder Löschen des Plugins **TCB Partnerlogos** selbst entfernt die angelegten Partner und deren Statistikdaten nicht automatisch.

Version 1.0.0 besitzt bewusst keine automatische Deinstallationsroutine zum Löschen sämtlicher Plugin-Daten. Dadurch bleiben die Daten auch bei einer vorübergehenden Deaktivierung oder Neuinstallation des Plugins erhalten.

===== Installation =====

TCB Partnerlogos kann als eigenständiges WordPress-Plugin installiert werden.

Die Installation erfolgt über:

**WordPress → Plugins → Plugin hinzufügen → Plugin hochladen**

Nach der Installation wird das Plugin aktiviert.

Die Partnerverwaltung steht anschließend im WordPress-Backend über **TCB Partnerlogos** zur Verfügung.

Die Frontend-Ausgabe wird über den Shortcode

<code>
[tcb_partnerlogos]
</code>

an der gewünschten Position eingebunden.

Das aktuelle Installationspaket kann direkt heruntergeladen werden:

* {{:plugins:tcb-partnerlogos:tcb_partnerlogos_v1.0.0_installation.zip|TCB Partnerlogos 1.0.0 – Installationspaket herunterladen}}

===== Versionshistorie =====

^ Version ^ Datum ^ Änderungen ^
| 1.0.0 | 15.09.2026 | Erste produktive Version mit Partnerverwaltung, prioritätsgewichteter Zufallsauswahl, konfigurierbarer Shortcode-Ausgabe, Sponsored-Kennzeichnung, REST-basierter Frontend-Ausgabe sowie interner Einblendungs-, Klick- und CTR-Statistik |

<WRAP tcw-to-top>
[[#plugins|↑]]
</WRAP>

Zusammenfassung