LEG App Logo
LEG App

Meta Ads Setup (Facebook / Instagram)

Diese Anleitung beschreibt die Einrichtung der Meta Marketing API fuer die LEG-App. Die Integration ermoeglicht Awareness- und Lead-Generation-Kampagnen auf Facebook und Instagram.

Voraussetzungen

  • Meta Business Suite Account (business.facebook.com)
  • Facebook Page fuer die LEG (z.B. "LEG App" oder pro Gemeinde)
  • Zugang zum Meta Business Manager

1. Meta Business Suite einrichten

  1. Unter business.facebook.com einen Business Account erstellen (falls nicht vorhanden).
  2. Eine Facebook Page anlegen oder eine bestehende verknuepfen.
  3. Die Page-ID notieren: Page Settings > General > Page ID.

2. Meta App erstellen

  1. developers.facebook.com oeffnen.
  2. Create App > App-Typ: Business auswaehlen.
  3. App-Name: z.B. "LEG App Ads".
  4. In der App unter Add Products die Marketing API aktivieren.
  5. Die App ID und das App Secret notieren (unter Settings > Basic).

3. Berechtigungen (Permissions)

Folgende Berechtigungen werden benoetigt:

| Berechtigung | Zweck | |---|---| | ads_management | Kampagnen erstellen und verwalten | | ads_read | Kampagnen-Status und Metriken lesen | | pages_manage_ads | Anzeigen auf Pages schalten | | pages_read_engagement | Page-Engagement lesen | | leads_retrieval | Lead-Formulardaten abrufen (fuer Lead Gen) | | pages_show_list | Pages auflisten |

Lead Ads Voraussetzung

Fuer Lead-Generation-Kampagnen muss die Facebook Page die Lead Ads Terms of Service akzeptiert haben:

  1. Page Settings > Lead Ads > Terms of Service akzeptieren.
  2. Ohne diese Akzeptanz schlaegt createLeadForm() fehl.

4. Access Token generieren

Fuer Entwicklung (kurzlebig)

  1. Im Graph API Explorer die App auswaehlen.
  2. Unter "Permissions" die oben genannten Berechtigungen hinzufuegen.
  3. "Generate Access Token" klicken.
  4. Dieses Token ist nur ca. 1 Stunde gueltig.

Fuer Produktion (langlebig)

  1. Im Business Manager unter Business Settings > System Users einen System User erstellen.
  2. Dem System User die noetige Ad-Account-Berechtigung zuweisen.
  3. Unter dem System User einen Token mit den noetigten Scopes generieren.
  4. Dieses Token hat keine Ablaufzeit (solange der System User aktiv ist).

5. Ad Account ID finden

  1. Business Manager > Business Settings > Ad Accounts.
  2. Die numerische Account-ID kopieren (z.B. 123456789).
  3. In der API wird automatisch act_ vorangestellt.

6. ENV-Variablen konfigurieren

In der .env-Datei muessen folgende Variablen gesetzt werden:

META_ADS_APP_ID=deine_app_id META_ADS_APP_SECRET=dein_app_secret META_ADS_ACCESS_TOKEN=dein_access_token META_ADS_ACCOUNT_ID=123456789

Die optionale Variable META_ADS_API_VERSION ist standardmaessig v21.0.

Konfiguration pruefen

Im Admin unter /admin/advertising wird angezeigt, ob Meta Ads konfiguriert ist:

  • Gruenes Badge: "Meta Ads aktiv" - Credentials vorhanden
  • Gelbes Badge: "Meta Ads nicht konfiguriert" - Credentials fehlen

7. Kampagnentypen

Awareness-Kampagnen

  • Objective: OUTCOME_AWARENESS
  • Ziel: Maximale Reichweite in den Ziel-PLZ
  • Ad-Typ: Link-Ad (Klick fuehrt zur Landing Page)
  • Landing Page: /community/{slug} (dynamisch pro Community)

Lead-Generation-Kampagnen

  • Objective: OUTCOME_LEADS
  • Ziel: Interessenten via In-App-Formular gewinnen
  • Ad-Typ: Lead Ad mit Instant Form (Email + PLZ)
  • Lead-Sync: Automatisch alle 15 Minuten via SyncMetaLeadsJob
  • Import: Leads werden als InterestedPerson mit lead_source=meta_lead_ad gespeichert
  • Pflichtfeld: privacy_policy_url (Datenschutzerklaerung)

8. Dynamische Landing Pages

Jede Community hat automatisch eine Landing Page unter:

/community/{slug}

Beispiele:

  • /community/lupsingen
  • /community/therwil

Die URL wird im Community-Building-Wizard automatisch als Kampagnen-Link vorgeschlagen. UTM-Parameter werden unterstuetzt:

/community/lupsingen?utm_source=meta&utm_campaign=aufbau-lupsingen

Alte URLs

Die bisherigen statischen Routen werden per 301-Redirect weitergeleitet:

  • /amtsanzeiger-lupsingen -> /community/lupsingen
  • /amtsanzeiger-therwil -> /community/therwil

9. Lead-Sync

Der SyncMetaLeadsJob laeuft alle 15 Minuten (konfiguriert in ScheduleServiceProvider):

  • Holt neue Leads von allen aktiven Lead-Gen-Kampagnen
  • Dedupliziert nach Email + Kampagne
  • Erstellt InterestedPerson mit:
    • lead_source = meta_lead_ad
    • ad_campaign_id = Verknuepfung zur Kampagne
    • data_consent = true (User hat in Meta zugestimmt)
  • Verknuepft den Lead mit der CommunityGroup (via Pivot-Tabelle)
  • Aktualisiert leads_count auf der Kampagne

Manueller Sync

Im Advertising Dashboard kann ein manueller Lead-Sync pro Kampagne ausgeloest werden (User-Plus-Icon).

10. Lokales Testing

Tests verwenden Http::fake() und benoetigen keinen Live-API-Zugang:

php artisan test tests/Feature/MetaAdsServiceTest.php php artisan test tests/Feature/SyncMetaLeadsJobTest.php php artisan test tests/Feature/CommunityLandingPageTest.php php artisan test tests/Feature/Admin/AdvertisingDashboardTest.php

11. Troubleshooting

| Fehler | Ursache | Loesung | |---|---|---| | Invalid access token (Code 190) | Token abgelaufen oder ungueltig | Neues Token generieren | | Unsupported get request (Code 100) | Kampagne auf Meta geloescht | Status wird automatisch auf deleted_on_platform gesetzt | | Error validating access token | Token-Berechtigungen fehlen | Berechtigungen im Business Manager pruefen | | Terms of Service not accepted | Lead Ads ToS nicht akzeptiert | Page Settings > Lead Ads > ToS akzeptieren | | Page not associated with app | Page nicht mit App verknuepft | Business Settings > Pages > App zuweisen | | #100: Invalid parameter | Falsches Payload-Format | API-Version und Feld-Syntax pruefen |

Logs

Meta-Ads-Fehler werden im Laravel-Log protokolliert mit dem Praefix MetaAdsService:::

tail -f storage/logs/laravel.log | grep MetaAds