C.1 Embedded cTrader Web

Embedded cTrader Web enables brokers to integrate the full trading platform directly within their client area, providing seamless access to trading functionality without requiring additional authentication. This module eliminates UX disruptions by leveraging existing broker authentication.

Overview

The Embedded cTrader Web module enables:

• Full trading platform integration within broker client area
• Single sign-on from broker CRM to cTrader Web
• iframe-based embedding for seamless user experience
• Automatic authentication via token exchange
• Consistent branding and user experience

Prerequisites

Before implementing Embedded cTrader Web, ensure completion of:

• Part A: All foundation requirements
• Part B: Either B.1 (Full SSO) or B.2 (Light Identity Handoff)

Note: Embedded cTrader Web requires long-term accessToken and therefore is only compatible with B.1 Full SSO.

Architecture

Integration Options

1. iframe Embedding: cTrader Web embedded within broker client area
2. New Tab Launch: cTrader Web opens in separate browser tab
3. Popup Window: cTrader Web opens in modal/popup window

Authentication Flow

• Broker CRM generates OT token for authenticated user
• cTrader Web receives token and validates with backend
• Token exchanged for long-term access token
• User authenticated without additional login

Implementation Flow

Flow Diagram

Detailed Flow Stages

Stage 1: User Authentication

1. User authenticates in broker CRM
   • Successful login via broker authentication system
   • User session established in broker client area
   • Authentication context available for token generation

Stage 2: Platform Launch

2. User initiates cTrader Web launch

   • Clicks "Launch Trading Platform" button
   • Selects trading from broker client area menu
   • Triggers embedded platform request

3. Broker generates OT token

   • Creates one-time token for user session
   • Associates token with authenticated user
   • Sets token expiration (typically 5-15 minutes)

Stage 3: Platform Loading

4. cTrader Web opens with token
   • iframe URL: https://app.ctrader.com/info?source=web&token={token}&lang=en&acc={account}
   • Parameters:
     • token: One-time authentication token
     • source: Platform source identifier
     • lang: User language preference
     • acc: Trading account number (optional)
     • theme: Theme preference (light/dark)

Stage 4: Token Exchange

5. cTrader Web processes token

   • Extracts token from URL parameters
   • Sends authorization request to cTrader backend
   • Initiates token exchange process

6. cTrader backend validates token

   • API Call: 4.2 - Verify and Exchange OT Token
   • Endpoint: /oauth2/token
   • Authentication: CRM API token

7. Broker CRM validates and responds

   • Verifies OT token validity and user context
   • Returns userId and accessToken
   • Establishes authenticated session

Stage 5: Session Establishment

8. cTrader backend authorizes session

   • Creates authenticated session under userId
   • Returns accessToken to cTrader Web application
   • Enables full platform functionality

9. Application stores access token

   • Saves token for subsequent API calls
   • Maintains session persistence
   • Enables automatic re-authentication

10. Authorized trading begins

    • User can access all trading features
    • Real-time market data and trading functionality
    • Account management and portfolio access

URL Parameters and Options

Required Parameters

Parameter	Required	Description
token	Yes	One-time authentication token from broker CRM
source	Yes	Platform source identifier (typically "web")

Optional Parameters

Parameter	Required	Description
lang	No	Language code (en, es, fr, etc.)
acc	No	Specific trading account number
theme	No	Theme preference (light, dark)
utm_*	No	UTM tracking parameters

Example URLs

<!-- Basic embedded URL -->
<iframe src="https://app.ctrader.com/info?source=web&token=f44bade2-2138-47c2-89e6-ce978bcca028&lang=en"></iframe>

<!-- With account and theme -->
<iframe src="https://app.ctrader.com/info?source=web&token=f44bade2-2138-47c2-89e6-ce978bcca028&lang=en&acc=8003098&theme=dark"></iframe>

<!-- With UTM tracking -->
<iframe src="https://app.ctrader.com/info?source=web&token=f44bade2-2138-47c2-89e6-ce978bcca028&lang=en&utm_source=crm&utm_campaign=trading_launch"></iframe>

Implementation Requirements

Broker CRM Requirements

Token Generation Endpoint

• Generate secure one-time tokens
• Associate tokens with authenticated users
• Set appropriate expiration times
• Return tokens to frontend for embedding

Token Validation Endpoint

• Validate OT tokens from cTrader backend
• Exchange tokens for access tokens
• Return user context and permissions
• Handle token expiration and invalidation

Frontend Integration

iframe Implementation

<div class="ctrader-embed-container">
    <iframe 
        src="https://app.ctrader.com/info?source=web&token={token}&lang={lang}"
        class="ctrader-iframe"
        frameborder="0"
        allowfullscreen>
    </iframe>
</div>

CSS Styling

