This story is non fictional, but for security reasons, name of people and places have been changed to ensure anonymity. We don't laugh about security around here!

Also this whole story takes place in an Android app, which makes sense as there is "AndroidKeyStore" in the title... but I make that clear just in case.

In order to keep this short, I will not go into all the details of how a certificate work. So I guess you're supposed to know at least what they are and what they do.

Yes, I will attempt to keep this short, which is going to be difficult as I love to talk!

spoiler: check the solution/conclusion at the end of the article if you don't want to read the whole thing!

Story

So a little while back, I ran into this issue where I needed to store a few keys (read here "public certificates which are combined with a private sibling hidden somewhere on the vast land of the interwebs") received by this amazing channel called "an API".

The use I have for those keys (certificates) is irrelevant for this post, let's say I was doing some highly classified processing, way above your pay grade. So don't ask as if I tell you, I'll have to kill you.

Anyway, I received those certificates through an API and I needed to store them so that I can reuse them even if the app is restarted. For that, I use ... well ... a KeyStore. Sure enough, testing this out on my great Nexus 5, big Nexus 6, awesome Nexus 6P and trusty Nexus 9 (see a pattern here?), everything was working just fabulously. Then I got a bug report, a very detailed one, saying, and I quote:

it doesn't work on my phone.

Well it took me a while to figure out that:
1. I was using it wrong
2. I was not handling errors and exceptions properly (sometimes I'm lazy!)
3. The user's phone was running with Android 4.2 JellyBean (Level 17)

My Mistake

Well I didn't know much about KeyStore back then, I was young and inexperienced ... so I did what everyone would have done:
* I found a tutorial online (StackOverflow anyone?) that seemed to be doing what I wanted to do
* I did not read the whole instructions and just copy pasted the code
* I noticed that it was working on my Nexi, I was happy and we went ahead with the release

Well, it turns out that when you google Android KeyStore, you will find a bunch of tutorials that explain how to use the "AndroidKeyStore", which is nice, but through my personal research (and lack of reading the fine prints), I couldn't find one that actually mentioned that the "AndroidKeyStore" didn't exist before Android SDK Level 18 (also known as Android Jelly Bean MR2). And that's when my story really begins.

Note: the official Android KeyStore System page actually says very clearly:

the Keystore system is used by the KeyChain API as well as the Android Keystore provider feature that was introduced in Android 4.3 (API level 18).

So I should have seen this coming... yep, I should have...

The Android KeyStore System

And here is what I have learned since then:

So a KeyStore object is doing all sorts of security magic that I will not (read here cannot ;) ) explain right now. However I can show you some things.

Instantiation

You do not just new a Keystore, you summon its presence.

Keystore keystore = KeyStore.getInstance("AndroidKeyStore");

This is what you will see in most of the tutorials, which basically says "give me the AndroidKeyStore instance"... for the untrained eye. For the others, you will read "give me an instance of a Keystore of type AndroidKeyStore", which is a little bit different.

This on devices running Android versions below 4.3 will return actually barf a very lovely exception such as this:

java.security.KeyStoreException: java.security.NoSuchAlgorithmException: KeyStore AndroidKeyStore implementation not found
            at java.security.KeyStore.getInstance(KeyStore.java:119)
            ...
         Caused by: java.security.NoSuchAlgorithmException: KeyStore AndroidKeyStore implementation not found
            at org.apache.harmony.security.fortress.Engine.notFound(Engine.java:177)
            ...

This is quite clear isn't i? Well it is when you pay attention to the exceptions and you treat the handling properly. It says very clearly "sorry, but I don't know this AndroidKeyStore you speak of". Run the same code on a Level 18+, and it will be just fine and return an actual instance.

The AndroidKeyStore Provider

To make a long story short, the "AndroidKeyStore" string you pass to the KeyStore.getInstance() method tells the system to return the/an instance of that particular provider, which for my little 4.2 device has not been invented yet!

