Boost Setup

Overview

The boost feature lets users promote events through paid Facebook and Instagram ads via the Meta Marketing API. The platform acts as an intermediary, creating campaigns, ad sets, and ads on behalf of users using a single platform-owned Meta ad account.

This guide walks through the complete Facebook/Meta configuration needed to enable the boost feature.

Step 1: Create a Facebook App

1. Go to developers.facebook.com
2. Click My Apps then Create App
3. Select Other as the use case, then Business as the app type
4. Fill in the app name (e.g. "Event Schedule Boost") and contact email
5. Once created, note the App ID and App Secret from App Settings > Basic

META_APP_ID=your_app_id
META_APP_SECRET=your_app_secret

Step 2: Meta Business & Ad Account

1. Go to business.facebook.com
2. Create a Business Account if you don't have one
3. In Business Settings > Accounts > Ad Accounts, click Add > Create a new ad account
4. Name it (e.g. "Event Schedule Boost Ads"), set the currency and timezone
5. Note the Ad Account ID (numeric, without the act_ prefix - the code adds that automatically)

META_AD_ACCOUNT_ID=your_ad_account_id

Step 3: Facebook Page

Ads require a Facebook Page as the ad's identity (the "posted by" entity).

1. Create a Facebook Page for your platform (or use an existing one)
2. Go to the Page, click About or check the URL to find the Page ID
3. In Business Settings > Accounts > Pages, add this page to your Business Account

META_PAGE_ID=your_page_id

Step 4: System User & Access Token

A System User provides a stable, long-lived token that doesn't expire when a personal account changes.

1. In Business Settings > Users > System Users, click Add
2. Name it (e.g. "Event Schedule API") and set the role to Admin
3. Click Add Assets and assign:
   • The Ad Account from Step 2 (with full control)
   • The Facebook Page from Step 3 (with full control)
4. Click Generate New Token, select the app from Step 1, and grant these permissions:
   • ads_management - create/update/delete campaigns, ad sets, ads, and creatives
   • ads_read - read campaign insights, ad status, and review feedback
   • pages_read_engagement - required for creating ads using the page's identity
   • pages_manage_ads - required for creating page post ads
5. Copy the generated token (you won't be able to see it again)

META_ACCESS_TOKEN=your_system_user_token

Step 5: Meta Pixel

1. In Events Manager (business.facebook.com/events_manager), click Connect Data Sources
2. Select Web, name the pixel (e.g. "Event Schedule Pixel")
3. Choose Conversions API as the connection method
4. Note the Pixel ID

META_PIXEL_ID=your_pixel_id

Step 6: Webhooks

The app uses webhooks to receive real-time updates when campaigns complete or ads get rejected.

1. In the Facebook App Dashboard, go to Add Product and add Webhooks
2. Select the Ad Account object type
3. Click Subscribe and configure:
   • Callback URL: https://yourdomain.com/webhooks/meta
   • Verify Token: A random string you choose (e.g. generate with openssl rand -hex 32)
4. Subscribe to these fields:
   • campaign - notifies when campaigns complete
   • ad - notifies when ads are approved or rejected
   • ad_account - notifies of account-level changes

META_WEBHOOK_VERIFY_TOKEN=your_random_verify_token

Step 7: App Review

For production use, your app needs to go through Meta's App Review process.

1. In the App Dashboard, go to App Review > Permissions and Features
2. Request approval for:
   • ads_management - required
   • ads_read - required
   • pages_read_engagement - required
   • pages_manage_ads - required
3. Provide a detailed description of how your app uses each permission, with screenshots
4. Submit for review

Step 8: Environment Variables

Here is the full set of environment variables for the boost feature:

# Required - Facebook App credentials
META_APP_ID=your_app_id
META_APP_SECRET=your_app_secret

# Required - System User access token
META_ACCESS_TOKEN=your_system_user_access_token

# Required - Ad Account (numeric ID, without act_ prefix)
META_AD_ACCOUNT_ID=your_ad_account_id

# Required - Facebook Page for ad identity
META_PAGE_ID=your_page_id

# Required - Pixel for Conversions API
META_PIXEL_ID=your_pixel_id

# Required - Webhook verification
META_WEBHOOK_VERIFY_TOKEN=your_random_verify_token

# Optional - API version (default: v21.0)
META_API_VERSION=v21.0

# Optional - Business settings
META_MARKUP_RATE=0.20          # 20% markup on ad spend (default)
META_MIN_BUDGET=10.00          # Minimum boost budget (default)
META_MAX_BUDGET=5000.00        # Maximum boost budget (default)
META_DEFAULT_CURRENCY=USD      # Default currency (default)
META_MAX_CONCURRENT_BOOSTS=3   # Max active boosts per schedule (default)

Config File

Ensure the page_id key is present in the meta config array in config/services.php:

'page_id' => env('META_PAGE_ID'),

Step 9: Scheduled Command

The boost:sync command syncs analytics every 15 minutes (already scheduled in routes/console.php). Make sure the Laravel scheduler is running:

* * * * * php artisan schedule:run