Motivation Pop-ups

Feature Owner: James Derick Billate
Module: Organization
Priority: Must
Date: July 8, 2026

Executive Summary

Creators need the ability to add motivational pop-up messages, either text or media, that display to learners during quest progression. This feature enhances learner engagement by providing contextual motivational content at key moments in the quest journey.

What is this feature?

Motivation Pop-ups allows Creators to add motivational text or media to quest content cards. These motivational items are configured from the Creator editing experience and are intended to display as overlays in the Quest Player during learner progression.

Why does it matter?

Motivational content at strategic moments increases learner engagement, provides encouragement at critical points, and improves the overall quest experience. This feature directly supports the gamification and engagement goals of the WyzQuests platform.

What's the MVP scope?

• Upload and manage motivation content: text, image, video, gif, or audio.

• Configure motivation content per content card.

• Permission logic for Creator management and learner visibility.

• Motivation storage in quest content card data.

• Pop-up modal/overlay rendering in Quest Player.

1. User Pain Point & Solution

Creators struggle to keep learners motivated during longer quest sequences, leading to incomplete quest journeys and reduced engagement metrics. Some learners lose momentum at critical decision points or challenging sections. Motivation Pop-ups gives Creators a way to attach encouragement, reminders, or media-based motivation directly to content cards.

Pain Points

• Emotional: Learners feel discouraged during difficult quest segments.

• Functional: No mechanism to deliver contextual encouragement during quest progression.

• Business: Lower quest completion rates and reduced platform engagement when learners lose momentum.

2. 4D Framework Mapping

Diagnose: Identifies points in quest progression where learner motivation may decrease.

Design: Enables Creators to map motivational messages or media to specific quest cards and progress moments.

Develop: Constructs the pop-up configuration and media upload workflow inside the Creator editing experience.

Deliver: Provides Creators with an effective tool to improve learner retention and engagement throughout quest journeys.

3. USER FLOWS

Entry Points: Creator must be logged in and have access to manage their quest.

Success Criteria: Creator successfully configures a motivational pop-up on a content card, and that motivation content is saved for display to learners at the intended quest progression point.

Main Path (Happy Path)

• Sign in as a Creator.

• Navigate to a Quest.

• Access Outline or content card editing.

• Access a card and click the spark icon.

• Choose motivation type: text, image, video, gif, or audio.

• Apply the necessary text input or media upload.

• Save the motivation content.

• System stores the motivation data on the selected content card.

• Learner reaches the designated card in Quest Player and sees the motivation pop-up.

No Data: Alert the Creator that no motivation pop-up has been added or configured.

API Error: Terminate pop-up processing and display the proper error codes and messages.

Permission Denied: If the authenticated account does not own or have access to the quest, terminate the request and show an access error.

Decision Points:

• IF Creator has permission THEN allow pop-up management ELSE deny access and show an error message.

• IF motivation type is text THEN save text data to the content card ELSE validate and upload media.

• IF media upload succeeds THEN save media URL and metadata ELSE show upload error.

• IF Motivational Popup is disabled in quest settings THEN Creators should not be able to configure or use the feature until it is enabled.

4. Information Architecture

Primary Information

• Creator or quest owner information.

• Quest information.

• Content card information.

• Pop-up content: text or media.

• Motivation type.

• Secondary Information

• File name.

• File type.

• File URL.

• File storage path.

• Quest setting: Motivational Popup enabled or disabled.

Secondary Information

• Updated timestamp.

• Upload status.

Tertiary Information

• Spark icon via cards.

Actions

• Primary CTA

  • Spark icon via cards

• Secondary Actions

  • Choose motivation type.

  • Upload media.

  • Save motivation.

  • Delete or clear motivation.

5. Data Requirements

Frontend Needs

• Creator account information.

• Quest ID.

• Content card ID.

• Motivational Popup quest setting.

• Motivation type.

• Text motivation input.

• Media file or media URL.

• Existing card motivation data.

API Calls Frontend Will Make

• PATCH /api/creator/(content)/update-quest

• POST /api/creator/quest-content-cards/create

• PUT /api/creator/quest-content-cards/update

• POST /api/creator/quest-content-cards/upload-motivation-media

• GET /api/creator/(content)/get-quest

6. Performance Considerations

Database Optimization

Ensure Supabase queries are limited to necessary quest and card columns rather than global calls.

Media Optimization

• Validate file type and file size before upload.

• Store media in a predictable path per quest and content card.

• Avoid re-uploading unchanged media when a Creator updates text-only motivation.

7. Security & Authorization

Who Can Access This Feature?

Administrator: No access.
Reviewer: No access.
Creator: Full access.
Learner: View access.
Agency Admin: No access.

8. Error Handling

Current Existing Error Handling

• Invalid credentials return an authentication error.

• Unauthorized users cannot configure motivation pop-ups.

• Quest not found or access denied returns an error.

• Content card not found returns an error.

• Missing required upload fields return an error.

• Invalid motivation type returns a validation error.

• Invalid media file type or size returns an upload validation error.

• Failed media upload returns a storage error.

• Failed card update returns an API error.

9. Testing Checklist

Happy Path

• Sign in as a Creator.

• Navigate to a Quest.

• Enable Motivational Popup in quest settings if required.

• Access Outline or content card editing.

• Access a card and click the spark icon.

• Add text motivation and save it.

• Add media motivation and save it.

• Confirm motivation data is saved on the card.

• Confirm motivation pop-up displays correctly in Quest Player.

Edge Cases

• Unauthorized account.

• Quest not found.

• Content card not found.

• Invalid motivation type.

• Invalid data input.

• Invalid media size or media type.

• Motivational Popup disabled in quest settings.

• Storage upload failure.

10. OPEN QUESTIONS

• Should learner analytics for specified motivation pop-ups be added?

• Should motivation pop-ups support trigger rules beyond card-level display?

11. OUT OF SCOPE

• Motivational pop-up configuration via Exploration mode nodes rather than strictly via cards.

• Advanced learner analytics for pop-up views, dismissals, or completion impact.

• Multi-step trigger conditions beyond card-level motivation.

12. SUCCESS METRICS

• Motivation pop-ups are displayed correctly in Quest Player.

• Creators can save text motivation on a content card.

• Creators can upload and save media motivation on a content card.

• Learners receive the configured motivation during quest progression.

18. DEPENDENCIES

This feature depends on

• Quest Creation.

• Activity Cards.

• Creator account details.

• Supabase Database.

• Supabase Storage.

This feature depends on this

• Quest Player learner display behavior.

19. TIMELINE & OWNERSHIP

Backend: James Derick Billate

Frontend: James Derick Billate

QA: Internal development testing

Estimated Completion: Feature completed.

Note: API Endpoints and Schema please refer to its Technical Documentation