Appearance

iFrame Integration ​

Overview ​

This documentation describes how to integrate external applications into Pitcher using iFrames with bi-directional communication. The integration allows external apps to receive Pitcher canvas data and context information through window messaging.

Architecture ​

The integration consists of two main components:

  1. Pitcher Embedded App - iFrame Window Message Passer (Parent Frame) - Runs within Pitcher
  2. External Application (Child iFrame) - Your external application

Communication Flow ​

Pitcher → iFrame Window Message Passer → iFrame → External App
         ↑                          ↓
         └──────── Messages ────────┘

Implementation Guide ​

Step 1: Create Your External Application ​

Your external application needs to listen for messages from the parent frame.

Example receiver.html (View full example):

javascript
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>External App - Canvas Data Receiver</title>
</head>
<body>
    <div id="status">Waiting for canvas data...</div>
    <div id="dataContainer"></div>

    <script>
        // Listen for messages from parent frame
        window.addEventListener('message', function (event) {
            console.log('Received message:', event.data);

            if (event.data.type === 'CANVAS_DATA' && event.data.canvas) {
                const canvas = event.data.canvas;
                
                // Access canvas data
                console.log('Canvas ID:', canvas.id);
                console.log('Canvas Name:', canvas.name);
                
                // Access context data (e.g., Selected Account)
                if (canvas.context && canvas.context.SelectedAccount) {
                    const account = canvas.context.SelectedAccount;
                    console.log('Account Name:', account.Name);
                }
                
                // Update your UI
                document.getElementById('status').textContent = 'Canvas data received!';
                document.getElementById('dataContainer').innerHTML = 
                    `<pre>${JSON.stringify(canvas, null, 2)}</pre>`;
            }
        });
        
        console.log('External app ready and listening for messages...');
    </script>
</body>
</html>

Step 2: Deploy & Configure the URL of the External App in Pitcher ​

Deploy your app to a web URL that supports HTTPS and copy/paste the URL to the iFrame Window Message Passer app settings in Pitcher.

Data Structure ​

Canvas Object ​

The canvas object passed to your external app includes:

javascript
{
    "id": "canvas_uuid",
    "name": "Canvas Name",
    "type": "canvas",
    "context": {
        "SelectedAccount": {
            "Name": "Account Name",
            // ... other Salesforce fields
        },
        // ... other context objects
    },
    "metadata": {
        // ... custom metadata
    },
    // ... other canvas properties
    // Note: 'content' property is excluded for security
}

Message Format ​

All messages follow this structure:

javascript
{
    "type": "MESSAGE_TYPE",
    "body": {
        "action": "action_name",
        "data": { /* payload */ }
    }
}

Security Considerations ​

  1. Origin Validation: In production, replace '*' with specific allowed origins:

    javascript
    if (event.origin !== 'https://your-pitcher-instance.com') return;

  2. Data Filtering: The parent app filters out sensitive content before passing to external apps

  3. HTTPS Required: Always use HTTPS for external applications

  4. Authentication: Implement proper authentication between your external app and backend services

Common Use Cases ​

  1. CRM Integration: Display and update CRM data based on selected Pitcher account
  2. Analytics Dashboards: Show real-time analytics for the current canvas context
  3. External Workflows: Trigger external processes based on canvas data
  4. Data Enrichment: Display additional data from external sources

Testing ​

  1. Deploy your external app to a publicly accessible HTTPS URL
  2. Configure the app in Pitcher with the correct URL
  3. Add the app to a canvas
  4. Verify data is received correctly in browser console
  5. Test with different canvas contexts and accounts

Troubleshooting ​

No data received ​

  • Check browser console for errors
  • Verify iframe URL is correct in app configuration
  • Ensure external app is accessible (no CORS issues)
  • Check message event listener is properly set up

Data missing fields ​

  • Verify the canvas has the expected context
  • Check if fields exist in the source system (e.g., Salesforce)
  • Ensure proper field API names are used

iFrame not loading ​

  • Check Content Security Policy (CSP) headers
  • Verify HTTPS is used for external URLs
  • Check for mixed content warnings

Full Working Example ​

You can download a complete working example of an external application that receives canvas data:

This example demonstrates:

  • Full iframe setup with seamless styling
  • Canvas data extraction and filtering
  • Context data display (including SelectedAccount)
  • Proper message handling patterns
  • Visual feedback when data is received
  • Formatted display of canvas and account information

Support ​

For additional support or questions about iframe integrations in Pitcher, please contact the Pitcher development team or refer to the Pitcher JS API documentation.