Build a homepage

A homepage is usually made of several CMS-managed content areas, such as featured carousels, playlist shelves, radio station rows, tagged content collections, campaign banners, new releases, or editorial recommendations.

The Tuned Global CMS is used by content, editorial, or marketing teams to decide what appears on the homepage. Your app retrieves that configuration through Tuned Global APIs and renders the homepage in the front-end experience.

This approach allows non-technical teams to update homepage content without requiring an app release.

How a CMS-managed homepage works

A typical workflow looks like this:

1. A CMS user configures the homepage structure and content in the Tuned Global CMS.
2. They add featured items, shelves, carousels, banners, playlists, radio stations, albums, artists, or tagged content groups.
3. They apply any required language, country, content tier, or visibility rules.
4. Your app retrieves the homepage configuration using Tuned Global APIs.
5. Your front end renders each homepage section using the data returned by the API.
6. When a user selects an item, your app routes them to the correct destination.

The CMS controls what appears on the homepage. The app controls how that content is displayed.

Retrieve homepage items

These endpoints are part of the Metadata API and are used to retrieve CMS-managed page content.

To retrieve CMS-managed homepage content, use the Get Items endpoint for the relevant CMS page.

👉 Endpoint: GET /api/v2.4/pages/{name}/items

Use this endpoint when your app needs to load the configured items for a homepage or another CMS-managed page.

Example request:

👉 Endpoint: GET /api/v2.4/pages/home/items StoreId: YOUR_STORE_ID

Replace home with the page name configured for your service.

The response should be used to determine which sections and items to render on the homepage. Your app should not hardcode the homepage layout if the page is intended to be managed from the CMS.

Retrieve public homepage items

Use the Get Public Items endpoint when the homepage or page content should be available without the same user-specific context as authenticated areas.

👉 Endpoint: GET /api/v2.4/pages/{name}/publicitems

Example request:

👉 Endpoint: GET /api/v2.4/pages/home/publicitems StoreId: YOUR_STORE_ID

Use the API Reference to confirm whether your implementation should use items or public items, depending on your app’s authentication flow and content visibility requirements.

Build homepage sections

A homepage response may include different item types or content blocks. Your front end should inspect the returned item data and render each section using the appropriate component.

For example:

The exact front-end layout is controlled by your application, but the content, ordering, and destination should come from the CMS-managed API response.

Use carousels on the homepage

If your homepage includes a featured carousel, retrieve the carousel content using the relevant Content Pages & CMS Content endpoint.

👉 Endpoint: GET /api/v2.4/pages/{name}/items

For language-specific carousel content, use:

👉 Endpoint: GET /api/v2.4/pages/carouselbylanguage

For country-specific carousel content, use:

👉 Endpoint: GET /api/v2.4/pages/carousel-by-country

Use these endpoints when the CMS team needs to show different homepage content by language, country, or market.

Use playlists on the homepage

If the homepage includes CMS-managed playlists, your app should use the playlist ID returned by the homepage response to retrieve the relevant playlist details and tracks.

For example, when a homepage item links to a playlist, your app can:

1. Display the playlist card using the metadata returned in the homepage response.
2. Open the playlist detail page when the user selects it.
3. Retrieve the playlist details and track list using the relevant Playlist endpoints.

This keeps the homepage lightweight while allowing the playlist detail page to load the full playlist experience only when needed.

Use tags on the homepage

Tags can be used to power flexible homepage shelves, such as mood, genre, campaign, or activity-based sections.

For example, a CMS user may tag several playlists, albums, songs, or radio stations with a tag such as workout, kids, new releases, or local artists.

Your app can use the configured tag to retrieve and display the related content. This allows the CMS team to change which content appears in a homepage shelf by changing tag assignments, rather than requiring a code change.

Route users from homepage items

When a user selects a homepage item, your app should route them based on the item type and destination returned by the API.

For example:

• If the item is a playlist, open the playlist detail page;
• If the item is a radio station, open or start the station experience;
• If the item is an album, open the album detail page;
• If the item is an artist, open the artist page;
• If the item is a custom banner, follow the configured link or deep link;
• If the item points to another CMS-managed page, open that page in the app.

Where additional data is required, call the relevant API endpoint for that content type after the user selects the item.

Recommended implementation pattern

1. Confirm the homepage is configured in the CMS The homepage structure, featured areas, shelves, banners, and linked content should be configured by a CMS user.
2. Retrieve the homepage configuration Use GET /api/v2.4/pages/{name}/items to retrieve the CMS-managed homepage content. Use GET /api/v2.4/pages/{name}/publicitems where public access is required.
3. Choose the correct localisation approach If the homepage changes by language or country, use the relevant language-specific or country-specific carousel endpoint.
4. Render each homepage section Use the item type, title, image, order, and destination returned by the API to choose the correct front-end component.
5. Load detailed data only when needed If a user selects a playlist, station, album, artist, or other content item, call the relevant API endpoint to retrieve the full detail view.
6. Respect visibility and catalogue rules Your app should respect any content tier, language, country, territory, rights, access, or availability rules returned or enforced by the API.
7. Handle unavailable content gracefully If a homepage item points to content that is no longer available, your app should hide it, skip it, or show a fallback state.
8. Handle updates and caching If homepage content, linked content, artwork, tags, or carousel items are updated in the CMS, the change may not appear instantly in the app because caching may be used for performance. If an immediate update is required, the relevant cache may need to be cleared or refreshed.

Related API Reference sections

Developers should refer to the API Reference for endpoint-level details:

Important notes

The homepage should be treated as a CMS-managed experience. Developers should avoid hardcoding featured content if the homepage is intended to be managed by editorial, content, or marketing teams.

The app should render the homepage based on the items returned by the API, including their order, images, content type, and destination.

If your service uses language-specific or country-specific homepage rules, make sure the app calls the correct endpoint and passes the required context.

If the homepage includes content that is restricted by user tier, market, territory, or catalogue availability, your app should respect those rules before displaying or playing the content.