In short, the provider allows to declare some certificate storing mechanism in a way that is opaque to the client. some will like this, others won't. In this case, this provider is very secure, is app specific, handles its own persistance, maybe more?

In code, when you do something like the following, you don't have to worry about a thing.

Certificate cert = getMyVerySpecialCertificateFromSomeVerySecretePlace();
String alias = generateAnAliasThatMakesSense();
KeyStore keystore = KeyStore.getInstance("AndroidKeyStore");
keystore.load(null);
keystore.setCertificateEntry(alias, cert);

Well actually, you do have to worry about the potential exceptions that can be thrown, such as KeyStoreException, CertificateException, NoSuchAlgorithmException, IOException... Ho yeah baby, exceptions! Don't you love them?

But all in all, once you have done this, your certificate is stored in a very secure place that only this particular app can obtain.

So what about Level 17 and below?

Well I still had my issue that my app was to work on Level 16 and up, and I had code that could only work on Level 18 and up. So I had to find the "old way" of doing things, and here it is. For the same 3 lines shown above (I'm not counting the retrieval of the certificate or the alias), you have to do a little bit more.

First, you need to decide on what type of KeyStore to get. The type basically represents the kind of encryption algorithm used to encrypt the data in the store. you can find a list of the available types on the KeyStore reference page.

KeyStore keystore = KeyStore.getInstance("BKS");

Or

KeyStore keystore = KeyStore.getInstance(KeyStore.getDefaultType());

Then you need to open it properly like so:

FileInputStream fis = context.openFileInput(KEYSTORE_FILE);
keyStore.load(fis, PASSWORD);
fis.close();

And finally, you actually need to store the data, because this one won't do it for you... (don't be greedy now!).

FileOutputStream fos = context.openFileOutput(KEYSTORE_FILE, Context.MODE_PRIVATE);
keyStore.store(fos, PASSWORD);
fos.close();

... And everything else (containAlias, setCertificateEntry, deleteEntry, etc) works the same way.

The Conclusion / Solution

So basically, if you're lucky enough to only make minSdkVersion=18 apps, you really don't care about this. Otherwise, please understand that it is best to use the AndroidKeyStore whenever you can, and when you can't then go back to the dark ages. In other words you need some kind of a KeyStorewrapper that will handle that logic for you.

And surprise: I did it for you and it's free of charge!!! And you'll wonder how you could have ever survived without it (ok it's maybe a little bit too much there !) --> check this gist out.

I hope this article was useful, leave a comment if you have any remarks, enjoy the rest of your day.

Over and out!

A friend of mine told me about this app he'd like to have. It is a very specific need which probably very few people have → he needed a button that would allow him to start an email with pre-filled data (recipients, subject, etc), so that he could skip a bunch of taps and steps and be as efficient as possible to send himself memos by email.

I like efficiency, I am myself a very big user of such niche and specific apps, and thus I saw this as an opportunity to learn about configurable widgets, and I figured it would be a "nice app" to make as a base for an explanation as to how I went about configurable widgets on Android because frankly, in 7 years developing for the platform, I had never done any widgets before ... shame on me. Since, I actually have made another app with configurable widgets as well ✌ :).

So let's get started.

Foreword(s)

• The app is built on purpose with minimal dependencies:

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'com.android.support:appcompat-v7:23.1.1'
    compile 'com.android.support:recyclerview-v7:23.1.1'
}

• It is ugly (meaning not well designed), I know, it's on purpose (that's my excuse for lacking any kind of UI design genes)
• It's using the best practices that I know, feel free to correct me ... that is how I grow!
• It may be buggy, but it's pretty straight forward so it should be ok.
• It is assumed that you have basic knowledge and Android development to understand this post. Meaning you know how to start a project, what an activity is, and so on.

Where to start?

Step 1: widget's UI

First thing first, you have to understand that a widget UI behave just like any other type of Android UI with I'd say one exception: the size.

