Handling postMessage Events from the In-App Marketplace

The Partner Fleet marketplace can send postMessage events to your application when users interact with it — most commonly when they click a button configured with a Send to page in my app destination. Your application can then handle this message to trigger appropriate actions, such as displaying modals, navigating to a page, updating states, or making API calls.

Configuration

To configure a button to send a postMessage event when clicked:

• Buttons & Actions tab: set the Default destination for an action type (Install, Uninstall, Configure, or Other) to Send to page in my app, then enter the JSON payload you want to receive.
• Permissions tab: in the No Access Fallback section, set Action to Send to page in my app for restricted accounts or users.
• Per-Listing Overrides: override the destination for a specific listing using the same Send to page in my app option.

The JSON you enter in the destination field is what your application will receive in the postMessage event's data property.

Message Listener Implementation

Basic Implementation

window.addEventListener('message', function(event) {
  // Verify the origin for security
  if (event.origin !== 'https://your-partner-fleet-domain') {
    return;
  }

  switch (event.data) {
    case 'configure_api_key':
      handleApiKeyConfiguration();
      break;
    case 'disable_integration':
      handleIntegrationDisable();
      break;
    default:
      console.log('Unhandled notification:', event.data);
  }
});

Advanced Implementation with Handlers

const notificationHandlers = {
  // Configuration Handlers
  configure_api_key: handleApiKeyConfiguration,
  update_settings: handleSettingsUpdate,

  // Status Change Handlers
  enable_integration: handleEnableIntegration,
  disable_integration: handleDisableIntegration,

  // Account Management
  upgrade_account: handleUpgradePrompt,
  verify_account: handleAccountVerification
};

window.addEventListener('message', function(event) {
  // Origin verification
  const allowedOrigins = [
    'https://your-partner-fleet-domain',
    'https://alternate-domain.com'
  ];

  if (!allowedOrigins.includes(event.origin)) {
    console.warn('Received message from unauthorized origin:', event.origin);
    return;
  }

  // Handle notification
  const handler = notificationHandlers[event.data];
  if (handler) {
    handler();
  } else {
    console.log('Unhandled notification:', event.data);
  }
});

Example Handler Implementation

Modal Handler Example

function handleApiKeyConfiguration() {
  const modal = document.createElement('div');
  modal.className = 'integration-modal';
  modal.innerHTML = `
    <div class="modal-content">
      <h2>Configure API Key</h2>
      <input type="text" id="apiKeyInput" placeholder="Enter API Key">
      <div class="button-group">
        <button id="saveApiKey">Save</button>
        <button id="closeModal">Cancel</button>
      </div>
    </div>
  `;

  // Add modal styles
  const style = document.createElement('style');
  style.textContent = `
    .integration-modal {
      position: fixed;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      background: rgba(0,0,0,0.5);
      display: flex;
      justify-content: center;
      align-items: center;
      z-index: 1000;
    }

    .modal-content {
      background: white;
      padding: 20px;
      border-radius: 5px;
      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
    }

    .button-group {
      margin-top: 15px;
      display: flex;
      justify-content: flex-end;
      gap: 10px;
    }
  `;

  document.head.appendChild(style);
  document.body.appendChild(modal);

  // Event Handlers
  document.getElementById('saveApiKey').addEventListener('click', function() {
    const apiKey = document.getElementById('apiKeyInput').value;
    saveApiKey(apiKey).then(() => {
      document.body.removeChild(modal);
    });
  });

  document.getElementById('closeModal').addEventListener('click', function() {
    document.body.removeChild(modal);
  });
}

Common Use Cases

1. Configuration Modals

Trigger an in-app modal when the user clicks a Configure button on a listing:

case 'configure_settings':
  showConfigurationModal();
  break;

2. Status Updates

Update the integration's status in your application after a successful action:

case 'update_integration_status':
  updateIntegrationStatus();
  break;

3. User Prompts

Show a confirmation dialog before proceeding with a destructive action:

case 'confirm_action':
  showConfirmationDialog();
  break;

Best Practices

Security

• Always verify message origins.
• Maintain a whitelist of allowed origins.
• Validate all received data.
• Handle sensitive data securely.

User Experience

• Provide immediate feedback for actions.
• Include loading states for async operations.
• Handle errors gracefully.
• Maintain consistent UI patterns.

Implementation

• Use separate functions for different notifications.
• Implement proper error boundaries.
• Keep handlers focused and single-purpose.
• Log unhandled notifications for debugging.

Testing

Security Testing

• Verify origin checking.
• Test with invalid origins.
• Validate data handling.

Functional Testing

• Test all notification types.
• Verify handler execution.
• Check async operations.
• Test error scenarios.

UI Testing

• Verify modal behavior.
• Test responsive design.
• Check loading states.
• Validate error messages.

Troubleshooting

Common issues and solutions:

• Messages do not arrive: Verify origin configuration. Confirm you add the event listener before the marketplace loads.
• Handlers do not execute: Check console for errors. Verify the event.data shape matches your handler's expected structure.
• UI not updating: Verify DOM manipulation. Check that the modal or page change is happening synchronously where expected.
• Modal issues: Check z-index and styling. Confirm parent containers don't have conflicting overflow rules.

Support

What's Next

• Buttons & Actions — configure the Send to page in my app destination on a default action.
• Permissions — configure Send to page in my app as a No Access Fallback.
• Per-Listing Overrides — override destinations for specific listings.
• Embed Script Implementation — the embed code that hosts the marketplace and dispatches the events.