share

ENGINEERING

7min read

Cockpit 2.2—New Features of Android Debug Menu

In April this year we released version 1.0.0 of Cockpit—an open-source Android tool for developers—but also designers and even customers—to tweak the debug build of the application at runtime. At the beginning it was a very simple tool, providing the user with just the basic functionality and supporting only primitive types of parameters. Now, with version 2.2.0, we’ve come up with a lot of great features, making developing and testing your native Android app more effective than ever.

Read more on the first version of Cockpit in our previous blog post.

8215000A-5D87-4F26-AF87-6475D40A4237

Discover the story of Timeular, the revolutionary IoT time-tracking device

What is Cockpit?

Cockpit is an open-source library providing a way to easily tweak your app using a compact debug panel. It’s very simple to use: you only need to define the params in yml file and the library does the rest for you! It generates the Cockpit.java file, providing you with all the methods to work with the params you defined. It also generates an easy to use UI, so you don’t have to worry about details. No more debug panels written from scratch!

We know every app is different, so we didn’t want to impose any particular way of showing Cockpit. You decide it yourself—whether you want to show it on button click, on shake, on multi-touch—it’s up to you! In our sample app, however, we used Seismic library by Square to display Cockpit panel on shake, as we find this solution very simple yet useful and intuitive.

Since Cockpit is a debug panel, it’s obvious that it can be used by Android developers. At Polidea we’ve used it to change animation length, displayed text, timeouts, endpoints, etc. Testers will find it pretty handy as well. But Cockpit is much more than that. You can pass the app integrated with Cockpit to the designers and they’ll be able to test it with different params without needing the developer to rebuild the project for them. You can also pass a debug build to the client to help them decide on some features in your project.

What’s new in 2.2.0?

Versions 1.0.x provided only handling of limited types of params—boolean, integer, double and string and supported only flat structure of params with name and default value. We knew that it’s not enough for advanced applications’ needs and decided to extend the functionality of the library.

Flavor support

The new release brings support for flavors. Params defined in cockpit.yml file are applied to all the flavors. To modify their values or add new ones depending on the flavor, you need to add cockpit<flavorName> file accordingly, for example:

cockpitDebug.yml
cockpitStaging.yml
cockpitStagingDebug.yml
cockpitStagingRelease.yml

Support for both flat and complex param structure

Until now, only flat structure of yaml file was supported. We’ve decided this wasn’t enough. That’s why we introduced more complex param structure to suit more demanding user needs. With complex structure, you can define not only param’s name and default value, but also a description, which, if provided, will be used for display in Cockpit panel instead of param’s name, making the panel’s content more readable to people.

message:
  description: "Message text"
  value: "Test"

Of course if you’re fine with using param names for display, you can still use the flat structure:

message: "Test"

New param types

Version 2.2.0 adds handling of the list, color, slider, step, read-only and action types. Additionally, the params can be put into named groups. Let’s take a look at how to use those features.

LIST

To define a list, you have to add one simple line in your cockpit.yml file:

listSimpleTypeName: [ "staging", "testing", "prod" ]

Based on this line, our library will generate a spinner with three options to choose from. However, if you feel it’s not enough for you, you can specify display name and index of the item selected by default. To be able to do it, you have to use more complex structure to define your list, for example:

listComplexTypeName:
  type: list
  values: [ "staging", "testing", "prod" ]
  selectedItemIndex: 1

selectedItemIndex field is optional. If not provided, 0 is assumed. You can access the selected value from your code using getParamNameSelectedValue(), where paramName is your param’s name.

ACTION

Another useful feature is an ability to define a custom action and invoke it on a button click. To define an action, add the following to your cockpit.yml file:

actionTypeName:
  type: action
  description: "Action description"
  buttonText: "Perform"

buttonText field is optional. If not provided, “Perform” will be used. description is also optional and will be used instead of a param name if provided.

Android app

COLOR

