Skip to main content

Result Page Integration (Epic 2)

Technical implementation details for displaying QR codes on the result page in Epic 2.

Epic 2 Enhancement

This document describes how the result page is enhanced in Epic 2 to display and download QR codes alongside audio content.

See Text-to-Speech Submission API for the base Epic 1 implementation.

Overview​

Epic 2 extends the result page to include QR code generation, display, and download functionality. The QR code is generated server-side during audio creation and displayed alongside the audio player.

What Changed from Epic 1​

Epic 1 Result Page:

  • Audio player
  • Shareable link
  • Copy link button

Epic 2 Result Page (Additions):

  • 🆕 [NEW] QR code preview
  • 🆕 [NEW] Download QR code button
  • 🆕 [NEW] QR code usage guide
  • 🆕 [NEW] QR code specifications display

Data Structure​

Generation Entity (Epic 2)​

Fields:

FieldTypeDescription
idstringUUID identifier
textstringUser input text
slugstringUnique URL-safe slug
voiceIdstringSelected voice ID
clientIdstringClient identifier
audioUrlstringS3 URL of audio file
qrCodeUrlstring | null🆕 [NEW] S3 URL of QR code image (Epic 2)
statusstring"completed", "processing", or "failed"
characterCountnumberNumber of characters
processingTimenumberGeneration time in milliseconds
createdAtstringISO 8601 timestamp
createdByobjectUser info (userId, userName)

Epic 2 Addition:

  • qrCodeUrl field contains S3 URL to QR code PNG image
  • null in Epic 1, populated in Epic 2

Example Response (Epic 2)​

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Welcome to MicDots!",
    "slug": "welcome-micdots-1706882400123",
    "voiceId": "rachel-voice-id-123",
    "clientId": "client-abc-123",
    "audioUrl": "https://s3.amazonaws.com/micdots-audio/welcome-micdots-1706882400123.mp3",
    "qrCodeUrl": "https://s3.amazonaws.com/micdots-qr/welcome-micdots-1706882400123.png",
    "status": "completed",
    "characterCount": 20,
    "processingTime": 7850,
    "createdAt": "2024-01-22T14:30:00Z",
    "createdBy": {
      "userId": "user-id-456",
      "userName": "John Doe"
    }
  },
  "links": {
    "share": "https://micdots.com/play/welcome-micdots-1706882400123",
    "audio": "https://s3.amazonaws.com/micdots-audio/welcome-micdots-1706882400123.mp3",
    "qrCode": "https://s3.amazonaws.com/micdots-qr/welcome-micdots-1706882400123.png"
  }
}

QR Code Card Component​

UI Structure​

The QR code card displays:

  • NEW Badge - Indicates this is a new Epic 2 feature
  • QR Code Preview - 200x200px image on white background
  • Download Button - Downloads the QR code as PNG
  • Format Info - "500x500px PNG • Print ready • Scannable"

Styling (CSS/SCSS)​

.qr-code-card {
  background: #242938;
  border: 2px solid #f093fb; // Pink gradient border
  border-radius: 16px;
  padding: 32px;
  position: relative;

  .new-badge {
    position: absolute;
    top: 16px;
    right: 16px;
    background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
    padding: 4px 12px;
    border-radius: 12px;
    font-size: 11px;
    font-weight: 600;
    color: #ffffff;
  }

  .qr-preview {
    background: #ffffff;
    border-radius: 12px;
    padding: 24px;
    margin-bottom: 20px;
    display: flex;
    align-items: center;
    justify-content: center;
    aspect-ratio: 1 / 1;

    img {
      max-width: 200px;
      max-height: 200px;
      border-radius: 8px;
    }
  }

  .download-button {
    width: 100%;
    height: 48px;
    background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
    border: none;
    border-radius: 8px;
    color: #ffffff;
    font-size: 16px;
    font-weight: 600;
    cursor: pointer;
    margin-bottom: 12px;
    transition: transform 0.2s;

    &:hover:not(:disabled) {
      transform: translateY(-2px);
    }

    &:disabled {
      opacity: 0.6;
      cursor: not-allowed;
    }
  }

  .format-info {
    font-size: 13px;
    color: #a0a8c0;
    text-align: center;
    margin: 0;
  }
}

