Facebook Conversions API Script: Reusable Event Sender with Test Suite

Session Date: 2025-12-28
Project: AnalyticsBot - Multi-provider Analytics Integration Platform
Focus: Create reusable Facebook Conversions API event sender with test suite
Session Type: Implementation

Executive Summary

Successfully implemented a comprehensive Facebook Conversions API event sender script (fb-event.sh) with full Doppler secrets integration, SHA256 user data hashing, and support for multiple pixels. The script supports all standard Facebook event types (PageView, Lead, Purchase, Contact, ViewContent, AddToCart, CompleteRegistration) with test mode capability for sandbox testing.

Created a companion test suite (test-fb-events.sh) that validates all script functionality, achieving 10/10 tests passing (100%). Both scripts integrate seamlessly with existing AnalyticsBot infrastructure and Doppler secrets management.

Key Metrics:

Metric	Value
Scripts Created	2
Total Lines of Code	~370
Event Types Supported	7+ standard + custom
Pixels Configured	6
Tests Passing	10/10 (100%)
Test Events Sent	16

Problem Statement

The project needed a reliable way to:

Send server-side events to Facebook Conversions API for multiple pixels
Securely manage Meta access tokens and Pixel IDs via Doppler
Hash user data (email, phone, names) per Facebook requirements
Test events without affecting production data
Validate the implementation with automated tests

Previous State: Manual curl commands with hardcoded credentials and no standardized approach.

Implementation Details

Script 1: fb-event.sh

File: AnalyticsBot/scripts/fb-event.sh (~230 lines)

Key Components

1. Doppler Integration for Secrets

PIXEL_ID=$(doppler secrets get "$PIXEL_NAME" --plain -p "$DOPPLER_PROJECT" -c "$DOPPLER_CONFIG")
ACCESS_TOKEN=$(doppler secrets get "META_ACCESS_TOKEN" --plain -p "$DOPPLER_PROJECT" -c "$DOPPLER_CONFIG")

2. SHA256 User Data Hashing

hash_value() {
    echo -n "$1" | tr '[:upper:]' '[:lower:]' | shasum -a 256 | cut -d' ' -f1
}

[[ -n "$EMAIL" ]] && USER_DATA="$USER_DATA, \"em\": [\"$(hash_value "$EMAIL")\"]"

3. Multi-Pixel Support

declare -A PIXELS=(
    ["INTEGRITY_PIXEL"]="integrity-studio:dev"
    ["FB_PIXEL_ID"]="integrity-studio:dev"
    ["ALEDLIE_PIXEL"]="integrity-studio:dev"
    ["LEORA_PIXEL_ID"]="integrity-studio:dev"
    ["SITEREADER_PIXEL"]="integrity-studio:dev"
    ["SOUND_SIGHT_PIXEL_ID"]="integrity-studio:dev"
)

4. Test Mode Support

TEST_EVENT=""
if [[ -n "$TEST_MODE" ]]; then
    TEST_EVENT=", \"test_event_code\": \"$TEST_MODE\""
fi

Supported Event Types

PageView - Page views
Lead - Lead form submissions
Purchase - Transactions with value
Contact - Contact form submissions
ViewContent - Content views
AddToCart - Cart additions with value
CompleteRegistration - User registrations
Any custom event name

Usage Examples

./fb-event.sh --event PageView

./fb-event.sh --event Lead --email user@example.com --fn John --ln Doe

./fb-event.sh --event Purchase --value 149.99 --email buyer@example.com

./fb-event.sh --pixel ALEDLIE_PIXEL --event PageView

./fb-event.sh --event Lead --email test@test.com --test TEST12345

./fb-event.sh --list-pixels

Script 2: test-fb-events.sh

File: AnalyticsBot/scripts/test-fb-events.sh (~140 lines)

Test Cases

Test #	Name	Description
1	Script exists	Validates fb-event.sh exists and is executable
2	Help command	Tests –help displays correctly
3	List pixels	Tests –list-pixels functionality
4	PageView event	Sends PageView in test mode
5	Lead event	Sends Lead with user data
6	Purchase event	Sends Purchase with value
7	Contact event	Sends Contact event
8	ViewContent event	Sends ViewContent event
9	AddToCart event	Sends AddToCart with value
10	CompleteRegistration	Sends registration event

Testing and Verification

Test Results