Another new param type is color. When you define a parameter as color type, Cockpit will display its preview next to the value. Supported color formats are #RRGGBB and #AARRGGBB. You can define color param with a following piece of yaml:

footerFontColor:
  type: color
  description: "Font color"
  value: "#FFFFFF"

description is optional; will be used instead of a param name if provided.

RANGE SLIDER

Slider can be useful to pick a value from within a predefined range for example age, font size, etc. You can define one for Cockpit as follows:

fontSize:
  type: range
  description: "Font size"
  min: 6
  max: 48
  step: 1
  value: 36

description, as in all other params, is optional. step is optional as well. If not provided, 1 is assumed. At last, value is optional—if not provided, min value is used.

STEP

Another useful feature in Cockpit 2.2.0 is a step param. It can be used with numeric values and provides + and - buttons, so you can change the value step by step in either way. You can define a step param with the following piece of code:

fontSize:
  type: step
  value: 36
  step: 2
  min: 20
  max: 60
  description: "Total price font size"

min, max and description are optional.

READ-ONLY PARAM

A read-only param can be useful when you just want to display some information in the Cockpit panel. A build version is a good example. To define a read-only param, use:

appVersion:
  type: read_only
  description: "Version"

description, as usual, is optional.

GROUP

When your set of params gets more and more complex, it’s only natural you’d want to group them into some meaningful sections. That’s why we’ve introduced groups. Using this feature is really simple—you just need to add group field to the complex param definition. If you don’t provide a group for a param, it will be assigned to Default one.

Listening for changes

To make the most of the debug panel, it’s nice to have a way to observe changes of the params. That’s why Cockpit generates appropriate methods for you: for value changes, you can use addOnParamNameChangeListener() and removeOnParamNameChangeListener(), for list selection changes, you can use addParamNameSelectionChangeListener and removeParamNameSelectionChangeListener, for actions, which don’t change by design, but only get invoked, you can use addParamNameActionRequestCallback() and removeParamNameActionRequestCallback().

Restoring default values

After integrating Cockpit into one of our projects, we found out that it would be handy to be able to restore default values of the parameters after some changes. Because of that we’ve added both a feature of restoring default values globally and per each param. To restore the default value, you just need to press curved arrow icon and the change will get applied immediately.

Teamwork

UI features and design

After adding some new features we came to the conclusion that we really need some neat UI design. One of our designers did a great job and provided us with a very nice one you can see in the current version.

On top of that, we decided it would be nice to be able to actually see your application under the debug panel. To achieve that, we’ve introduced a bottom sheet fragment you can pull down to fit half of the screen’s height. That way you can update your params and observe the screen underneath.

What’s next?

We still have some ideas to develop in our library. At the moment we’re very proud of how Cockpit evolved and grew from version 1.0.0. We’re happy we were able to learn a lot and have fun during its development. We’d like to see the developers use Cockpit in their projects and are super curious about the feedback. Take a look at our repository and stay tuned for more!

share


MartaSoftware Engineer

LEARN MORE

Contact us if you have any questions regarding the article or just want to chat about technology, our services, job offers and more!

POLIDEA NEWSLETTER

Sign in and expect sharp insights, recommendations, ebooks and fascinating project stories delivered to your inbox

The controller of the personal data that you are about to provide in the above form will be Polidea sp. z o.o. with its registered office in Warsaw at ul. Przeskok 2, 00-032 Warsaw, KRS number: 0000330954, tel.: [0048795536436], email: [hello@polidea.com] (“Polidea”). We will process your personal data based on our legitimate interest and/or your consent. Providing your personal data is not obligatory, but necessary for Polidea to respond to you in relation to your question and/or request. If you gave us consent to call you on the telephone, you may revoke the consent at any time by contacting Polidea via telephone or email. You can find detailed information about the processing of your personal data in relation to the above contact form, including your rights relating to the processing, HERE.

Data controller:

