|
| 1 | +--- |
| 2 | +title: KickImportInstagram Plugin |
| 3 | +description: Dokumentation zum Joomla Scheduler-Plugin „KickImportInstagram“ |
| 4 | +--- |
| 5 | + |
| 6 | +# KickImportInstagram Plugin |
| 7 | + |
| 8 | +Das `kickimportinstagram` Task-Plugin importiert Instagram-Beiträge automatisch als Joomla-Artikel. Es eignet sich besonders für redaktionelle Seiten, die regelmäßig Inhalte von einem Instagram-Business- oder Creator-Konto übernehmen und dabei Vorschaubilder oder Videos nutzen möchten. |
| 9 | + |
| 10 | +## Voraussetzungen und Installation |
| 11 | + |
| 12 | +- Joomla 4.x installieren. |
| 13 | +- Das Plugin unter `src/structure/plugins/task/kickimportinstagram` bereitstellen und per Installer oder manuell aktivieren. |
| 14 | +- Den Scheduler (Komponente `com_scheduler`) konfigurieren, damit der Task regelmäßig ausgeführt wird. |
| 15 | + |
| 16 | +Die Installation erfolgt wie bei allen Joomla-Erweiterungen über den Extension Manager (`Erweiterungen > Installieren`). Nach der Installation sollte das Plugin unter `System > Plugins > task – KickImportInstagram` aktiviert sein. |
| 17 | + |
| 18 | +## Plugin-Parametrisierung |
| 19 | + |
| 20 | +Das Plugin bietet die folgenden Parameter im Task-Formular (`import.xml`): |
| 21 | + |
| 22 | +| Feldname | Beschreibung | |
| 23 | +| --- | --- | |
| 24 | +| `instagram_access_token` | gültiger **long-lived** Access Token für die Instagram Graph API. Wird automatisch erneuert, sobald das Ablaufdatum näher rückt. | |
| 25 | +| `instagram_access_token_expires` | read-only Anzeige des aktuellen Ablaufdatums. Wird vom Plugin aktualisiert und in der Aufgaben-Tabelle gespeichert. | |
| 26 | +| `instagram_user_id` | ID des Instagram-Kontos, dessen Beiträge importiert werden sollen. | |
| 27 | +| `limit` | maximale Anzahl Posts pro Lauf (1–50). | |
| 28 | +| `user_id` | Joomla-Benutzer, dem die importierten Artikel zugeordnet werden. | |
| 29 | +| `image_folder` | Ordner innerhalb von `images/`, in den Medien gespeichert werden. | |
| 30 | +| `image_field` | Zielbild-Feld für normale Bildbeiträge (`image_intro` oder `image_fulltext`). | |
| 31 | +| `video_field` | Zielbild-Feld für Instagram-Videos. | |
| 32 | +| `video_thumbnail_field` | Zielbild-Feld für das Thumbnail von Instagram-Videos. | |
| 33 | +| `toCatid` | Kategorie, in die die Artikel einsortiert werden. | |
| 34 | +| `overwrite` | steuert, ob vorhandene Artikel mit derselben Alias/Catid überschrieben werden. | |
| 35 | +| `urlb`, `urlc` usw. | Platzhalter-URLs, die optional mit zusätzlichen Links befüllt werden können. | |
| 36 | +| `caching` & `cachetime` | steuern das Zwischenspeichern der Instagram-API-Antworten. | |
| 37 | + |
| 38 | +## Token-Management und Speicherung |
| 39 | + |
| 40 | +Das Plugin erneuert einen long-lived Access Token automatisch mittels der Aktion `refresh_access_token`, wenn dessen Ablauf innerhalb von drei Tagen liegt. Der neue Token sowie das neue Ablaufdatum werden direkt in der `#__extensions`-Tabelle (`task`-Plugin-Eintrag) gespeichert, so dass auch kommende Scheduler-Läufe sofort den aktualisierten Wert nutzen. Die Anzeige `instagram_access_token_expires` wird bei jedem Speichern aktualisiert. |
| 41 | + |
| 42 | +## Importverhalten |
| 43 | + |
| 44 | +- Die API-Abfrage holt die Felder `id, caption, media_type, media_url, permalink, timestamp, thumbnail_url`. |
| 45 | +- Jeder Post wird anhand seines Alias (Instagram-ID) und der Zielkategorie geladen; ohne aktiviertem Overwrite werden vorhandene Artikel übersprungen. |
| 46 | +- Texte werden mit `nl2br` formatiert und der Artikel erhält title/alias/state/created-publish-Daten basierend auf dem Instagram-Timestamp. |
| 47 | +- Die ausgewählten Joomla-Bildfelder (`image_field`, `video_field`, `video_thumbnail_field`) werden befüllt, Videos werden optional (parametergesteuert) als MP4 in `images/{image_folder}` gespeichert. |
| 48 | +- Der Pfad zu einem gespeicherten mp4-Video landet zusätzlich in `attribs.instagram_video`, so dass Template-Overrides oder Custom Fields darauf zugreifen können. |
| 49 | + |
| 50 | +## Media Handling |
| 51 | + |
| 52 | +- Fotos: Heruntergeladen und als `image_intro` oder `image_fulltext` gespeichert, je nach Einstellung. |
| 53 | +- Videos: Mp4-Dateien (optional) und Thumbnails landen in den gewählten Slots. Video-Thumb wird bevorzugt genutzt, die mp4-Datei kann in Templates eingebettet werden. |
| 54 | +- Caching verhindert Mehrfachabfragen anhand des Request-URLs (`md5`-Key), die Gültigkeitsdauer ist durch `cachetime` steuerbar. |
| 55 | + |
| 56 | +## Fehlerbehandlung |
| 57 | + |
| 58 | +- Bei fehlenden Parametern (`instagram_user_id`, `instagram_access_token`) wird der Task abgebrochen. |
| 59 | +- API- oder Downloadfehler führen zu Log-Einträgen (`logTask`) und verhindern das Speichern. |
| 60 | +- Das Plugin loggt zusätzlich erfolgreiche Token-Erneuerungen oder fehlschlagende Refresh-Versuche. |
| 61 | + |
| 62 | +## Hinweise für Entwickler |
| 63 | + |
| 64 | +- `cacheMedia` verwendet cURL, um Dateien herunterzuladen; fehlende Ordner werden angelegt. |
| 65 | +- `persistPluginParams` aktualisiert die Plugin-Parameter (`params`) in der Datenbank via `Joomla\CMS\Table\Extension`. |
| 66 | +- Die Scheduler-Schnittstelle nutzt „TaskPluginTrait“ und wird über die Service-Provider-Datei `services/provider.php` registriert. |
| 67 | + |
| 68 | +Weitere Informationen zur Implementierung und möglichen Anpassungen finden sich direkt in `src/structure/plugins/task/kickimportinstagram/src/Extension/KickImportInstagram.php`. |
0 commit comments