Configuration Options

Learn about all available parameters to customize your Plaros embeds.

Base URL Structure

All Plaros embeds use this URL pattern:

https://play.plaros.com/v1/embed/{tenantSlug}/playbooks?{parameters}

Required Parameters

zonePath (required)

The zone path from your Plaros dashboard that contains the playbooks you want to embed.

?zonePath=learning-hub

How to find your zone path:

  1. Go to your Plaros dashboard

  2. Navigate to Zones

  3. Copy the path from your desired zone

Optional Parameters

Playbook Selection

playbookId (optional)

Display a specific playbook instead of random selection.

?zonePath=learning-hub&playbookId=pb_123456

Default behavior: When omitted, a random playbook from the zone is selected for each visitor.

User Identification

userId (optional)

Identify users for personalized experiences and analytics.

?zonePath=learning-hub&userId=user_12345

Anonymous users: When omitted, anonymous user IDs are automatically generated.

Analytics & Debugging

analytics (optional)

Enable or disable analytics tracking.

  • Type: boolean

  • Default: true

  • Values: true, false

?zonePath=learning-hub&analytics=false

debug (optional)

Enable debug mode for development and troubleshooting.

  • Type: boolean

  • Default: false

  • Values: true, false

?zonePath=learning-hub&debug=true

⚠️ Important: Always disable debug mode in production environments.

Theme Customization

primaryColor (optional)

Override the primary theme color.

  • Type: string (hex color without #)

  • Default: Your tenant's default primary color

?zonePath=learning-hub&primaryColor=FF6B35

secondaryColor (optional)

Override the secondary theme color.

  • Type: string (hex color without #)

  • Default: Your tenant's default secondary color

?zonePath=learning-hub&secondaryColor=004E89

themeMode (optional)

Force a specific theme mode.

  • Type: string

  • Default: User's system preference

  • Values: light, dark

?zonePath=learning-hub&themeMode=dark

Complete Parameter Reference

Parameter
Type
Default
Description

zonePath

string

required

Zone path containing playbooks

playbookId

string

random

Specific playbook ID to display

userId

string

auto-generated

User identifier for analytics

analytics

boolean

true

Enable/disable analytics tracking

debug

boolean

false

Enable debug mode with console logs

primaryColor

string

tenant default

Primary theme color (hex without #)

secondaryColor

string

tenant default

Secondary theme color (hex without #)

themeMode

string

user preference

Force theme mode: light or dark

Example URLs

Basic Embed

https://play.plaros.com/v1/embed/acme-corp/playbooks?zonePath=onboarding

Specific Playbook with User Tracking

https://play.plaros.com/v1/embed/acme-corp/playbooks?zonePath=onboarding&playbookId=pb_123456&[email protected]

Custom Themed Embed

https://play.plaros.com/v1/embed/acme-corp/playbooks?zonePath=onboarding&primaryColor=FF6B35&secondaryColor=004E89&themeMode=dark

Development/Debug Mode

https://play.plaros.com/v1/embed/acme-corp/playbooks?zonePath=onboarding&debug=true&analytics=false

Building URLs Programmatically

JavaScript Example

function buildEmbedUrl(config) {
  const baseUrl = `https://play.plaros.com/v1/embed/${config.tenantSlug}/playbooks`;
  const url = new URL(baseUrl);
  
  // Required parameter
  url.searchParams.set('zonePath', config.zonePath);
  
  // Optional parameters
  if (config.playbookId) {
    url.searchParams.set('playbookId', config.playbookId);
  }
  
  if (config.userId) {
    url.searchParams.set('userId', config.userId);
  }
  
  if (config.analytics !== undefined) {
    url.searchParams.set('analytics', config.analytics.toString());
  }
  
  if (config.debug) {
    url.searchParams.set('debug', 'true');
  }
  
  if (config.primaryColor) {
    url.searchParams.set('primaryColor', config.primaryColor.replace('#', ''));
  }
  
  if (config.secondaryColor) {
    url.searchParams.set('secondaryColor', config.secondaryColor.replace('#', ''));
  }
  
  if (config.themeMode) {
    url.searchParams.set('themeMode', config.themeMode);
  }
  
  return url.toString();
}

// Usage
const embedUrl = buildEmbedUrl({
  tenantSlug: 'acme-corp',
  zonePath: 'employee-training',
  userId: 'user123',
  primaryColor: '#FF6B35',
  themeMode: 'dark'
});

Parameter Validation

Color Values

  • Must be valid hex colors (3 or 6 characters)

  • Do not include the # symbol in URL parameters

  • Examples: FF6B35, 004E89, F00, 0A8

Theme Mode Values

  • Only light and dark are supported

  • Case sensitive (use lowercase)

Boolean Values

  • Use string representations: 'true' or 'false'

  • Any non-'true' value is treated as false

Next Steps

  • Learn about Custom Theming for advanced branding options

  • See Integration Examples for framework-specific implementations

  • Check Troubleshooting if you encounter issues with parameters

PreviousQuickstartNextTroubleshooting Guide