The controller of your personal data is Polidea sp. z o.o. with its registered office in Warsaw at ul. Przeskok 2, 00-032 Warsaw, KRS number: 0000330954, tel.: [0048795536436], email: [hello@polidea.com] (“Polidea”)

Purpose and legal bases for processing:

 

Used abbreviations:

GDPR – Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016
on the protection of natural persons with regard to the processing of personal data and on the free movement
of such data, and repealing Directive 95/46/EC (General Data Protection Regulation)

ARES – Polish Act on Rendering Electronic Services dated 18 July 2002

TL – Polish Telecommunications Law dated 16 July 2004

1)        sending to the given email address a newsletter including information on Polidea’s new projects, products, services, organised events and/or general insights from the mobile app business world |art. 6.1 a) GDPR, art. 10.2 ARES and art. 172.1 TL (upon your consent)

Personal data:name, email address

2)       statistical, analytical and reporting purposes |art. 6. 1 f) GDPR (based on legitimate interests pursued by Polidea, consisting in analysing the way our services are used and adjusting them to our clients’ needs, as well as developing new services)

Personal data:name, email address

Withdrawal of consent:

You may withdraw your consent to process your personal data at any time.

Withdrawal of the consent is possible solely in the scope of processing performed based on the consent. Polidea is authorised to process your personal data after you withdraw your consent if it has another legal basis for the processing, for the purposes covered by that legal basis.

Categories of recipients:

Your personal data may be shared with:

1)       authorised employees and/or contractors of Polidea

2)       persons or entities providing particular services to Polidea (accounting, legal, IT, marketing and advertising services) – in the scope required for those persons or entities to provide those services to Polidea

 

Retention period:

1)       For the purpose of sending newsletter to the given email address – for as long as the relevant consent is not withdrawn

2)       For statistical, analytical and reporting purposes – for as long as the relevant consent is not withdrawn

Your rights:

 

Used abbreviation:

GDPR – Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016
on the protection of natural persons with regard to the processing of personal data and on the free movement
of such data, and repealing Directive 95/46/EC (General Data Protection Regulation)

According to GDPR, you have the following rights relating to the processing of your personal data, exercised by contacting Polidea via [e-mail, phone].

1)       to access to your personal data (art. 15 GDPR) by requesting sharing and/or sending a copy of all your personal data processed by Polidea

2)       to request rectification of inaccurate personal data
(art. 16 GDPR) by indicating the data requiring rectification

3)       to request erasure of your persona data (art. 17 GDPR); Polidea has the rights to refuse erasing the personal data in specific circumstances provided by law

4)       to request restriction of processing of your personal data (art. 18 GDPR) by indicating the data which should be restricted

5)       to move your personal data (art. 20 GDPR) by requesting preparation and transfer by Polidea of the personal data that you provided to Polidea to you or another controller in a structured, commonly used machine-readable format

6)       to object to processing your personal data conducted based on art. 6.1 e) or f) GDPR, on grounds relating to your particular situation (art. 21 GDPR)

7)       to lodge a complaint with a supervisory authority,
in particular in the EU member state of your habitual residence, place of work or place of the alleged infringement if you consider that the processing
of personal data relating to you infringes the GDPR
(art. 77.1 GDPR)

No obligation to provide data:

Providing your personal data is not obligatory, but necessary for Polidea to provide you the newsletter service

Refusal to provide the above data will result in inability to receive the newsletter service.

Profiling

In the process of providing the newsletter service, we make decisions in an automated way, including profiling, based on the data you provide.

 

“Profiling” means automated processing of personal data consisting of the use of your personal data to evaluate certain personal aspects relating to you, in particular to analyze or predict aspects concerning your personal preferences and interests.

 

The automated decisions are taken based on the analysis of clicked and viewed content. They affect the targeting of specific newsletter content to selected users registered to receive the newsletter service, based on the anticipated interests of the recipient.