Indeed, a widget can have a fixed size, and potentially be expanded. If expansion there is, then you must adapt (or not) the UI accordingly. I will not cover this at the moment (sorry).

So first,you need the widget UI, which is a layout like any other layout file in an app, and it'll look something like this:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/layoutWidget"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:padding="4dp"
    android:background="@drawable/bg_widget"
    >

    <ImageView
        android:id="@+id/imageIcon"
        android:layout_width="40dp"
        android:layout_height="40dp"
        android:layout_marginTop="5dp"
        android:src="@drawable/ic_pen"
        android:layout_centerHorizontal="true"
        android:contentDescription="@string/app_name"
        />

    <TextView
        android:id="@+id/textLabel"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_below="@id/imageIcon"
        android:textColor="@color/widgetText"
        android:layout_centerHorizontal="true"
        tools:text="Label"
        />

</RelativeLayout>

So very simple, one icon on top, one label underneath, a bit of padding and an awesome background that allows for rounded corners ... super classy!

Step 2: the provider configuration

The provider will be the key to interact with the widget: it will manage its creation, update and deletion. It will be up to you to figure out a way to make it do that right.

First you must define the provider creating the AppWidgetProviderInfo with an XML file located in the res/xml folder that will be called widget_info.xml (for lack of more originality), and it'll look like this:

<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:updatePeriodMillis="0"
    android:resizeMode="none"
    android:previewImage="@drawable/ic_widget"
    android:initialLayout="@layout/widget_layout"
 android:configure="com.techyos.oneclickonemail.ui.activities.WidgetConfigActivity"
    android:widgetCategory="home_screen">
</appwidget-provider>

Explanation of the parameters (because I'm a nice guy, and you may deserve it!)
As per the documentation, the minWidth and minHeight in this case will represent a widget that is 1x1 columns on the screen, and it's not resizable (yes I know, I'm lazy), which is why resizeMode is set to "none".
Next, the updatePeriodMillis. It is not important in this case as it will manually be triggered for every change by the user, and the data cannot change on its own, so it is set to 0 to avoid useless system overhead and CPU churning.

The previewImageis the image that will be displayed in the widget picker area.
The initialLayout is the one we made earlier.
The configure points to the configuration activity, which is an activity like any other activity, and that will allow you to get whatever configuration you need from the user for that widget. You'll see later that you can re-use this activity in the regular app.
And finally widgetCategory (which is only available since api level 17 by the way, so take appropriate precautions) defines this widget to be on the home screen only and not the lock screen (which makes no more sense since api level 21 by the way).

Ok now that we have defined our awesome widget ... well we need to put together the stuff that will make it actually work. Which means --> CODE! (woohoo!)

Step 3: provider implementation

It's time for a little of real fun, enough with XML, let's do some Java (sorry Kotlin will be for a later post).

So in order to understand what the provider is, and how it works, you have to understand how a widget works.
A widget is an entity that works independently from an app. You cannot programmatically create or delete it from an app: that is up to the system, and to the end user, to decide to add a widget on the home screen, or remove it for that matter.
And if you want to interact with it from an app or a service, you need some kind of a communication channel, and this channel is the AppWidgetProvider.
In the previous step, we have created an XML file describing the behavior of the widget, the system will figure things out based on that. Now we have to let the system know what instance of the provider to use in order for the widget to live.

First, we need to ad a few definitions in the AndroidManifest.xml, starting with the provider declaration which actually is a BroadcastReceiver:

<receiver android:name=".ui.widgets.WidgetProvider" >
   <intent-filter>
      <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
      <action android:name="android.appwidget.action.APPWIDGET_DELETED" />
  </intent-filter>
  <meta-data android:name="android.appwidget.provider"
                android:resource="@xml/widget_info" />
</receiver>

Notice the intent filters, which basically tells the system to wake this instance up when a widget is updated (= also created) or deleted. Then, there is that line (meta-data) that says "and by the way, the configuration is in the xml file mentioned here".

