Rails use cases

Typically, a client application will need to make several calls to get all the information it needs to render the different pages that make up its interface and the rails within each page, as shown in the following diagram:

The calls that the client makes are as follows:

1. Retrieve the template hierarchy – call GET https://<host>:<port>/contentdelivery/v1/templateviews/hierarchy to get the hierarchy of templates that represent the various screens.

2. Retrieve the rail structure for a template – for each page/template, call GET https://<host>:<port>/contentdelivery/v1/templatesummary/{templateId} to get the rails that make up the page (without their contents).

3. Retrieve a specific rail and its contents – for each rail on the page, call GET https://<host>:<port>/contentdelivery/v2/templateviews/{templateId}/rails/{railId}?limit=10 to get the rail contents and metadata.
   Make sure you follow Rails best practices:

   1. Load only enough rails to populate the visible part of the screen, plus enough additional rails so that the user does not have to wait for rails to load when they scroll vertically. Load any additional rails only as needed when the user scrolls.

   2. Within each rail, load only enough rail items to fill the visible part of the rail and the first part that the user will see if they scroll horizontally, and only load more if they do scroll. (Use the limit, page, and offset parameters to do this.)

4. When the client displays a rail on the screen, it must report a railView event. As the user scrolls vertically and the client displays more rails, it must report railView for each new rail that it displays.
   See Reporting activity and event metrics to UAV and Rails-specific metrics.

5. When the user clicks on an item in a rail, the client needs to:

   1. Report a railSelection event. See Rails-specific metrics.

   2. Perform the appropriate action. This depends on the type of item the user clicks on.
      See Section types in Interpreting rails responses.

When you make a request to Content Delivery, you must include:

• The destination (e.g., tv or mobile) in the Nagra-Target header. Content Delivery returns the appropriate layout for that destination.

• The device type (e.g., Android or iOS) in the Nagra-Device-Type header. This ensures that the rails that Content Delivery returns reference the correct technical contents (e.g., an HLS technical for iOS or a DASH technical for Android).

Search

A client application can also use rails for searching. If a search template has been set up in OpCon (see Set up a search template), the client can send a request to Content Delivery that includes search criteria.

The response will consist of a template with a rail that contains the search results, which the client can display in exactly the same way as any other rail.

See Searching using search rails.