How Custom screens work

Overview

This article is part of Custom screens: Server side rendering which describes how Custom screens work.

• Data Flow
• Important notes
• Structure
• Components
• Establishing trigger authenticity
• Localization
• Conclusion

Data Flow

To get a solid grasp of how Custom screens work, it’s important to understand the flow of data between the driver app and your endpoint that builds your desired custom screens. In this sense, we have prepared the diagram below:

In essence, MotionTools acts as a middleware between the MotionTools driver app and your backend.

When a user opens a custom screen, the following process ensures:

1. Driver app contacts the MotionTools server to retrieve the data needed to render the custom screen.
2. MotionTools processes the request, then forwards it to the endpoint you provided when you configured the custom screen via the Dashboard.

3. Your backend receives the request from MotionTools, validates its authenticity, then replies with the content to be rendered.

4. MotionTools receives the payload generated by your server. We validate the payload schema, and if valid we return it to the original driver app instance.

5. The data your server generated is now rendered in the driver app as a custom screen! 🎉

Important notes

• In order to guarantee a smooth user experience, your backend needs to respond with a valid payload within 1 second, otherwise we will issue a timeout.
• The request from MotionTools to your backend will have attached an Authorization header that stores a JWT which encodes the MotionTools userId on whose behalf the request is made.
• If you check 'Embed user profile fields in JWT token' when setting up your custom screen in the dashboard, the following additional fields will be available in the JWT: name, given_name, family_name, email, email_verified.
• The process described above is synchronous: the driver app shows a loading indicator while this communication between MotionTools and your backend takes place.
• If any errors occur while requesting the custom screen data (including a timeout), the app will display an error message.

Structure

Custom screens are structured as a list of components, where each component represents an element that renders on screen. Every component covers the full width of the screen.

The JSON representation of a custom screen follows its visual structure - it has a title and an array of components:

{
  "title": "Title",
  "components": [
    {
     //component 1
    },
    {
     //component 2
    },
    ...    
  ]
}

Components

To keep things focused in this article, the list of available components is documented in another dedicated article:

• Reference: Custom screens components

We encourage you to browse our available components and get accustomed to their capabilities and schema, before moving forward. Future sections and articles assume you’re already familiar with available components.

Establishing trigger authenticity

When MotionTools contacts your backend to obtain the payload for a particular custom screen, it will attach an Authorization header on the request to your server. The header will store a JWT that, among others, you should use to ensure the authenticity of the incoming request.

• Format: Bearer <JWT_Token>

The process to fully establish the authenticity of the incoming request is optional to perform, however we strongly recommend you do not skip it.

It involves two steps:

1. Verify the JWT against the public key handed out by the Dashboard when setting up the custom screen. Verify the token using your favorite library with support for JWT: Official list. Passing this verification guarantees that the request comes from MotionTools, and not from a malicious third party.

2. Check the value of the jti field of the JWT against a token reuse store, in order to prevent replay attacks.

Localization

Custom screens have built-in localization support.

When MotionTools request data for a particular custom screen from your backend, it also includes the Accept-Language header on the request to your backend. The contents of Accept-Language will be the the IETF language tag (en-US) or ISO639-1 (en) locale currently applied on the device where the custom screen will be rendered.

To localize accordingly, your system is expected to check the value of Accept-Language and match the language of the custom screen to the locale applied on the user’s device.

Conclusion

In this article you learned the ins & outs of our Custom screens feature. Up next, we will finally reach the fun part: we will set up a custom screen in the dashboard!

▶️ Continue to Part 2: Configure a new custom screen via the dashboard