Next thing, while we're in the manifest anyway, let's declare the configuration activity as well:

<activity android:name=".ui.activities.WidgetConfigActivity">
   <intent-filter>
      <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
   </intent-filter>
</activity>

Again, note the intent filter specifying that the activity will react to a widget configuration intent.

Enough with XML (finally)
So far, everything we have done have been "by the book". All of that can be found pretty much exactly as is in the official documentation. What is not defined in the said documentation is what comes afterwards.

The point of this article is to show how to make a configurable widget, which means you have an activity that allows the user to set some values that will provide a specific behavior for the widget.
We have declared this activity previously in the AndroidManifest.xml, as well as in the appwidget-provider XML, and the implementation of that activity is not very important as, I hope, you have already done tons of them. In this example, it is a simple form like activity that will write the data in the database using the received appwidget id as the key.

Now what is tricky is not the activity, it is the implementation of the provider, which we also have declared in the manifest earlier. And here is its implementation.
There are (at least) 2 methods to override in order for everything to work smoothly:

First, the onUpdate method:

@Override
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
  WidgetEntryDao dao = new WidgetEntryDao(new DbHelper(context));
  final int N = appWidgetIds.length;

  // Perform this loop procedure for each App Widget that belongs to this provider
  for (int i = 0; i < N; i++) {
    int appWidgetId = appWidgetIds[i];

    // Finding the widget entry for the app widget id
    WidgetEntry entry = dao.findByWidgetId(appWidgetId);

    if (entry != null) {

      // creating the intent with all the information we want to pre-fill
      Intent intent = new Intent(Intent.ACTION_SEND);
      // array of destination email addresses
      intent.putExtra(Intent.EXTRA_EMAIL, entry.getTo());
      // subject (optional)
      intent.putExtra(Intent.EXTRA_SUBJECT, entry.getSubjectPrefix());
      // little bonus, we're adding some kind of signature after the (optional) message
      intent.putExtra(Intent.EXTRA_TEXT, entry.getMessagePrefix() + "\n\n\n" + context.getString(R.string.signature));
      // and setting a type that will narrow the choice of apps that handle email related stuff
      intent.setType("message/rfc822");

      // creating pending intent, the flag is REALLY important, and so is the appWidgetId
      PendingIntent pendingIntent = PendingIntent.getActivity(context, appWidgetId, intent, PendingIntent.FLAG_UPDATE_CURRENT);

      RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
      // using main layout to handle the click, so the whole widget is a button
      views.setOnClickPendingIntent(R.id.layoutWidget, pendingIntent);
      // setting the label
      views.setTextViewText(R.id.textLabel, entry.getLabel());

      // updating the widget because
      appWidgetManager.updateAppWidget(appWidgetId, views);
    }
  }
}

Few details

• I won't get into details with the DAO, it is just my way of dealing with data on Android, I like the separation of concerns. Check out this file for more information.
• This method is called when a APPWIDGET_UPDATE intent is broadcasted. In our case it's when the widget is created, and when modification is made from the main app. Remember that we have set a updatePeriodMillis to 0, but had you set this value to some other number greater than 0, the intent would have been triggered by the system every that much milliseconds automatically.
• About the way to open a pre-filled email app on Android, there are several ways of doing it, I know of 2. The solution displayed may not be the best as it may show some apps that do not send emails in the app selection dialog. But it works, and I can set multiple recipients :).
• The biggest problem I faced was that if I had several widgets with a different configuration, they would all open with the configuration of the first widget. I finally found out about the PendingIntent.FLAG_UPDATE_CURRENT flag that is set during the construction of the PendingIntent instance, which saved my life. Also, the appWidgetId in there is not mandatory but will help to focus this particular PendingIntent instance with that particular widget and avoid weird behaviors. This is my version of a winning combination!

Second, the onDelete method:

