public-api-docs

User API Tutorial Guide

Overview

Tutorials are operator-configured in-app education flows. A tutorial contains one or more slides, and each slide can include an image, title, description, background styling, and optional translation keys. Apps use tutorials to explain features at the moment where the user needs the context, such as app start, sign-up, vehicle selection, first rental, rental start, rental end, reservation start, or menu entry points.

The User API returns active tutorials. The app decides when to show them, how to render the slides, and whether a tutorial is shown once, shown again, or suppressed after the user chooses “do not show again”.

Related reference: User API

User API Guide

Discovery And Vehicle Guide

---

Core Concepts

Tutorial

A tutorial is a named content flow with trigger metadata and optional vehicle-category targeting.

Field	Meaning
id	Stable tutorial identifier. Use it for client-side seen/dismissed state.
name	User-facing or operator-facing tutorial name.
trigger	One or more app moments where the tutorial is intended to be shown.
singleView	Indicates that the tutorial is intended to be shown only once. The app must store the seen state.
doNotShowAgain	Indicates that the UI can offer a “do not show again” option. The app must store that choice.
customerSupport	Indicates that the tutorial can show a customer-support action.
vehicleCategoryIds	Optional category targeting. Use it for category-specific vehicle or rental education.
slides	Ordered tutorial screens. Slides are returned sorted by rank.

Multiple tutorials can be active at the same time. An app should select the tutorials relevant to the current trigger and context instead of assuming there is only one global onboarding flow.

Slides

Each tutorial is made of screens/slides.

Field	Meaning
title	Slide heading.
description	Main slide copy.
image	Main slide image reference.
backgroundColour	Optional background color.
backgroundImage	Optional background image.
customCss	Optional tenant styling hook. Use carefully in native apps.
rank	Slide order.
translationKeys	Optional translation key map for app-specific rendering.

The common rendering pattern is a carousel or paged modal with image, title, description, progress indicator, and close/continue actions.

Triggers

The trigger field tells the app where a tutorial is intended to appear:

Trigger	Intended app moment
APP_START	App launch or home screen initialization.
MODE_SWITCH	User switches between modes, for example rental and booking.
VEHICLE_SELECTION	User opens a vehicle detail sheet from the map.
SIGNUP	User completes sign-up or enters the app for the first time.
FIRST_RENTAL	User starts their first rental. The backend excludes this trigger for authenticated users who already have a rental.
START_RENTAL	User starts a rental.
END_RENTAL	User finishes a rental.
MENU	User opens the menu drawer or account navigation.
START_RESERVATION	User starts a reservation flow.
MENU_LINK	User explicitly opens a tutorial link from the menu.

Treat triggers as product hints. The backend does not force a modal to open in the app; the client owns the display timing and suppression rules.

---

Common User Workflow

Load Active Tutorials

Fetch tutorials during app bootstrap or when refreshing app content:

GET /tutorials?page=0&size=50&sort=id,asc

The endpoint returns active tutorials and supports pagination. Cache the response with the rest of the app content, but refresh it periodically because operators can change tutorial content and triggers.

Select A Tutorial For A Screen

When a relevant app event happens:

1. Filter cached tutorials by trigger.
2. If the flow is vehicle-specific, also check vehicleCategoryIds.
3. Exclude tutorials that the local user has already seen when singleView=true.
4. Exclude tutorials that the user dismissed with “do not show again”.
5. If multiple tutorials match, show the one with the most specific context first, or show a list when the user explicitly opened tutorials from a menu.

Example trigger selection:

on vehicle detail opened:
  matching = tutorials where trigger contains VEHICLE_SELECTION
  matching = matching where vehicleCategoryIds is empty or contains selectedVehicle.categoryId
  remove locally dismissed tutorials
  show the selected tutorial slides

Show Once Or Show Again

The API tells the app what the tutorial is intended for, but the app controls persistence:

• If singleView=true, store a local or backend-backed “seen” flag keyed by user ID and tutorial ID.
• If doNotShowAgain=true, show a dismissal option and store that choice.
• If neither flag is set, the app can show the tutorial every time the trigger occurs, or apply its own cooldown to avoid interrupting the user too often.
• For MENU_LINK, it is usually acceptable to show the tutorial even when it was already seen, because the user explicitly requested it.

First Rental Behavior

FIRST_RENTAL is special. When the user is authenticated and already has any rental, the backend excludes first-rental tutorials from GET /tutorials. Apps should still keep their own seen-state logic, but they do not need to manually detect previous rentals just to hide FIRST_RENTAL tutorials.

---

Most Relevant APIs

Area	Endpoints
Tutorials	GET /tutorials
Localized messages	GET /resources/messages, GET /resources/messages/languages
Vehicle context	GET /vehicles/{id}, GET /vehicles/code/{code}
Rental context	GET /rentals/{rentalId}, POST /rentals, POST /rentals/{rentalId}/operation

---

Implementation Notes

• Use tutorials as contextual education, not as required business-rule enforcement. Rental requirements, payment checks, and terms acceptance still come from their dedicated endpoints.
• Store seen and dismissed state per user and tutorial ID in the app or in your own app backend.
• Use vehicleCategoryIds to avoid showing category-specific instructions for the wrong vehicle type.
• Sort and render slides by rank; the API returns frontend slides in rank order.
• Use Accept-Language and resource localization consistently so tutorial copy matches the rest of the app.
• Keep tutorial display interruptible. Users should be able to close the flow unless the operator intentionally designed a required onboarding step outside the tutorial system.