$ ./test-fb-events.sh
========================================
Facebook Conversions API Test Suite
========================================
Testing: /Users/alyshialedlie/code/ISPublicSites/AnalyticsBot/scripts/fb-event.sh
Pixel: INTEGRITY_PIXEL (default)
Mode: Test events (won't affect production)

TEST: Script exists and is executable
✓ PASS: fb-event.sh exists and is executable

TEST: Help command
✓ PASS: Help displays correctly

TEST: List pixels command
✓ PASS: List pixels works

TEST: PageView event (test mode)
✓ PASS: PageView event sent successfully

TEST: Lead event with user data (test mode)
✓ PASS: Lead event with user data sent successfully

TEST: Purchase event with value (test mode)
✓ PASS: Purchase event with value sent successfully

TEST: Contact event (test mode)
✓ PASS: Contact event sent successfully

TEST: ViewContent event (test mode)
✓ PASS: ViewContent event sent successfully

TEST: AddToCart event (test mode)
✓ PASS: AddToCart event sent successfully

TEST: CompleteRegistration event (test mode)
✓ PASS: CompleteRegistration event sent successfully

========================================
Test Summary
========================================
Passed: 10
Failed: 0
Total: 10

All tests passed!

Manual Event Verification

Events sent during session to INTEGRITY_PIXEL (25629020546684786):

Event	URL	Trace ID	Status
PageView	integritystudio.ai	AIINEEuqMufYEu7yc7vYB6y	✅
Lead	integritystudio.ai	Ag1azaX7WaDfcLsoVOkoToB	✅
Lead	integritystudio.ai	AqKEQhS5H5Xfmfu7FcKjest	✅
Purchase ($199.99)	integritystudio.ai	AGHiVDm9_Yyq-JwbssTmS9L	✅
Contact	integritystudio.ai/contact	AObn93E1mDyh8vHQuzP7ulf	✅
Contact (test)	integritystudio.ai/contact	A6UfNgO8wwSOLTmjYMgUCYe	✅
ViewContent	integritystudio.ai/services	AXIPOD9ep2AwE6QD8D95exg	✅

Key Decisions and Trade-offs

Decision 1: Bash 5 (Homebrew) vs Standard Bash

Choice: Use /opt/homebrew/bin/bash (Bash 5.3.3) Rationale: Associative arrays require Bash 4+; macOS ships with Bash 3.2 Alternative Considered: Rewrite without associative arrays Trade-off: Requires Homebrew bash installation

Decision 2: SHA256 for User Data Hashing

Choice: SHA256 with lowercase normalization Rationale: Facebook Conversions API requirement for PII Implementation: echo -n "$value" | tr '[:upper:]' '[:lower:]' | shasum -a 256

Decision 3: Doppler for Secrets Management

Choice: Integrate with existing Doppler infrastructure Rationale: Centralized secrets, no hardcoded credentials, audit trail Configuration: Project integrity-studio, config dev

Decision 4: Test Mode with test_event_code

Choice: Support --test CODE flag for sandbox testing Rationale: Test events without affecting production metrics Implementation: Adds test_event_code to API payload

Doppler Secrets Configuration

Secrets Retrieved

Secret Name	Doppler Project	Config
META_ACCESS_TOKEN	integrity-studio	dev
INTEGRITY_PIXEL	integrity-studio	dev
FB_PIXEL_ID	integrity-studio	dev
ALEDLIE_PIXEL	integrity-studio	dev
LEORA_PIXEL_ID	integrity-studio	dev
SITEREADER_PIXEL	integrity-studio	dev
SOUND_SIGHT_PIXEL_ID	integrity-studio	dev

Files Created

New Files (2)

File	Lines	Purpose
`AnalyticsBot/scripts/fb-event.sh`	~230	Reusable event sender
`AnalyticsBot/scripts/test-fb-events.sh`	~140	Automated test suite

API Reference

Facebook Conversions API Endpoint

POST https://graph.facebook.com/v21.0/{pixel_id}/events

Payload Structure

{
  "data": [{
    "event_name": "Lead",
    "event_time": 1735412345,
    "action_source": "website",
    "event_source_url": "https://integritystudio.ai/contact",
    "user_data": {
      "client_ip_address": "192.168.1.1",
      "client_user_agent": "Mozilla/5.0",
      "em": ["sha256_hashed_email"],
      "fn": ["sha256_hashed_firstname"],
      "ln": ["sha256_hashed_lastname"]
    },
    "custom_data": {
      "value": 99.99,
      "currency": "USD"
    }
  }],
  "access_token": "...",
  "test_event_code": "TEST12345"
}