Media App — User Guide

The Media app gives your collection a single home for visual content — images, videos, 3D models, and embeds — and lets you arrange them into reusable presentations called Media Views. Views can be deep-linked from anywhere in your SmartLinks experience, dropped in as widgets, or used as the default the app opens to.

How it works (in 30 seconds)

The app has two halves:

1. Media Pool — your library of assets. Add anything you want to use anywhere.
2. Media Views — saved presentations. Each view picks items from the pool (by tag and/or type), arranges them in a chosen layout, and can be linked to or embedded.

You curate the pool once. You then build as many views as you need on top of it.

Getting started

Open the Media admin for your collection. You'll see a header at the top and two pill tabs: Media Pool and Media Views. Use the help link in the header to jump back to these docs anytime.

1. Add some media

In the Media Pool tab, click Add Media Item. You can bring in assets four ways:

Supported types: images (JPG, PNG, WebP, GIF, SVG), videos (MP4, WebM), 3D models (glTF, GLB), and embeds (YouTube, Vimeo, etc.).

For each item, set:

• Title and alt text — used for accessibility and admin search.
• Tags — free-text labels (e.g. hero, product-detail, lifestyle). Views filter by these.
• Sort order — controls the default order within the pool.

The pool sidebar groups items by type (Images, Videos, 3D Models, Embeds) so it's easy to scan a large library.

2. Build a Media View

Switch to the Media Views tab and click Add Media View. A view is just a name + a filter + a display mode:

• Name — what users and pickers see (e.g. "Product Hero Carousel").
• Tag filter / type filter — narrow the pool down. Leave empty to include everything.
• Limit — cap the number of items shown.
• Display mode — Carousel, Grid, Video Player, or 3D Viewer.
• Display settings — mode-specific options (auto-play, dots, columns, etc.).
• Appearance — padding, sizing, scale, optional title and card chrome.
• Default view — mark exactly one view as the app's default (see below).

Save and you're done — the view is immediately available as a deep link, a widget option, and (if marked default) the app's landing screen.

The default view

Every Media app has one default view — the one shown when someone opens the app without specifying which view they want.

• The first time you open the admin, a Default Carousel view is auto-created and flagged as default.
• You can change which view is the default by editing any view and toggling its default flag. The system enforces a single default — promoting a new one automatically demotes the previous one.
• If you delete the current default, the next available view is auto-promoted.

This means the Media app is always usable out of the box: link to it directly, drop it on a page, or scan a proof — something sensible always renders.

Display modes

All modes support lightbox — click any item to open it full-screen.

Embedding & linking

There are three ways to surface a Media View in the wider SmartLinks experience:

As a deep link

Every view is automatically registered as a deep-linkable destination. The platform's Link Picker lists your views by name in any other app — no IDs to copy or remember. When someone follows the link, the app opens directly on that view.

Behind the scenes the URL carries a viewId parameter; if it's missing the app falls back to the default view.

As a widget

Place a MediaWidget on any page through the platform's widget system. The widget's config picker lists every view by name. If no view is selected, the widget renders the default view, so it's always safe to drop in.

As a full-page container

The Media app itself can be embedded as a container. Without parameters it shows the default view; with ?viewId=… it filters to one specific view.

Scoping

Both pool items and views can live at two levels:

• Collection scope — available across the whole collection.
• Product scope — only available in the context of a specific product (overrides or supplements the collection-level set).

Use product scope when a particular product needs its own hero carousel or its own set of lifestyle shots.

Tips

• Tag intentionally. A small, consistent tag vocabulary (e.g. hero, gallery, detail, lifestyle) lets you build many specialised views from one pool.
• Reuse the pool. Don't duplicate an asset just to use it in a second view — add another tag instead.
• One default to rule them all. Pick the view that makes the best first impression; that's what new visitors see.
• Keep view names clear. They appear in pickers across the platform — Hero Carousel beats View 1.

Troubleshooting

Nothing renders when I open the app. Check the Media Views tab — you need at least one view, and one of them must be flagged as default. (One is normally seeded automatically.)

A widget is empty. The selected view's tag/type filter probably matches no pool items. Loosen the filter or add the right tags to your assets.

3D model won't load. Confirm it's a valid glTF or GLB file and the URL is publicly accessible.

Video won't play. Use MP4/H.264 for widest browser support.

For platform-level questions, see the SmartLinks documentation.