Embed Script Implementation

This guide covers how to implement the Partner Fleet marketplace embed script in your application. The embed script renders the In-App Marketplace iframe, handles JWT authentication, passes integration status to the marketplace, and routes postMessage events between the marketplace and your application.

Basic Setup

1. Add Container Element

Add a container element where the script will render the marketplace iframe:

<div id="iframe-container"></div>

2. Include the Script

Add the Partner Fleet script to your page:

<script src="https://your-partner-fleet-domain/inapp_script.js"></script>

Basic Implementation

Initialize the embedded iframe with your JWT configuration:

const embeddedIframe = new EmbeddedIframe({
  // Required Configuration
  iframeOrigin: 'https://your-partner-fleet-domain',
  trustedOrigins: ['https://your-partner-fleet-domain'],
  containerId: 'iframe-container',

  // JWT Configuration
  initialToken: 'YOUR_INITIAL_JWT_TOKEN',  // Optional: Can be empty string if using getJwtToken
  getJwtToken: function() {
    return new Promise((resolve, reject) => {
      // Implement your token retrieval logic here
      try {
        const token = generateNewToken();  // Your token generation function
        resolve(token);
      } catch (error) {
        reject('Token generation failed');
      }
    });
  }
});

The getJwtToken function should return a Promise resolving to a fresh JWT for the current user. The embed will call this function on initial load and again when the token is near expiration. See the JWT SSO Implementation guide for the JWT payload structure and signing requirements.

Advanced Implementation: Passing Integration Status

In addition to the JWT, the embed script accepts an integrations array that pre-populates each end user's integration status for each listing. The marketplace uses these statuses to render the correct buttons (Install, Manage, Reinstall, Fix Issues, etc.) on each listing for that user.

const embeddedIframeWithIntegrations = new EmbeddedIframe({
  iframeOrigin: 'https://your-partner-fleet-domain',
  trustedOrigins: ['https://your-partner-fleet-domain'],
  containerId: 'iframe-container',
  initialToken: 'YOUR_INITIAL_JWT_TOKEN',
  integrations: [
    {
      partner_id: 'chrome',
      status: 'Pending',
      metadata: {
        installDate: '2024-03-15',
        version: '1.0.0'
      }
    },
    {
      partner_id: 'chili-piper',
      status: 'Pending',
      metadata: {
        configuration: {
          enabled: true,
          settings: {}
        }
      }
    }
  ],
  getJwtToken: function() {
    return new Promise((resolve, reject) => {
      fetchNewToken()
        .then(token => resolve(token))
        .catch(error => reject(error));
    });
  }
});

Integration Object Structure

{
  partner_id: string,    // Partner identifier
  status: string,        // Integration status
  metadata: object       // Additional integration data
}

Configuration Options

Required Parameters

Optional Parameters

Handling postMessage Events

When you configure a CTA destination as Send to page in my app on the Buttons & Actions, Permissions, or Per-Listing Overrides tab, clicking the button triggers a postMessage event from the embedded marketplace to your application. Your application listens for these events and routes the user accordingly.

Basic listener

window.addEventListener('message', (event) => {
  // Verify the message comes from your trusted origin
  if (event.origin !== 'https://your-partner-fleet-domain') return;

  const { action, path, listingId, ...rest } = event.data;

  if (action === 'navigate') {
    window.location.href = path;
  }
});

Always verify event.origin against your trusted origin to prevent malicious sites from sending fake postMessage events. For more advanced handler patterns including modal triggers and multi-action routing, see the Handling postMessage Events guide.

CNAME and Embed Origin

If you've configured a custom CNAME (for example, marketplace.yourcompany.com), your iframeOrigin and trustedOrigins should use that CNAME, not the Partner Fleet subdomain. The embed snippet generated in Developer Settings uses the correct values automatically.

Allowed Domains

The marketplace will only render on domains you've authorized. Configure these in Settings > In-App Marketplace > Developer Settings > Allowed Domains. If your embed doesn't render and you don't see JavaScript errors, check the Allowed Domains list first.

HTML Container Requirements

The container element:

• Must have a unique ID.
• Should have a defined width (either via CSS or class).
• Should have a defined height if parent element height is not set.

Example with custom dimensions:

<div id="iframe-container" style="width: 100%; height: 600px;"></div>

Script Behavior

Automatic Features

Responsive Sizing

• Adjusts height based on content.
• Maintains full width of container.
• Handles window resize events.

Token Management

• Requests new tokens when needed.
• Handles token refresh automatically.
• Maintains session continuity.

Cross-Origin Communication

• Securely handles messages between your application and the marketplace.
• Validates message origins.
• Manages integration status updates.

Event Handling

The script automatically handles:

• Window resize events.
• Content height changes.
• Initial load sizing.
• Token expiration.
• Token refresh requests.
• Authentication failures.
• Status update requests.
• Integration creation events.
• Metadata updates.

Best Practices

Container Setup

• Place container in a responsive layout.
• Avoid fixed height constraints.
• Consider mobile viewports.

Token Management

• Implement robust token generation logic.
• Handle token refresh failures gracefully.
• Include proper error handling.

Performance

• Load script asynchronously if possible.
• Initialize after DOM is ready.
• Handle loading states appropriately.

Common Issues and Solutions

Support

What's Next

• JWT SSO Implementation — backend signing and payload structure.
• Handling postMessage Events from the In-App Marketplace — advanced postMessage patterns.
• Dynamic Domains Configuration — multi-environment URL substitution.
• Test Tools — validate your token before deploying.
• Developer Settings — admin configuration reference.