Building An Interactive App Guide
Support teams often struggle with apps they have never installed.
A PDF with screenshots is the standard solution. Most people do not read PDFs. I wanted to build something better. I wanted a guide that feels like the real app. You see the home screen, click a button, and the next screen appears.
I built an interactive guide using real screenshots and clickable hotspots.
How It Works
I used Firebase Storage for images and vanilla JavaScript for logic. No external libraries.
- Each screen is one full image.
- I place invisible rectangles, called hotspots, on top of the image.
- These hotspots use percentages instead of pixels. This keeps them aligned when the window size changes.
- A simple state machine handles navigation. Each screen has an ID, an image, and a list of hotspots.
The Editor
Measuring coordinates by hand is slow. I built a standalone HTML editor to speed up the process.
- Upload a screenshot.
- Drag your mouse to draw a hotspot.
- Link the hotspot to a target screen.
- Export the code directly.
Design Choices
Not every screen has full navigation. To prevent confusion, I added a pulsing blue glow to clickable areas. This shows users exactly where they can tap.
Key Technical Lessons
- Firebase Storage: Do not build URLs manually. Use the SDK method getDownloadURL. This includes the auth token needed to bypass security rules.
- CSS Flexbox: If you use flex: 1 in a column layout, the parent must have an explicit height. Set min-height: 0 on the child to prevent overflow.
- Performance: Calling Firebase on every click adds lag. I implemented an in-memory cache and preloaded all images when the modal opens. This makes navigation instant.
- Scaling: Use the CSS transform: scale() property. This ensures the image and hotspots stay perfectly aligned regardless of the screen size.
The Result
- 20 screens navigated like a real phone.
- 52 hotspots with visual cues.
- Instant loading via preloading and caching.
- Responsive design that fits any modal size.