QR Usage Guide Component​

The QR Usage Guide displays three use cases:

  1. 🖨️ Print & Display

    • Add to menus, posters, business cards, or product packaging

  2. 📱 Scan to Play

    • Anyone can scan with their phone camera to hear the message

  3. 📧 Digital Sharing

    • Include in emails, PDFs, presentations, or social media

API Integration​

Fetching Result Data​

The result page fetches generation data from the backend API.

Endpoint: GET /api/v1/text-to-speech/{id}

Headers:

Authorization: Bearer {access-token}
Content-Type: application/json

Response: See the "Example Response (Epic 2)" section above for the complete JSON response structure.

QR Code Download Functionality​

The download button allows users to save the QR code image to their device.

Download Behavior:

  • Fetches QR code image from S3 URL
  • Triggers browser download
  • Filename format: micdots-qr-{slug}.png
  • Falls back to opening in new tab if download fails

Error Handling​

QR Code Loading Error​

If the QR code image fails to load:

  • Display error message: "⚠️ Failed to load QR code. Please refresh the page."
  • Provide "Refresh Page" button
  • Log error to console for debugging

Download Error Handling​

If QR code download fails:

  • Show error notification: "Failed to download QR code. Please try again."
  • Allow user to retry download
  • Log error details for debugging

Responsive Design​

Layout Behavior​

The result page adapts to different screen sizes:

Desktop (≥ 1024px): 3-column grid Tablet (768px - 1023px): 2-column grid (QR card spans both columns) Mobile (< 768px): Single column stack

Responsive Styles​

.content-grid {
  display: grid;
  gap: 24px;

  // Desktop: 3 columns
  @media (min-width: 1024px) {
    grid-template-columns: repeat(3, 1fr);
  }

  // Tablet: 2 columns
  @media (min-width: 768px) and (max-width: 1023px) {
    grid-template-columns: repeat(2, 1fr);

    // QR card spans both columns
    .qr-code-card {
      grid-column: span 2;
      max-width: 400px;
      margin: 0 auto;
    }
  }

  // Mobile: 1 column (stack)
  @media (max-width: 767px) {
    grid-template-columns: 1fr;
  }
}

Performance Optimization​

Lazy Loading QR Code​

The QR code image uses browser native lazy loading:

  • loading="lazy" attribute prevents loading until image is near viewport
  • decoding="async" allows async image decoding
  • Explicit width/height (200x200) prevents layout shift

Preloading QR Code (Optional)​

Optionally preload QR code image when result data is fetched to improve perceived performance.

Analytics Tracking​

Track QR Code Downloads​

Track QR code downloads for analytics:

Success Event: "QR Code Downloaded"

  • generationId: UUID of the generation
  • slug: URL slug
  • timestamp: ISO 8601 timestamp

Failure Event: "QR Code Download Failed"

  • generationId: UUID of the generation
  • error: Error message

Testing​

Manual Testing​

Test the QR code display and download functionality:

  1. QR Code Display

    • Verify QR code image renders correctly
    • Check image has correct src attribute
    • Verify 200x200px dimensions

  2. Download Functionality

    • Click "Download QR Code" button
    • Verify button shows "Downloading..." state
    • Confirm file downloads with correct name: micdots-qr-{slug}.png
    • Verify downloaded file is valid PNG image

  3. Error Handling

    • Test with invalid QR code URL
    • Verify error message displays
    • Confirm "Refresh Page" button works

Security Considerations​

Validate QR Code URL​

Validate QR code URLs to prevent security issues:

Validation Rules:

  • Must be a valid URL format
  • Must be from allowed S3 bucket: s3.amazonaws.com/micdots-qr/
  • Must start with https://
  • Reject invalid or suspicious URLs

Error Handling:

  • Log validation errors to console
  • Display error state to user
  • Do not render invalid URLs