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