Climate Action Now Web Plugin

A React-based web plugin for embedding climate action cards into any website. Built with TypeScript, Vite, and Tailwind CSS.

Documentation

• 📋 Cloudflare Migration Checklist - Step-by-step guide for migrating to Cloudflare Pages
• ⚙️ Cloudflare Setup Guide - Detailed technical setup and configuration
• 🏗️ Cloudflare DNS Architecture - How custom domains and branch routing work
• 🌐 GoDaddy DNS Quick Reference - Creating CNAME records in GoDaddy
• 📖 Embedding Guide - Complete guide for embedding the plugin
• 🔌 Parent API - JavaScript API for parent pages
• 💳 Stripe Setup - Stripe payment integration

Embedding

📖 Complete Embedding Guide →

Quick start for embedding the plugin:

<!-- Option 1: Script Embedding (auto-sizing) -->
<div id="climate-action-plugin"></div>
<script
  src="https://embed.climateactionnow.com/production/iframe-embed-loader.js"
  data-client-id="can"
  data-campaign-code="173"
  data-theme="light"
></script>

<!-- Option 2: Direct Iframe (most reliable) -->
<iframe
  src="https://embed.climateactionnow.com/production/src/embed.html?clientId=can&campaignCode=173&theme=light"
  width="100%"
  style="border: 0; height: 600px;"
  title="Climate Action Plugin"
  sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"
  allow="payment https://js.stripe.com https://m.stripe.com https://hooks.stripe.com; publickey-credentials-get https://js.stripe.com https://m.stripe.com https://hooks.stripe.com; clipboard-write"
>
</iframe>

Features

• Action Cards: Interactive climate action cards with completion tracking
• Multi-Step Flows: Petition signing, calling representatives, and learning actions
• Responsive Design: Works on desktop and mobile devices
• Theme Support: Light and dark themes
• Auto-Resize: Dynamic height adjustment (script embedding)
• Cross-Origin Safe: Bypasses browser security restrictions
• Parent API: Programmatic control of popups from parent pages

Parent API

The plugin provides a JavaScript API for parent pages to programmatically trigger popups within the embedded iframe.

API Methods

// Import the API (TypeScript/ES6)
import ClimateActionAPI from '@epurchasepower/can-action-carousel/parent-api'

// Or use the global (browser)
// The API is automatically available as window.ClimateActionAPI

// Get the iframe element
const iframe = document.getElementById('climate-action-iframe')

// Trigger a gift popup
ClimateActionAPI.showGiftPopup(iframe, {
  adName: 'gifts',
  productName: 'TreesGift', // or 'LandGift', 'CarbonReductionGift'
  value: 10,
  triggerValue: Date.now(),
  ABTestId: 'test-id', // optional
  ABGroupId: 'test-group', // optional
})

// Trigger a membership popup
ClimateActionAPI.showMembershipPopup(iframe, {
  adName: 'canMembershipAd',
  triggerValue: Date.now(),
  value: 5, // optional
})

// Trigger a Save the Planet subscription popup
ClimateActionAPI.showSaveThePlanetPopup(iframe, {
  adName: 'saveThePlanetAd',
  triggerValue: Date.now(),
  value: 3, // optional
})

// Trigger the welcome popup
ClimateActionAPI.showWelcomePopup(iframe)

Using Selectors

You can also pass a CSS selector instead of an iframe element:

ClimateActionAPI.showGiftPopup('#climate-action-iframe', {
  adName: 'gifts',
  productName: 'TreesGift',
  value: 10,
  triggerValue: Date.now(),
})

Testing the Parent API

A test page is included for development testing:

1. Start the development server:

   pnpm dev:iframe

2. Open the test page in your browser:

   http://localhost:5173/test-parent-api.html

3. Click the buttons to trigger different popup types

Low-Level postMessage API

For advanced use cases, you can send messages directly using postMessage:

const iframe = document.getElementById('climate-action-iframe')

iframe.contentWindow.postMessage(
  {
    type: 'trigger-gift-popup',
    payload: {
      adName: 'gifts',
      productName: 'TreesGift',
      value: 10,
      triggerValue: Date.now(),
    },
  },
  '*'
)

Available message types:

• trigger-gift-popup
• trigger-membership-popup
• trigger-save-planet-popup
• trigger-welcome-popup

Development

Quick Start

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Start iframe development (for embedding tests)
pnpm dev:iframe

# Build for production
pnpm build:staging    # Staging build
pnpm build:production # Production build

# Run tests
pnpm test
pnpm check-types
pnpm lint

Environment Configuration

Create .env.development from .env.example:

VITE_API_BASE_URL=http://localhost:8040
VITE_TENANT_ID=can
VITE_CAMPAIGN_CODE=173

Deploying

The plugin supports multi-environment deployments to Cloudflare Pages with separate versions for development, staging, and production.

Deployment Commands

# Development deployments (for active development and testing)
# ⚠️  IMPORTANT: Uses STAGING environment variables (staging API, test Stripe keys)
pnpm run deploy:development        # Interactive version selection
pnpm run deploy:development:patch  # Patch version (0.0.X)
pnpm run deploy:development:minor  # Minor version (0.X.0)
pnpm run deploy:development:major  # Major version (X.0.0)

# Staging deployments (for testing before production)
pnpm run deploy:staging            # Interactive version selection
pnpm run deploy:staging:patch      # Patch version with -staging suffix
pnpm run deploy:staging:minor      # Minor version with -staging suffix
pnpm run deploy:staging:major      # Major version with -staging suffix

# Production deployments (for live production use)
pnpm run deploy:production         # Interactive version selection
pnpm run deploy:production:patch   # Patch version (0.0.X)
pnpm run deploy:production:minor   # Minor version (0.X.0)
pnpm run deploy:production:major   # Major version (X.0.0)

# View all options
pnpm run deploy:help

Version Strategy

• Development: X.Y.Z-dev.N - For rapid iteration and testing
  • ⚠️ Uses STAGING environment variables (staging API, test Stripe keys, etc.)
  • This allows published development builds to be tested externally without localhost
  • URL: https://embed.climateactionnow.com/development/
• Staging: X.Y.Z-staging.N - For pre-production testing
  • Uses staging environment variables
  • URL: https://embed.climateactionnow.com/staging/
• Production: X.Y.Z - For production use
  • Uses production environment variables
  • URL: https://embed.climateactionnow.com/production/

Deployment Process

Each deployment automatically:

1. Validates code (type checking, linting)
2. Builds all three environments (development, staging, production)
3. Bumps version according to selection
4. Deploys to Cloudflare Pages
5. Displays CDN URLs for immediate use

Example development workflow:

# Make changes to the code
# ...

# Deploy a development version
pnpm run deploy:development:patch

# Test using the development URL:
# https://embed.climateactionnow.com/development/iframe-embed-loader.js

# When ready, promote to staging
pnpm run deploy:staging:patch

# After testing staging, deploy to production
pnpm run deploy:production:patch

Testing Deployments

# Test local development build
pnpm dev

# Test published development version from CDN
pnpm run test:embed:development

# Test staging version
pnpm run test:embed:staging

# Test production version
pnpm run test:embed:production

Architecture

Built with React, TypeScript, and Tailwind CSS. Key directories:

• src/components/ - React components
• src/features/ - Feature modules (actions, carousel)
• src/hooks/ - Custom React hooks
• src/services/ - API services

Contributing

1. Create a feature branch
2. Make your changes
3. Run pnpm test and pnpm check-types
4. Submit a pull request