Screens

Overview

Screens allow you to display ordered, interactive content to users within the mobile app. Screens support multi-line text combined with tappable actions, enabling users to navigate to other screens, submit information, scan documents, or launch other Platform functionality.

Common use cases include:

Emergency contact directories
Pre-trip checklists
Instructional content
Contextual workflows tied to specific loads or stops

Ultimately, you can utilize screens for a multitude of use cases, and can be customized to suit your needs.

How It Works

Screens are managed through App Manager or the Screens API. Each screen is referenced by a unique code value and can be launched from supported menu items or actions.

Screens can be configured using either static JSON definitions or dynamic JavaScript definitions depending on the desired behavior.

Screen Types and Creation

Two screen types are available depending on your implementation requirements:

Static screens: Displays the same content to all users by defining the definition property as a JSON array containing text and actions.
Dynamic screens: Generates content at runtime by defining a JavaScript function within the definition_javascript property. The function accepts a data object and returns a JSON array containing the screen layout.

Screens can be created and updated directly through App Manager or via the API.

App Manager

Using App Manager, you can use the built-in custom screen builder to define required data mappings and generate the initial JavaScript layout.

TIP: Save the original auto-generated JavaScript before applying custom API modifications. Restoring the original generated code allows the screen to become editable in App Manager again.

The following example shows a custom screen configured within App Manager:

Customizing Screens via API

Manage advanced screen behavior using custom JavaScript definitions through the API.

Retrieve the current screen definition using a GET request:

curl --request GET 'https://platform.driveaxleapp.com/api/v1/screens/YOUR-SCREEN-CODE' \
     --header 'Authorization: Key key=yourAPIkey' \
     --header 'Accept: application/json'

Modify the definition_javascript function to return the desired card array. Structure it as a single top-level unnamed function that accepts one data argument (a key-value store of data passed in from the action).
NOTE: Use ES6/JavaScript 2015 syntax within the function to handle the incoming payload data.
Submit a PUT request to update the screen with your custom JavaScript, ensuring the value is formatted as a single line with escaped quotes and newlines to keep the JSON payload valid.

The following action types can be used within your custom JavaScript definition: telephone, embedded-browser, browser, transaction-editor, scan-flow, screen, launch-url, and logout. To see more information regarding available action types, visit our Actions Guide.

IMPORTANT: Updating a screen through the API with custom JavaScript disables App Manager editing for that screen version to prevent accidental overwrites.

NOTE: Restore App Manager editing by re-uploading the original auto-generated JavaScript, including the commented fingerprint footer, before making additional App Manager changes.

Launching and Lifecycle Management

Launch and maintain screens using screen configuration properties.

Launching Screens

Configure actions or menu items using:

type: screen
screen_code: YOUR-SCREEN-CODE

This configuration launches the target screen within the mobile app.

TIP: Use the screen action type within screen definitions to create multi-step navigation flows between screens.

Archiving Screens

Set archived to true to remove a screen from the active App Manager list.

Archiving does not prevent the screen from displaying in the mobile app if active actions or menu items still reference the screen.

NOTE: The code property permanently identifies a screen. The id property represents the current version identifier and may change after screen updates.

Documentation Index