@Override
public void onDeleted(Context context, int[] appWidgetIds) {
  super.onDeleted(context, appWidgetIds);

  WidgetEntryDao dao = new WidgetEntryDao(new DbHelper(context));
  final int N = appWidgetIds.length;

  for (int i = 0; i < N; i++) {
    dao.deleteByWidgetId(appWidgetIds[i]);
  }
}

Not much to explain here, other than the fact that the method is called when a APPWIDGET_DELETED intent is broadcasted by the system, meaning when the user is removing the widget from his/her home screen.
Basically here, I'm back again with my DAO object and I delete the widget corresponding to the received id from the database, that's it.
Note: if you try to broadcast this yourself in the app, the system will throw a very nice java.lang.SecurityException: Permission Denial exception because as stated in the documentation, this intent can only be broadcasted by the system.

Step4: What's left?

So now we have the widget's layout, the configuration, the provider ... what's left?
In our example, the widget is a button, and the button opens up an (email) app installed on the device. But a widget could do all sorts of stuff like displaying information, or sending data to a server, etc.

In this example, I decided that the main app could let the user change the configuration at will, and thus I have a list of all the widget configurations that have been written in the database, and with a tap on one of the list item, the configuration activity is launched again and fills the form entries the data corresponding data, save that data in the database once the changes are made, and then broadcast a APPWIDGET_UPDATE intent afterwards so that the whole update process will occur as the platform intended it to.

In another app that I have made, I didn't need any UI on click, I needed to send some information to a server through some REST API. In that case the provider was very similar, but instead of calling an activity, I was calling an IntentService instead. The PendingIntent construction code looked more like this:

PendingIntent pendingIntent = PendingIntent.getService(context, appWidgetId, intent, PendingIntent.FLAG_UPDATE_CURRENT);

Notice the PendingIntent.getService instead of PendingIntent.getActivity as we have used earlier. The difference is pretty self explanatory, but the flags and parameters are exactly the same.

So basically now it's up to you to decide what's next. Depending on your requirements, hopes and dreams, figure out what is the best course of action for you, I think you have all the pieces here.

Conclusion

Developing a widget is not complicated, it's just a lot of stuff and steps to do.
I find that the official documentation is lacking a bunch of details, such as the little tips that I've been giving throughout this post: the flags for the PendingIntent, how to communicate the configuration, how to call a service, etc.

Also, it is nice to have a proper understanding of how things are working ... it tends to remove a lot of frustrations :) So for instance, understanding the principle of broadcast receivers help with understanding the provider. Knowing about the intent mechanism also helps with the way we can communicate data across.

The full app is open source and completely available on github. Don't hesitate to clone it, fork it, do whatever you want with it.
Feel free to get back to me if I wasn't clear enough, if I made a mistake, if you found better ways of doing things, or to let me know that this was useful to you.
Thanks a bunch for reading, see you next time!

I've been working on Android development for a while now, I think I started tinkering in 2008 I didn't even own a compatible phone at the time.
I worked on a bunch of mobile project, mostly native Android, but also some with PhoneGap, and Titanium but really it's native Android that I liked the best.

So it's been 7 years, and lately for the first time, I actually have put my very app on the store. It was actually my first encounter with making widgets ... I figured why not put some ads in it and try to become rich?

So here it is: Fit DrinkUp!.
If you are a fitbit user like me, and you were annoyed at tracking your water consumption like me (that makes about 1 of us ... yes I know ... I should have researched the demand a little bit more), this app allows you to add pre-configured widgets on your home screen which will log the configured amount of water onto your account.

So I have learned about:

• configurable widgets
• how poor the widget documentation is
• how to put ads on a view (which is actually quite simple)
• that I might not have made the most profitable app for my first official!

This was indeed fun, and I will certainly make an entry in the near future with some more insights about widget making, and the difficulties that I have encountered.
In the meantime, go and try the app, let me know how you like it, send me feedbacks.

Over and out!