Skip to main content

C.5 InApp Controls / Ribbons

InApp Controls / Ribbons enables brokers to display targeted promotional and informational elements directly within the cTrader interface. This module provides a powerful marketing and communication channel that allows brokers to engage users with personalized messages, promotions, and calls-to-action.

Overview​

The InApp Controls / Ribbons module enables:

  • Targeted promotional ribbons within cTrader interface
  • Personalized messaging based on user segments
  • Interactive controls for user engagement
  • Real-time content updates and scheduling
  • Comprehensive analytics and performance tracking

Prerequisites​

Before implementing InApp Controls / Ribbons, ensure completion of:

  • Part A: All foundation requirements
  • Part B: B.1 (Full SSO) - Required for user identification and targeting

Note: InApp Controls / Ribbons requires B.1 Full SSO as it needs access to the broker's user database for targeted messaging.

Architecture​

Control Types​

  1. Promotional Ribbons: Marketing messages and promotional offers
  2. Informational Banners: Important announcements and updates
  3. Interactive Controls: Clickable elements with specific actions
  4. Targeted Messages: Personalized content based on user behavior

Targeting Capabilities​

  • User Segments: Target based on account type, balance, trading volume
  • Behavioral Targeting: Target based on trading patterns and activity
  • Geographic Targeting: Target based on user location
  • Temporal Targeting: Schedule messages for specific times

Implementation Flow​

Control Creation and Management​

Stage 1: Control Definition​

  1. Broker defines control content

    • Content: Message text, images, call-to-action buttons
    • Targeting: Define target audience criteria
    • Scheduling: Set display schedule and duration
    • Actions: Define actions for user interactions

  2. Control configuration

    • Visual Design: Colors, fonts, layout specifications
    • Positioning: Location within cTrader interface
    • Priority: Display priority when multiple controls active
    • Frequency: Display frequency and capping rules

Stage 2: Control Distribution​

  1. Control registration with cTrader

    • API Call: Register control definitions with cTrader backend
    • Targeting Rules: Upload targeting criteria and user segments
    • Content Assets: Upload images and other media assets
    • Schedule Information: Provide display schedules

  2. cTrader backend processes controls

    • Validation: Validate control configuration and content
    • Asset Processing: Process and optimize media assets
    • Targeting Index: Index targeting rules for efficient matching
    • Cache: Cache control data for performance

Stage 3: User-Specific Control Selection​

  1. User session initialization

    • User Identification: Identify user via Full SSO authentication
    • Profile Loading: Load user profile and trading data
    • Segment Evaluation: Evaluate user against targeting criteria
    • Control Selection: Select relevant controls for user

  2. Control rendering

    • Priority Sorting: Sort controls by priority and relevance
    • Position Assignment: Assign controls to interface positions
    • Content Assembly: Assemble control content with user data
    • Display: Render controls in cTrader interface

Stage 4: User Interaction and Analytics​

  1. User interaction with controls

    • Impression Tracking: Track control impressions and views
    • Click Tracking: Track user clicks and interactions
    • Action Execution: Execute defined actions (open screens, etc.)
    • Conversion Tracking: Track conversion events and outcomes

  2. Analytics and Reporting

    • Performance Data: Collect performance metrics
    • User Behavior: Analyze user interaction patterns
    • A/B Testing: Support for A/B testing different variants
    • Reporting: Provide comprehensive analytics dashboard

API Specifications​

Broker CRM Endpoints​

Control Registration​

POST /ctrader/api/controls/register
Content-Type: application/json
Authorization: Bearer {managerToken}

Request Body:

{
    "controlId": "promo_summer2023",
    "type": "ribbon",
    "name": "Summer Trading Bonus",
    "content": {
        "title": "Get 50% Bonus on Deposits",
        "message": "Deposit $1000+ and get a 50% bonus. Limited time offer!",
        "imageUrl": "https://broker.com/assets/summer-promo.png",
        "backgroundColor": "#FF6B35",
        "textColor": "#FFFFFF",
        "buttonText": "Deposit Now",
        "buttonAction": {
            "type": "inapp_action",
            "action": "deposit",
            "parameters": {}
        }
    },
    "targeting": {
        "userSegments": ["premium", "active"],
        "minBalance": 1000.00,
        "maxBalance": null,
        "tradingVolume": {
            "min": 10000.00,
            "period": "monthly"
        },
        "countries": ["US", "UK", "DE"],
        "excludeSegments": ["inactive"]
    },
    "schedule": {
        "startDate": "2023-06-01T00:00:00Z",
        "endDate": "2023-06-30T23:59:59Z",
        "displayHours": {
            "start": "09:00",
            "end": "21:00"
        },
        "timezone": "UTC"
    },
    "priority": 1,
    "frequency": {
        "impressionsPerDay": 3,
        "impressionsPerWeek": 10
    }
}

Control Update​

