Component Development Guide > Guidelines & Best Practices

Component Architecture

This is a set of best practices for building out your Flite component's base functionality (the Build portion of the Component Lifecycle). The guidelines listed here are specific to Flite components, rather than the general UI or application design guidelines found in the General Principles article.

Track all events: A component should track as many events as makes sense given that component’s functionality. For example, a component with an email address input form should track all form submissions (i.e. when a user clicks the submit button). Components should also track all clickthroughs, scrolls, tab/button clicks, etc. Advertisers using your component can decide for themselves which metrics are important to them and which ones are not. All of this tracking should be done using the Flite Ad API, to make sure the events appear in Flite’s metric reports whenever the component is used inside an ad. See the Flite Metrics section of this document for more guidance on tracking metrics in your components.

Handle errors gracefully: Make sure the component handles errors in a way that disrupts the user experience as little as possible. This means several different things.

• When an error occurs, the component should give an error message to the user and continue operation; it should not crash.
• All error messages should be friendly, descriptive, and understandable to an average user. This means no overly technical error messages that refer to the internal operation of the component.
• There should be an error message for every potential error that can affect the user’s interaction with the component.
• When a connecting third party service or API is unavailable, the component should provide graceful failover.
• If the component has forms, it should provide form field validation for all form elements.
• If the error is on the user’s end (e.g. invalid email address), it should be easy for the user to understand what they did wrong, and to try the failed operation again.

Secure any sensitive information. If your component handles sensitive or personally identifiable user information (e.g. email addresses, phone numbers, etc.), make sure that this information is encrypted and secure when it is passed over the wire. Similarly, if the component's operation involves handling sensitive information that is integral to its function (e.g. API keys/passwords for any third party services), make sure this data is secure when it is transferred. Finally, make sure to review any third party APIs you might be using in your component from a security standpoint.

Be conscious of perceived performance. If there is a part of the component workflow where you expect latency while some data is loaded or processed, make sure to bring up a loader image, spinner, or some other visual cue to communicate to the user that the component didn’t break, and is in fact working as expected.

Provide affordances for interactive elements. If you want users to interact with an element, make that clear from the element’s design. For instance, if you want users to click something, then make it look clickable – e.g. shape it like a button, give it some dimensionality, subtly change its appearance when the user mouses over it, etc.

Minimize the number of screens. If your component needs to have multiple screens in order to accomplish its desired functionality, reduce that number of screens as much as possible. This will make it easier for users to understand what the component does, and for ad developers to configure the component.

Provide good debug information. Make an effort to provide good debug information. We recommend adding a hidden Debug Mode parameter to your component, that can be toggled on and off in Component Studio. Hidden parameters cannot be accessed by component users. When it is turned on, the ad should output helpful debug information about the component’s operation and status. Just make sure to turn off Debug Mode when releasing a component into production; live components should not output debug messages!