.ctrader-embed-container {
    position: relative;
    width: 100%;
    height: 600px; /* Adjust as needed */
}

.ctrader-iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    border: none;
}

JavaScript Integration

function launchCTraderWeb(token, options = {}) {
    const params = new URLSearchParams({
        source: 'web',
        token: token,
        lang: options.language || 'en',
        theme: options.theme || 'light'
    });
    
    if (options.account) {
        params.append('acc', options.account);
    }
    
    const url = `https://app.ctrader.com/info?${params.toString()}`;
    
    // Embed in iframe
    const iframe = document.getElementById('ctrader-iframe');
    iframe.src = url;
    
    // Or open in new tab
    // window.open(url, '_blank');
}

Security Considerations

Token Security

• Short Lifetime: OT tokens should expire within 5-15 minutes
• One-Time Use: Tokens become invalid after first use
• Secure Generation: Use cryptographically secure token generation
• HTTPS Only: All communications must use HTTPS

iframe Security

• Sandbox Attributes: Use appropriate iframe sandbox attributes
• Content Security Policy: Implement CSP headers for security
• X-Frame-Options: Configure proper frame options
• Same-Origin Policy: Understand cross-origin implications

Session Security

• Token Validation: Always validate tokens before use
• Session Management: Proper session timeout and refresh
• Access Control: Implement proper user permission checks
• Audit Logging: Log all authentication events

User Experience Guidelines

Responsive Design

• Mobile Compatibility: Ensure iframe works on mobile devices
• Responsive Sizing: Adjust iframe size based on screen size
• Touch Support: Optimize for touch interactions
• Performance: Ensure fast loading times

Loading States

• Loading Indicators: Show loading state during platform initialization
• Error Handling: Display appropriate error messages
• Retry Mechanisms: Implement retry logic for failed loads
• Fallback Options: Provide alternative access methods

Integration Consistency

• Brand Consistency: Maintain broker branding in surrounding interface
• Navigation: Provide clear navigation options
• Help Support: Include help and support links
• Feedback: Collect user feedback on integration experience

Error Handling

Token Errors

// Handle token expiration
if (response.error === 'TOKEN_EXPIRED') {
    // Request new token from broker CRM
    refreshToken().then(newToken => {
        launchCTraderWeb(newToken);
    });
}

// Handle invalid token
if (response.error === 'INVALID_TOKEN') {
    // Show error message to user
    showError('Authentication failed. Please try again.');
}

iframe Errors

// Handle iframe load errors
const iframe = document.getElementById('ctrader-iframe');
iframe.addEventListener('error', function() {
    showError('Failed to load trading platform. Please try again.');
});

// Handle communication errors
window.addEventListener('message', function(event) {
    if (event.data.type === 'CTRADER_ERROR') {
        handleError(event.data.error);
    }
});

Performance Optimization

Loading Optimization

• Preloading: Preload iframe content when possible
• Lazy Loading: Implement lazy loading for better performance
• Caching: Cache static resources appropriately
• Compression: Use gzip compression for faster loading

Network Optimization

• CDN Usage: Use CDN for static content delivery
• Connection Pooling: Optimize connection reuse
• Request Optimization: Minimize unnecessary requests
• Monitoring: Monitor performance metrics

Analytics and Tracking

User Analytics

• Launch Events: Track platform launch events
• Session Duration: Monitor user session times
• Feature Usage: Track feature usage patterns
• Error Rates: Monitor error rates and types

Integration Analytics

• Token Success Rate: Track token generation success
• Load Times: Monitor platform loading performance
• User Flow: Analyze user navigation patterns
• Conversion Metrics: Track conversion to active trading

Testing Requirements

Functional Testing

• Token Generation: Test token generation and validation
• Platform Loading: Verify iframe loading and functionality
• Authentication: Test authentication flow end-to-end
• Error Scenarios: Test various error conditions

Performance Testing

• Load Testing: Test with multiple concurrent users
• Stress Testing: Test system limits and recovery
• Network Testing: Test with various network conditions
• Device Testing: Test across different devices and browsers

Security Testing

• Token Security: Test token security mechanisms
• Session Security: Verify session management security
• Data Protection: Test data protection measures
• Vulnerability Testing: Conduct security vulnerability assessment

Business Benefits

For User Engagement

• Seamless Experience: No additional login required
• Increased Usage: Easier access increases platform usage
• User Retention: Better experience improves retention
• Brand Consistency: Maintains broker branding throughout

For Operational Efficiency

• Reduced Support: Fewer login-related support issues
• Simplified Management: Centralized user management
• Better Analytics: Comprehensive user behavior tracking
• Cost Efficiency: Reduced authentication infrastructure costs

This Embedded cTrader Web integration provides a seamless trading experience within the broker's ecosystem, maximizing user engagement and operational efficiency.