PUT /ctrader/api/controls/{controlId}
Content-Type: application/json
Authorization: Bearer {managerToken}

Control Analytics​

GET /ctrader/api/controls/{controlId}/analytics
Authorization: Bearer {managerToken}

Response Example:

{
    "controlId": "promo_summer2023",
    "analytics": {
        "impressions": 15420,
        "clicks": 892,
        "clickThroughRate": 0.0578,
        "conversions": 156,
        "conversionRate": 0.0101,
        "revenue": 15600.00,
        "period": {
            "startDate": "2023-06-01T00:00:00Z",
            "endDate": "2023-06-15T23:59:59Z"
        },
        "breakdown": {
            "byCountry": {
                "US": {"impressions": 5000, "clicks": 300, "conversions": 50},
                "UK": {"impressions": 3000, "clicks": 200, "conversions": 40},
                "DE": {"impressions": 2000, "clicks": 150, "conversions": 30}
            },
            "byUserSegment": {
                "premium": {"impressions": 8000, "clicks": 500, "conversions": 100},
                "active": {"impressions": 7420, "clicks": 392, "conversions": 56}
            }
        }
    }
}

cTrader Backend Endpoints​

User Controls Retrieval​

GET /api/controls/user/{userId}
Authorization: Bearer {userToken}

Response Example:

{
    "userId": 12345,
    "controls": [
        {
            "controlId": "promo_summer2023",
            "type": "ribbon",
            "position": "top",
            "priority": 1,
            "content": {
                "title": "Get 50% Bonus on Deposits",
                "message": "Deposit $1000+ and get a 50% bonus. Limited time offer!",
                "imageUrl": "https://broker.com/assets/summer-promo.png",
                "backgroundColor": "#FF6B35",
                "textColor": "#FFFFFF",
                "buttonText": "Deposit Now",
                "buttonAction": {
                    "type": "inapp_action",
                    "action": "deposit",
                    "parameters": {}
                }
            },
            "displayRules": {
                "maxImpressions": 3,
                "currentImpressions": 1,
                "nextDisplayTime": "2023-06-16T09:00:00Z"
            }
        }
    ]
}

Control Interaction Tracking​

POST /api/controls/interaction
Content-Type: application/json
Authorization: Bearer {userToken}

Request Body:

{
    "controlId": "promo_summer2023",
    "userId": 12345,
    "interactionType": "click",
    "timestamp": "2023-06-15T10:30:00Z",
    "context": {
        "position": "top",
        "device": "desktop",
        "sessionDuration": 1800
    }
}

Control Types and Specifications​

Promotional Ribbons​

  • Purpose: Marketing messages and promotional offers
  • Content: Title, message, image, call-to-action button
  • Targeting: Based on user segments, behavior, demographics
  • Actions: InApp actions, external links, screen navigation

Informational Banners​

  • Purpose: Important announcements and system updates
  • Content: Title, message, optional image
  • Targeting: Broad targeting or specific user groups
  • Actions: Information display, optional acknowledgment

Interactive Controls​

  • Purpose: User engagement and interaction
  • Content: Interactive elements, forms, quizzes
  • Targeting: Specific user segments or behaviors
  • Actions: Form submission, survey completion, game interaction

Targeted Messages​

  • Purpose: Personalized communication
  • Content: Personalized messages with user data
  • Targeting: Highly specific targeting criteria
  • Actions: Personalized recommendations and offers

Implementation Requirements​

Broker CRM Requirements​

Content Management​

  • Content Editor: Visual editor for creating control content
  • Asset Management: Upload and manage images and media
  • Template System: Pre-designed templates for common control types
  • Preview Functionality: Preview controls before deployment

Targeting Engine​

  • User Segmentation: Tools for creating and managing user segments
  • Behavioral Analysis: Analyze user behavior for targeting
  • Rule Engine: Complex targeting rule creation and management
  • Performance Optimization: Efficient targeting rule evaluation

Analytics Platform​

  • Real-time Analytics: Real-time performance monitoring
  • Custom Reports: Customizable analytics reports
  • A/B Testing: A/B testing framework for control optimization
  • Export Capabilities: Data export for external analysis

Frontend Requirements​

Responsive Design​

  • Multi-Device Support: Optimize for desktop, mobile, tablet
  • Adaptive Layout: Adaptive layout based on screen size
  • Touch Optimization: Touch-friendly interaction design
  • Performance: Fast loading and rendering

User Experience​

  • Non-Intrusive: Controls should not disrupt trading experience
  • Clear CTAs: Clear call-to-action buttons and messaging
  • Easy Dismissal: Easy way to dismiss or hide controls
  • Accessibility: WCAG compliance for accessibility

Targeting Capabilities​

User-Based Targeting​

  • Account Type: Target based on account type (standard, premium, VIP)
  • Balance Range: Target based on account balance ranges
  • Trading Volume: Target based on trading volume patterns
  • Registration Date: Target based on user registration date
  • Geography: Target based on user location

