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.

Embedding

📖 Complete Embedding Guide →

Quick start for embedding the plugin:

<!-- Option 1: Script Embedding (auto-sizing) -->
<script
  src="https://unpkg.com/@epurchasepower/can-action-carousel@latest/dist/production/embed-loader.js"
  data-client-id="can"
  data-campaign-code="173"
  data-theme="light"
></script>

<!-- Option 2: Direct Iframe (most reliable) -->
<iframe
  src="https://unpkg.com/@epurchasepower/can-action-carousel@latest/dist/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="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

Releasing

The plugin supports multi-environment releases to npm/unpkg with separate versions for development, staging, and production.

Release Commands

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

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

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

# View all options
pnpm run release:help

Version Strategy

• Development (@development tag): 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
• Staging (@staging tag): X.Y.Z-staging.N - For pre-production testing
  • Uses staging environment variables
• Production (@latest tag): X.Y.Z - For production use
  • Uses production environment variables

Release Process

Each release automatically:

1. Validates code (type checking, linting)
2. Builds all three environments (development, staging, production)
3. Bumps version according to selection
4. Publishes to npm with appropriate dist-tag
5. Displays unpkg CDN URLs for immediate use

Example development workflow:

# Make changes to the code
# ...

# Publish a development version
pnpm run release:development:patch

# Test using the development URL:
# https://unpkg.com/@epurchasepower/can-action-carousel@development/dist/development/iframe-embed-loader.js

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

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

Testing Releases

# Test local development build
pnpm dev

# Test published development version from unpkg
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