Behavioral Targeting​

  • Trading Patterns: Target based on trading frequency and patterns
  • Platform Usage: Target based on platform usage patterns
  • Feature Usage: Target based on feature usage patterns
  • Inactivity: Target inactive or at-risk users

Temporal Targeting​

  • Time of Day: Display controls at specific times
  • Day of Week: Different controls for different days
  • Seasonal Campaigns: Time-based promotional campaigns
  • Event-Triggered: Controls triggered by specific events

Analytics and Metrics​

Performance Metrics​

  • Impressions: Number of times control is displayed
  • Clicks: Number of times control is clicked
  • Click-Through Rate (CTR): Percentage of impressions that result in clicks
  • Conversions: Number of desired actions completed
  • Conversion Rate: Percentage of clicks that result in conversions
  • Revenue: Revenue generated from control interactions

User Metrics​

  • Reach: Number of unique users who saw the control
  • Frequency: Average number of times each user saw the control
  • Engagement: User engagement levels and interaction patterns
  • Segment Performance: Performance by user segments

Quality Metrics​

  • View Time: Average time users spend viewing controls
  • Dismissal Rate: Percentage of controls dismissed without interaction
  • Error Rate: Percentage of controls that fail to display properly
  • User Feedback: User feedback and satisfaction scores

Error Handling​

Control Display Errors​

{
    "error": "Control Display Failed",
    "message": "Unable to display control due to content error.",
    "code": "CONTROL_DISPLAY_ERROR",
    "controlId": "promo_summer2023",
    "retryAllowed": true
}

Targeting Errors​

{
    "error": "Targeting Evaluation Failed",
    "message": "Unable to evaluate targeting rules for user.",
    "code": "TARGETING_ERROR",
    "userId": 12345,
    "fallbackControls": true
}

Content Loading Errors​

{
    "error": "Content Loading Failed",
    "message": "Unable to load control content assets.",
    "code": "CONTENT_LOADING_ERROR",
    "assetUrl": "https://broker.com/assets/summer-promo.png",
    "fallbackContent": true
}

Security Considerations​

Content Security​

  • Content Validation: Validate all content before display
  • Asset Security: Secure hosting and delivery of media assets
  • XSS Prevention: Prevent cross-site scripting attacks
  • Content Filtering: Filter inappropriate content

Data Protection​

  • User Privacy: Protect user privacy in targeting and analytics
  • Data Minimization: Collect only necessary data for targeting
  • Consent Management: Manage user consent for personalized content
  • GDPR Compliance: Ensure compliance with privacy regulations

Testing Requirements​

Functional Testing​

  • Control Display: Test control rendering and display
  • Targeting Logic: Test targeting rule evaluation
  • User Interaction: Test user interactions and actions
  • Analytics Tracking: Test analytics data collection

Performance Testing​

  • Load Testing: Test with multiple concurrent users
  • Rendering Performance: Test control rendering performance
  • Targeting Performance: Test targeting rule evaluation performance
  • Database Performance: Test database query performance

Security Testing​

  • Content Security: Test content security measures
  • Data Protection: Test data protection mechanisms
  • Access Control: Test access control for management APIs
  • Vulnerability Testing: Security vulnerability assessment

Business Benefits​

For Marketing​

  • Targeted Messaging: Precise targeting for marketing campaigns
  • Real-time Updates: Real-time campaign updates and optimization
  • Performance Analytics: Comprehensive performance analytics
  • A/B Testing: Data-driven campaign optimization

For User Engagement​

  • Personalization: Personalized user experience
  • Relevance: Relevant content and offers
  • Non-Intrusive: Non-intrusive integration with trading experience
  • Value Addition: Add value through relevant offers and information

For Revenue Generation​

  • Conversion Optimization: Improved conversion rates
  • Cross-selling: Opportunities for cross-selling
  • Upselling: Upselling opportunities for premium services
  • Customer Lifetime Value: Increased customer lifetime value

Best Practices​

Content Design​

  • Clear Messaging: Clear and concise messaging
  • Visual Appeal: Visually appealing design
  • Brand Consistency: Consistent with broker brand
  • Mobile Optimization: Mobile-first design approach

Targeting Strategy​

  • Segment Testing: Test targeting segments before full deployment
  • Frequency Capping: Avoid overexposure to users
  • Relevance: Ensure content relevance to target audience
  • Performance Monitoring: Monitor and optimize targeting performance

User Experience​

  • Non-Disruptive: Don't disrupt trading experience
  • Easy Dismissal: Provide easy dismissal options
  • Loading Performance: Ensure fast loading
  • Accessibility: Ensure accessibility compliance

This InApp Controls / Ribbons integration provides a powerful marketing and communication channel within cTrader, enabling brokers to engage users with personalized, targeted content while maintaining excellent user experience.