Author Archives: Muhammad

E-mail marketing & Amazon SES (Simple Email Service)

This is the age of social media. Our customers have myriad of different gadgets in the form of phones and tablets. But even in this day and age, e-mail promotions and marketing is still heavily used and relied upon. Do we need to delve and create innovative ways into sharing the promotions and marketing other than this? Is e-mail marketing still effective? In this post, let’s try to understand Amazon SES and understand the world surrounding i.e. e-mail marketing.

An auto-manufacturer has millions of car leases every year. At the end of each cycle a great number of leases are getting expired. This number can run anywhere from thousands to millions of cars in each cycle. We might want to provide our customers the opportunities to buy the cars they already have. Since there is a green revolution and we are trying to save the world by cutting as less trees as possible, ESPs (Email Service Providers) provide great opportunities to send these messages to our customers. This is definitely not about creating new customers but using the existing customer base. This is just one example, you might have some other business and you want to engage your customers through emails. In all these cases, ESP is your guy.

E-mail marketing and promotions is a type of Direct Marketing.

Amazon has a number of services for making our business processes and application development easier. In this post we will be discussing about one such service. This is Amazon Simple Email Service, more commonly known as SES.

Why do we need such a Service??

There are a number of email services available to send emails. If we need to send the same emails to multiple recipients, why would I use SES, when I can just send them through my email service including Gmail, Hotmail or Yahoo?

First of all, this is one use case of SES i.e. sending the same email to multiple recipients but this is not the only use case. We also need to understand that our assumption that I can send email to as many recipients I want, is not very true.

Personally, I have never opened any marketing email when it comes from a free service including hotmail, google or yahoo domains. If a marketeer can’t invest himself in his business by not even getting a new domain, I am not interested in them either. I am sure if you also behave the same. So for a marketeer to bring legitimacy to it’s marketing pitch, it has to come from a special domain. This is a loss of branding power for being a cheapskate.

Even if you compromise on branding, every email service provider allows a maximum number of intended recipients including To, CC and BCC fields.

For yahoo, such limitations exist but they are unannounced. But you can be axed pretty easily.

These services can also put further restrictions if they think the activities are suspicious. There are more restrictions for newer and unverified accounts.

The biggest concern for a marketing campaign is for the message to reach the target audience. With email marketing you have reached client but you don’t want to end-up in the SPAM folder. Actually SPAM folder is our biggest enemy. Client’s email services are on the look to catch emails which they could happily throw in client’s JUNK / SPAM folder. It is not only based on source addresses but also the contents of the messages. Working with an ESP like Amazon’s SES, this can be reduced as they establish trust with the popular email providers.

ESPs also help us determine the effectiveness of the marketing campaign by providing reports about bounces (recipient account doesn’t exist) and complaints (Mark as spam). Amazon SES, not only provides a pretty interface to view the information, this can also be forwarded through SNS (Amazon Simple Notification Service). Now Delivery Notifications are also supported by SES.

Based on the above discussion we can safely say that we need an ESP for our marketing and transactional messages.

Sending Emails through Amazon SES

The easiest option for sending emails is through AWS Console. But this is a very simple interface. This is generally used when we are still in the Sandbox environment and don’t yet have production access. If you are already using an SMTP client, you can configure that to use Amazon SES for sending out emails destined to your intended recipients. But remember that Amazon SES just has an outgoing server and no incoming servers are provided. This can be a standard SMTP client e.g. Microsoft Outlook. This can also be a custom STMP client with SMTP support.

We can also write custom applications to interact with Amazon SES using Amazon SES API. In order to do that we can simply use AWS Command Line Interface and AWS tools for Windows Powershell. We can also directly use HTTPS based SES Query Interface. Additionally, AWS SDK provides a wrapper around this API. The SDK is provided for different platforms including Android, iOS, Java, .NET, Node.js, PHP, Python, and Ruby.

Is there a competition, and where does SES stand?

Amazon SES is not the only solution for email marketing. It is also not the first one. There are a number of ESPs, which provides email solutions. Some of them are as follows:

Main Features of ESP (Email Service Provider)

Looking at the available service providers, there is a general set of services we should be expecting an ESP to provide. They are as follows:

Sending Bulk Messages through Email

This is the very reason a marketeer organization use an Email Service Provider. The message is expected to reach a bulk of intended audience through emails. ESPs provides creative pricing plans for sending these messages. Generally the cost incrementally increases as the number of recipients increase. They also include a free-tier up to a certain number of messages in a specific duration.

Delivery, Bounce and Complaints Notifications

The recipients ISPs respond with bounce and complaint notifications. Complaints are generated when a user hits SPAM button for your email. ESPs provides feedback analytics to marketeers about delivery, bounce and complaints. Since specific email addresses are included in the report, it can help the marketeers determine how they want to deal with the specific recipients. You might want to simply opt-out those customers and remove them from the list. It also gives a general sense how their campaign has been received by their target audience.

Auxillary Email Services for Marketeers

Inbox Vs Junk Folder

EPS allows us to run our marketing campaigns through emails. So the marketing messages reach to the clients proximity, which can be read at the client’s own convenience. But we never want to end-up in the SPAM / Junk folder. Now just try logging-in to your email account and open Junk folder, do you see how many marketing messages end-up here. Nobody runs a campaign just to end-up in the SPAM or Junk folder, but they do end-up here. How can we improve this and find our way to Inbox instead of Junk folder?

The truth is that nobody can provide this assurance but there are steps which can be taken to improve our chances to reach the Inbox folder.

Previewing Emails in Different Clients

Your e-mail message is supposed to be received by thousands of current or prospective customers. A marketing message is created very carefully so that the correct message reaches to the audience. In order to test how message would show up in different e-mail clients including blackberry, iphone, android, we need to preview it. There are a number of products in the market providing this service. One such service is from litmus.com.

Return Path also provides a similar service. Their product is called Inbox Preview.

Email Certification and White List Senders

Certified emails bypass the spam filters. So, this seems like the best option to end-up in the customer’s Inbox. But how to certify an email plus is there any concept of trusted senders?

Email providers allow creating lists of senders for their customers. They allow adding a sender to blacklist easily if the recipient doesn’t want the sender’s emails in the inbox and filter out to the SPAM folder. But before applying customer’s filters, an email has to go through the email provider’s filters. The email providers have black and white lists of their own. The black list is generally created based on the historical and current email trends for the particular sender. They also have a white list, you have to pay, plus there are different standards and requirements you have to follow to be added to the list.

There are also third party white lists. This would save you from separately negotiating with individual email providers. It’s the white list provider’s responsibility to do all this work. They charge you, and have agreements with the ISPs. One such example is Return Path’s white list and certification program.

Reputation monitoring and Sender’s Trustworthiness

As we discussed ISPs have a black list of senders they use to filter out messages before placing it in customers’ inbox. The black list is also based on senders IP addresses. It is very unlucky to be there but they might have received emails from the specified email address, which they consider SPAM like.

ReturnPath has this amazing service called Reputation Monitor. They have a list of blacklisted IP addresses which seems to be generated from various ISPs. Based on this data, they provide a number to the reputation of sender. They call it Sender Score.

The score is based on IP address. You can see the sender’s email address and how it has been treated by your ISP.

Email Authentication

You might be wondering what is being authenticated here. It is to authenticate the sender of emails. It verifies that the sender is really what it actually claims. There are a number of protocols for email authentication including SPF and DKIM.

http://en.wikipedia.org/wiki/Email_authentication

DKIM stands for Domain Keys Identified Mail. It uses digital signatures. Sender Policy Framework (SPF) links sending email’s domain to the sender’s email address. If the mapping exists as expected by the framework, this is considered an email sent by a legitimate sender. You can read more about SPF here:

DMARC standardizes how email receivers perform email authentication using the well-known SPF and DKIM mechanisms. It considers both SPF and DKIM as a combined authentication method. You can read about DMARC here:

Regulations around Email

There are a number of federal and state regulations around email space. One such regulation is CAN-SPAM which stands for Controlling the Assault of Non-Solicited Pornography and Marketing (CAN-SPAM) Act. You might have other regulations based on the contents of the message e.g. HIPAA for medicare.

GitHub Contributions – Move heavyliftings to Service

This is a continuation of a post for building an android app for displaying GitHub contributions of a user. We are pulling down profile and repository details of the user. As we are adding features to the app, we have been learning about android and its development model.

Currently we are at the point that we can download the data asynchronously and display it on the UI. We can also change user and the data is downloaded for the new user. In this post, we want to build up on this by moving all the heavy lifting for downloading the data to a background service.

What is Service?

Services are used to run a long-running operation in the background without affecting app’s responsiveness. Services are faceless i.e. there is no UI for a service. They can be used to download or process information. They also can provide feedback to the app. Services can be used by more than one app.

The lifetime of service can be independent of the app launching the service. They can also be bound the apps and die as soon as the number of apps bound to the service drops to zero. There are two non-mutually exclusive forms of service:

Started: In this form, a service is invoked by calling startService(). In this way a service can run indefinitely. We will be using our service in this form as we want to keep the data current by downloading it periodically every 3 hours.

Bound Service: This form is used for the service designed for client / server operations. They are used when an application needs to delegate some actions to the service and needs results back. An application uses bindService() to use a service in this form.

A service can be public or private. A private service can only be used by the app providing the service. On the other hand, a public service can be started by any app on the device using Intent.

Android Service & Threading

A service is invoked in the main thread of app hosting the service. But we can start a new thread in a service to run the operations in a non-blocking mode. In our case, we will keep our operations in AsyncTask for downloading user profile and repository data.

Service Lifetime

Showing Loading… before downloading data

Since we have decided to move the logic for downloading data from activity to a background service, we need to show some info to the user on the screen. Let’s keep it simple and show the text Loading… on UI.

Now if the user is not connected to the network and no data is available then we can show Not Connected… message. We included a separate resource definition for this message previously. Even if old data (older than 3 hours), we can still show this data to the user. In case, user is connected to the network and data is current (less than 3 hours old), we can just show this data. If the data is not current, then we can download the data and show it. The following is the resource definition:

The service needs to periodically download data from GitHub in order to keep it current.

GitHub Contributions App States

There are three states of our app. These states are as follows:

Loading
Not Connected
Connected

There are few state transitions allowed. When the application is launched, it is in Loading state. In this state, it starts the service. As many times the service is started, it generates a connectivity intent to notify the starter with the state of network connectivity. This transitions the state to Not Connected or Connected.

The Connected state is kind of misnomer for network state. It is not network state. It is to show to the user that there is some data available to be shown on the screen. This might not be the most recent data if the device is currently not connected to the network. And if the device is not connected, I don’t think that the user concerns a lot by looking at the most recent and updated data.

The Not Connected state is only available when there is no suitable data available to be shown for the user set in the preference settings.

Service Vs IntentService

All android services inherit from Service. You can create a service type by directly inheriting from Service class. This allows multiple simultaneous use of the service in a multhreaded-multirequest scenario. But if your service is not expected to be used simultaneously (as is the general case), then you can extend IntentService (which also inherits from Service).

IntentService uses a work queue to handle requests in a serial fashion. It uses a single worker thread to handle all the requests. The request’s Intent is provided in the onHandleIntent() method, we can use it to pull the required parameters.

But IntentService automatically stops itself when the work is done. We want the service to be running even if the app terminates, so IntentService shouldn’t be our first choice in this case. Instead we can create a simple service inheriting from Service type. IntentService also inherits from Service.

Running Service when device starts up

There are a few things we need to do to startup service at device startup. They are as follows:

– Request permissions to handle device startup intent.
– Registering service description in AndroidManifest.xml.
– Handler to handle the startup intent so that the service can be starteup
– Definition of broadcast receiver and its registration in AndroidManifest.xml

Since a service cannot be directly started, we need a BroadcastReceiver to start the service. The receiver is registered with intent-filter to handle the device startup intent.

Using Intent to pass custom objects

We can add information to Intent, which can be pulled by a receiver. The added info is called Extra. There are a number of putExtra() overrides in Intent to add extras of various primitive types. In order to add custom objects, it becomes a little more challenging.

Since intents can be received by outside process, we cannot really expect the other process to have same type definitions. In order to pass an object of a custom type, there are a number of options.

First, if an object is serializable, it can simply be added as an extra. So implement your type as serializable, you should be good to go. You must realize that you wouldn’t be getting the same object on the other side but a serialized copy of the object. When you would deserialize it, this is a new object created on a different place in memory.

You can implement Parcelable for the type. Read more about Parcelable.

The easiest option is to serialize it using Json. Since we are already using Gson in our project, we can simply serialize it using Gson. On the other side, we can deserialize the Gson back to the original type.

Passing Data from Service to Activity

In our case we have an activity (GitHubCardActivity) and a service (GitHubSyncService). When the app is launched, the activity can start a service if it is not already running. This should also be the case when the app is launched on a device. In the other case, the service should also be started when the device starts up (when no activity is yet created). So service doesn’t know if there is a corresponding activity interested in the data just downloaded. In this case, Intent makes our job a lot easier as we can generate the Intent from the service, if there is a corresponding activity interested in receiving the data, receives it. In order to keep this responsibility separate, let’s create a BroadcastReceiver.

A BroadcastReceiver can receive broadcasts for a number of actions. Here we are using GitHubCardActivityReceiver to receive broadcasts for UpdateConnectedStatusAction, UpdateUserProfileAction and UpdateUserRepositoriesAction. These broadcasts would be generated from GitHubSyncService as we have already seen in the above code.

Instead of the whole JSON path, we can simply push that data to the storage anytime we download the info. We can always read the info in our service from storage. This would save us the conversion time and make it easier for us to read from storage (which we already have the code for). So let’s keep it simple in our case.

Updating Connectivity Receiver

The connectivity receiver also needs an update. Since service can run independently of the activity, it can be updated to notify the service of any changes in network connectivity.

We have also registered the BroadcastReceiver with the service. We are registering it for the intent ConnectivityManager.CONNECTIVITY_ACTION.

Service Creation Vs Start-up

A service is only created once. As it is created, its onCreate() method is called. We can override this method to perform the one-time things important for a service. This includes all the initializations required. Every time, the service is started, its onStartCommand method is called. Here is the definition of these methods for our service.

Get it from Git

Android Development – Offline Support

This post is amongst the series of post for discussion about development of an App in Android Platform. We have been developing an app, named GitHub Contributions as an example. In each post, we keep adding some new feature to the app, which adds to our knowledge about android.

In this post, we are going to see how we can add offline support to our app. So if a user has launched our app and there is no internet connection available, we cannot download user profile’s data from github.com. In this case, we can show any previous data downloaded for the specified user. If we are running the app for the first time for the user, then we can just show a Not-Connected message on the screen. As soon as the user connects to the network, we can attempt to download the information and show the pretty view.

What to display when not connected?

Developing Offline support for your app, also includes how to notify user of no connectivity. Since the regular view needs the actual data to be shown, it doesn’t really make sense to still load the whole view with empty data. I think the better option is to display a simpler view with details about inactivity and if there is anything a user can do to fix it.

In order to keep things simple here, we are just showing a message to the user. It should say “Not Connected!”.

Checking Network Connectivity

We can use ConnectivityManager to determine network state. In the code below, we are checking if the device is connected to a network. We can use Context to get the ConnectivityManager object from system. It is registered as a system service CONNECTIVITY_SERVICE.

Since we are periodically downloading user data after every 3 hours. We need to register for connectivity changes to allow application state based on the connectivity. A BroadcastReceiver can be registered in a Context for the specified intent. Here is the definition of ConnectivityReceiver.

When the connectivity changes for the device, onReceive() would be called. Here we are using the same connectivity service to determine the current state of connectivity and updating the Activity about this.

Simulator & Checking Network Connectivity

If you are debugging your app in a simulator then the NetworkInfo would always consider the phone to be connected. In order to test the connectivity logic, we can put the phone in Airplane mode. In this case, the layout definition for “not connected” state would appear as follows:

Permission to Access Network State

Now if we run the application as is, we get the following exception when we try to get the state of network.

Actually we need to request permissions for accessing network state in AndroidManifest.xml. We can define it as following:

App Startup

When the app starts up, onCreate() is called. Here we need to decide what information we need to display to the user. It is also the the usual place to set the layout resource definition xml to be used for the activity. In our case, we can determine, if the user is connected to the network, if so, we can use the older logic to download user information only in the case that the user information is not current i.e. downloaded less than 3 hours ago.

We have also updated to loadUserDetails() to relax the 3 hours requirement for using the user’s data from persistence. If the user is not connected, we can show the older data. On the other hand, we wouldn’t use older data if the user is connected and would download the fresh data at app startup.

Changing modes with Connectivity changes

Since our app can be used in online and offline modes, we need to update the app state when connectivity state changes.

Get it from Git

Android Development – Scheduled Execution

This is a continuation of our post discussing different areas of android development. We are getting introduced to android development while developing an application GitHub Contributions App.
There are a number of ways we can delay processing of some work in android. It also allows us to execute these work items on a periodic basis. There are a number of options for an android developer for introducing scheduled execution.

Refactoring the code

Before we start scheduling the work, we know that the scheduled download would involve getting the online data. Our current AsyncTasks would not support so. They would check if we have recent data in the files and would provide the data stored in file to the activity. So we need to refactor the code to separate the data load from internal storage and online. Let’s first create these base classes. They would be extended by their specialized classes for internal storage and online.

Here are the extended types to support loading user profile information from online and internal storage. The online version, in addition to download information, also serializes the info.

Similar should be the implementation for specialized types for repository data. It also has two types to download the same details.

When to load information from Internal Storage

We should remember that we only need to load information from internal storage when the application is launched. After every periodic load of information every three hours, it is download form online github profile of the user. Let’s introduce a boolean flag isLoaded. The flag is initially reset. After the application is loaded by finishing execution of onCreate(), the flag is set.

We have also updated the definition of loadUserDetails() to use this flag. Since the same method is used for initial and all the subsequent load of information, the above code should ensure that the async tasks loading information from internal storage are only used the first time. They would also not be used when the information in the internal storage is not current.

Using Scheduled Executor Service

There are number of options available for periodic execution of code in android. ScheduledExecutorService is one such option. It provides options for these executions at fixed rate or intervals.

We can use Executors type to get an instance of ScheduleExecutorService. Executors is a type available in java.util.concurrent package. It provides factory methods for Executor, ExecutorService, ScheduledExecutorService and ThreadPoolExecutor.

Other Options for Delayed / Periodic Executions in Android

Android has a number of other options to post a single or periodic executions of some code block. Let’s briefly discuss some of them.

Handler

Handlers are used to delay the execution of some code and post it after the specified delay. It can also use a HandlerThread to support executing on a different thread.

There is no associated message loop for a thread. Looper can be used to create a message loop for a thread. HandlerThread provides a message loop which can be used by Handler instance.

Since we don’t just need to delay the execution butt we need to introduce periodic execution, we have avoided using Handler type for our case.

Timer

If you are coming for a non-android platform, then this is the first option you would think about for scheduled execution. There are a number of timers you might be used to in C#. You might want to dig for single and multithreaded timers. We can introduce timers to delay processing of some work (one-shot) or performing it on a periodic basis (recurring). They can also be fixed-period or fixed-rate. The former ensures every-next execution to start based on the start time of the previous execution, while the latter would just fire-off every time the duration lapses without any consideration of possible delay starting the previous run. There are a number of schedule() methods available in the Timer for choosing among these modes.

Timers can be created to execute on a user or daemon thread. For .net developers, they are respectively similar to foreground and background threads.

It must be remembered that Timers are not recommended for newer development using Android. Developers are encouraged to use ScheduledThreadPoolExecutorService.

Alarm Manager
AlarmManager can also be used to execute some code block at some later time. It can also be used to execute it on periodic basis. But this is more system wide approach. Beginning API 19, Alarms are also not exact. Details here.

Get from Git

GitHub Contributions – Add File Storage

This is a continuation of a post for building an android app for displaying GitHub contributions of a user. We are using name of user for pulling down profile and repository details of the user. As we are adding features to the app, we have been learning about android and its development model.

Currently we are at the point that we can download the data asynchronously and display it on the UI. User can also change user and the data is downloaded for the new user. In this post, we want to build up on this by adding the following:

Keep the data in a file so that when the app needs it it can just be pulled from a file rather than being downloaded from the web. This can also cater to the offline scenarios when the app is launched while being disconnected from the network. We also don’t need to download data if the app is launched within 3 hours of when the data was downloaded last time.

Since a picture is worth a thousand words, let us try to depict the storage model for android apps.

There are basically two types of storage available for an android app. They are internal and external storage. Here internal storage is an always available storage with the contents only visible for the app under consideration. Au contraire, the contents of external storage are accessible to other apps plus it may or may not not available. An uninstall removes all app data except the data specifically in the public area of external storage.

Since we don’t need to share GitHub contribution’s data with any other app, we will be keeping it in internal storage. The data would include profile and repository data for a GitHub user. In order to make our life easier, we will be keeping the data in JSON format.

Adding Serializer

Let’s add a serializer to manager persistence of profile and repository data. The responsibility of serializer is to serialize / deserialize profile and repository data. It also needs to check if the files are current. The definition of current in our system is that it is not older than 3 hours.

Checking if Data is Current

In order to avoid frequently download the user information, we have decided to keep it in a file storage. We need to check the file’s last modified date for our decision to download. Now this would require comparing the last modified date of file to the current machine’s time. Here we are using Calendar to get the current time. The literal integer value is the number of milliseconds for 3 hours. So if the duration is lesser than 3 hours, it is OK to get it from persistence. In order to keep things simpler, we are just checking for file to save repositories data.

Serialization Data Format

In order to serialize we can simply convert the data in to byte[]. We can then push the byte array to internal storage using FileOutputStream. We would be creating this after serializing it in JSON format. We can simply read data using FileInputStream. Here is the code we are using to save data to internal file storage and getting the data from it.

As discussed above, data is being converted to JSON format before sending it out to the storage. For our project, we are using GSON library for this conversion. Earlier we have discussed how we can add a JAR library to a project in Android Studio.

Since we have bitmap data in the profile, we are creating a memento for holding profile data excluding avatar’s bitmap. The bitmap is saved in a separate file.

Download Vs Load from Internal Storage

We have separate AsyncTask (s) for providing the profile and repositories data. Currently it just downloads it. Here we can make a decision to download it only when data is not current. Following is the code for providing profile data. It is using the same isPersistedDataCurrent from PersistenceHandler to check if data is current.

And we have similar code for repositories data.

Get code from GitHub

Android Studio – Adding Library to your Project

In this short post we will be learning how we can add a JAR library to our project in Android Studio. Here we are using Android Preview 0.5.4 edition.

Let’s use Gson library. This is used to serialize / deserialize java objects to JSON format. Please see the license requirements before using in your project.

Just download it from the above location from Google Code and copy it to the lib folder of your project. As you copy it to the folder you would see this dialog opened. You can just hit OK here.

We need to update the build file (build.gradle) to include the lib for building the project. You don’t have to worry anymore as Android studio now includes everything form the lib folder now.

Now just make sure that you clean the project before using the types from the library.

GitHub Contributions App – Creating Hyperlinks

This is a continuation of our posts adding features to GitHub Contributions App. We have been developing this app on android. The app allows loading some important details from the profile of a github user including the repositories list. The information is provided by GitHub through HTTP Service.

In this small post, we will be updating the blog address to a hyperlink. You would be amazed to know that there is no separate View type in android for hyperlinks.

We add the hyperlinks using the same TextView type. We can create hyperlinks for web-links, maps, email and other types. Clicking on the hyperlink text would open the corresponding apps selection registered for this. These are the default types supported to include hyperlinks. This is similar to applications registered for particular URI scheme in microsoft’s world [See this].

We just need to update the definition of TextView with the particular type of link. Since we are interested in opening the user’s blog in a browser, we need to select web here.

Now let’s update the code and start debugging it again using the same emulator.

You can see that the blog address is updated as link. As we click the link, the browser opens up the blog.

Get it from GitHub

GitHub Contributions App – Android App Preferences

In the previous post, we started creating GitHub Contributions App for Andrdoid. We saw how we can access HTTP REST Service using HttpClient, how we can update permissions specially to access network resources, plus the details about performing actions on background thread while showing the result on UI thread. We also saw how we can define string resources and use them in our code and layout definition.

In this post we are continuing with the app. We will be updating the action bar from default to custom. Currently, you can only see author’s GitHub contributions. We will be providing a setting to change GitHub user. The feature will be provided by adding an action bar button for settings.

Creating Icon

We can use Android Asset studio to create icons from clipart. You can find it here:

Here we need an icon for settings. Let us use this clipart to create icons:

It allows creating icons for different resolutions. We can download the icons as a single zip file and copy them in the respective folders in our project. We can then reference these icons as drawable resources.

Action Bar Button for Settings

Let us first add a resource directory to hold the definition of action bar. Now we can add a menu resource to the directory.

We update the contents of the menu resource to include settings menu item. Here we are using the icon we created above. There are three possible options for a menu item to display in action bar. They are as follows:

never
always
ifRoom

Since we just have one menu item, we are always showing it.

Now we need to hook up this menu to the activity’s action bar. We add a menu resource to activity’s menu in onCreateOptionsMenu method. In order to associate activity’s action bar with menu from the resource file, we use MenuInflater obtained using getMenuInflater for the activity.

When an item is selected from the menu, the framework calls onOptionsItemSelected method with the menu item selected. Since we only have one menu, we have a simplified implementation of this method. Here we are just calling openSettings method. We will be providing the definition of this method later in this post.

Defining Preferences

Now we need to allow user to enter userName of the github contributor we are interested to see the profile of. Android provides a whole API around preferences. These preferences can be local to the application or they can be shared with other apps. We can also provide a read-only or read/write access to other apps.

Since we just need a single preference to store the user name, we just need and EditTextPreference, this would show a TextView to show and update the value of the preference. Here we can provide a default value, title and summary information for the preference. The key can be used to later get the value of the preference. It must be remembered that Android preferences are stored as key / value pairs. Let’s update the contents of the xml with the following:

Create Settings Activity

We need to create an activity to display preferences. We use PreferenceActivity for this purpose.

In order to keep things simple we let’s update the contents of the file containing the activity definition. Here we are using addPreferenceFromResource method from PreferenceActivity. The method is deprecated. In some next post, we will try to update this with the newer recommended approach. We can pass the preference, we created above, to the method.

The preference API revolves around SharedPreference. It provides storing and retrieving data in the form of key/value pairs.

Adding Settings Activity to GitHub Card

Now the stage is all set. We can add the Settings activity to GitHub card. In the openSettings() method we can start this like any other activity i.e. we can create an Intent for the activity, then we can start it using one of the methods provide by Activity. Since we need to load the view again with the updated user name, we are using the overload startActivityForResult. This would make sure that the framework calls onActivityResult method when the activity returns.

Here we have moved the part where it loads the user profile and repository data to loadUserDetails() method. The method is being called from onActivityResult() method. We have also updated activity’s onCreate() to use the same.

You might remember the preference definition where we used pref_loginName to store user name. Here we are using the same to retrieve the value. If there has never been a value saved for the key, it should return the default value “msiddiqi” which is the github profile name for the author of this post. PreferenceManager is used to get the SharedPreference for the activity.

After retrieving the user name, we can use the same AsyncTask (s) to load user profile and repository details.

Running the App

Before running the App, let me tell you that we can capture the virtual / real device under debug using DDMS.

As we run the application, we don’t have any value for the specified key in the preference, so it should return the default value “msiddiqi”. In the onCreate method, it should use the default value to load user’s GitHub profile details.

Now open preference activity by clicking the Settings button in the action bar. It should open the view for SettingsActivity. As the activity is defined it using preferences defined in preferences.xml. This just includes EditTextPreference for user name. Selecting the preference opens the last saved or default value for the preference. Let’s update the user to paulcbetts. Paul is the main contributor to Reactive UI framework.

After updating the user as we head back to the main activity, it should load the profile and repository details for paul. The view is updated as follows:

This should be the same view if we exit the application and launch it again.

Download Code from GitHub

GitHub Card Android App

In this post we will be proceeding with the app development for our GitHub Card App. Here we are targeting android audience. This is the wire frame we designed for our card App.

App Wireframe

Since this is a wireframe, we don’t have to match it exactly but we will try to keep the layout as close to this as possible. It would be tricky to get the number of total commits so we will be ignoring this for now.

GitHub API

GitHub provides users’ and repositories’ data through REST based HTTP services. It is currently version V3 of the API. The details about the api can be found here [https://developer.github.com/v3/]. We can test our requests using Curl as follows:

Creating GitHub Contributions Android Project

Let’s use Android Studio for our development. You can download the tool here. We are naming the project as GitHubCard.Android. The project is being targeted for API 19 (KitKat).

Here we are using a clipart as an icon for the app. Let’s pick a simple clipart from the gallery.

Since we selected the option “Create Activity” in the first page of the wizard, we are asked about the type of the activity. Let us select a empty activity.

Now we need to specify the details about the activity. It includes activity and layout name for the activity.

And that completes the wizard, we have our project created in the workspace. It appears as follows:

There are two folders which are of special concern. They are src and build folders. Here src folder contains project’s code including layouts. The type “R” is of special importance in an Android project. We can find it in build folder.

Android Permissions

In order to access GitHub user profile and repository data, we need to have access to internet. This would require our app to require permissions to access the network. We need to declare this in AndroidManifest.xml of the app.

What is Activity in an Anrdoid App

Activities define the interface display for an android app. Its layout and behavior are defined separately. We can define a layout for an activity or an app widget. If you are coming for a XAML background like me, you must be used to define the application view in XML. The mapping of an activity layout to an activity is defined in activity definition using tools:context. Here tools is the namespace, “http://schemas.android.com/tools”. In the java code we can define the content-view for the activity of interest. Here we have the onCreate() definition of our card activity.

So anything we want to show on the UI, we create an activity for that. As we just discussed, an activity is bound to a view defined in XML so technically, we can bind more than one view to an activity but this is generally not recommended. There are a number of overloads of setContentView method.

An activity has a single thread i.e. UI thread. The activity currently being displayed is referred as Active. Creating multiple activities doesn’t create new threads as only a single activity is active at a given time.

Activity Designer
An Activity can be mapped to one or more layouts. These layouts are defined res/layout folder for an android project. We generally specify the layout of an activity using setContentView method in onCreate method.

This is like Microsoft’s XAML technologies where views are defined in XAML, which is based on XML. The behavior is defined outside the layout definition in view models. Android layout is also defined in XML. For convenience, we can use the Activity Designer, which makes it easier to generate this XML.

Double clicking a widget enables us to change the orientation and Id of the selected widget.

This is the layout definition for our GitHubCardActivity. It is a simple layout with a few TextView(s) (for name and other info) , ImageView (for profile picture) and ListView (for showing the list of user’s repositories).

You can notice the strings being referenced as strings/id. This is a reference to strings.xml containing the definitions of these strings. We can find the file in res/values folder.

Downloading Profile and Repositories Info

Downloading the profile and repositories info for the user is the most important part of the development for this app. Let’s first create an interface type to hold information for user’s profile data. We are naming the type as GitHubProfileDetails.

And here is the interface type to download profile and repositories data. Since we would be accessing the network, we might need to handle IOException cases. All the data is returned in JSON format by default. We might run into issues while formatting the JSON data causing JSONException. The calling code must handle these two exceptions.

Here is the implementation for GitHubProfileDetails. Here we are using the URL from the profile data returned to download user’s profile pic. Just make sure that this is being constructed on a non-UI thread as we cannot access network on UI thread in android.

And here is the implementation for GitHubProfileDetailsDownloader interface. Since we can use different approaches to download this data. We are deliberately keeping this type agnostic to the particular approach used. The profile’s data is downloaded as JSON. Here we are parsing JSON and creating a GitHubProfile instance. Similarly we are getting the repositories’ data and returning it to the calling code.

GitHub Repositories List
In order to show the list of user’s repositories we are using ListView. This is used to display a list of scrollable items. This is how we are defining it in activity_git_hub_card.xml.

Please notice the id here. We will be using the same id in activity definition to access the element to bind it to user’s repositories data using R type.

In android, we use Adapters to bind data to ListView. It also provides sorting and filtering capabilities. Let’s look at the inheritance tree of ListView type. All elements which inherit from AdapterView can use adapters. From the definition, we notice that it supports ListAdapter, which is an interface type. Based on Liskov’s substitution principle, it must also support all implementations of the interface.

Here is the code, we are using to create an ArrayAdpater from the data returned by GitHub API. Since we are just interested in the name of repositories, we are just passing them to this method. After creating an ArrayAdpater for the data, we are just setting the ListView’s adapter.

Just note that we have added this method in GitHubCardActivity. We also need to make sure that the method is being called on UI thread, which is obvious here since we are calling it from onPostExecute of AsyncTask.

Loading Image from GitHub Profile

ImageView doesn’t allow directly setting a web Uri to load image. We need to explicitly load image and assign it to the imageView source. We should remember that we are required to download this in a non-UI thread to avoid the InvocationException. Here we are using URL to create an HttpConnection with the image source. We are then getting the InputStream from the connection. BitmapFactory allows us to create an Bitmap from an InputStream.

Since URL’s constructor can throw a MalformedURLException and HttpConnection.getInputStream() can throw an IOException, we need to catch them.

After downloading image and other profile data, we need to show them on UI. In this method we are providing the data using GitHubProfileDetails type. Since we need to show name, blog, date of creation and number of followers’ data in a certain format, we are using String.format for this purpose. ImageView cannot use a web URI, so we have downloaded the whole bitmap, now we just need to set the bitmap as the profile picture.

AsyncTasks for Profile and Repositories’ data

Since we need to download data on a non-UI thread (because of android’s restriction of network access on a non-UI thread) and populate UI elements on a UI thread (android’s restriction for accessing the UI elements only in UI thread), AsyncTask is ideal for this purpose. We can download the profile data first, get URL for repositories and then download the repositories’ data. But since the URL for repositories’ data is also standard one, I think it should be fine if just directly use it and download this in parallel to the profile data.

Below we have introduced two AsyncTask (s) to download user’s profile and repositories details. If you are coming from a Microsoft’s background, AsyncTask (s) are very similar to BackgroundWorker. They allow some processing to be done on a background thread. During the processing, we can report progress of the operation which can be used to update UI. After completion of task, it executes onPostExecute() method.

Unlike Microsoft’s BackgroundWorker, it doesn’t provide any event for progress publishing and task completion but it provides other overridable methods for this purpose. This makes it difficult to pass the data to the UI Activity which can be fulfilled by providing callbacks. Here we are providing two child types for AsyncTask. We are expecting the GitHubCardActivity to be passed as constructor’s arguments. We are using the provided instance to use callbacks once the required data is available. In the callbacks (discussed above), we are updating the UI.

Running App

Now let us run this app. We can use a virtual device for running this. Here we are using Galaxy. This is the output of the app.

Download Code

You can download the app from GitHub.

A Simple Android App for learning

In my talk about options for development for google glass, I briefly discussed about Android studio to be an option. In this post, we will not be discussing about glassware development though. We will be focusing on creating a simple android app. Since this would be our first one, we would like to keep the discussion as simple and straight as possible.

The App should just have a button and a number. Clicking the number each time should increment the number on the screen.

Let’s open our Android Studio and create a new project. Let’s name this project as IncrementerApp. Let’s keep the default options selected here. If you have a .net development background, like me, this first screen does confuse us. There are so many platform versions asked. In our .net experience, we just have one version to care about. That is the version we develop against, and that is the version we expect our customer to be running our application against. But don’t be confused, just get in the water, it will be just fine.

Now let’s move to the next stage of the project creation wizard. Here we are adding a blank activity. We don’t want any additional features added to the activity here.

Hitting the Finish button would create the activity with default definition. Now for our activity, we should specially be careful about two files. They are IncrememntActivity.java and activity_increment.xml files. It has picked up the name for xml file from the casing of the name of the activity. Here you should know that all the activities should have these two files. The java file defines the behavior of the activity, while the xml one defines the activity layout. Since each activity is something that we want to show to the screen, it must have a layout, generally only one.

Let’s add a Framelayout the activity layout. We add a TextView and a button to the layout as follows:

You might have noticed the button’s content as Increment. Now Android is very good at providing a framework for resources from the ground-up. There are already existing resource files for different purposes. Here we have introduced the “Increment” text in strings resource file. It should be available for selection as follows:

Here the resource file has already been updated as follows:

You can directly go to the definition of these resource definitions by CTRL + MOUSE OVER over the resource usage. It transforms into a hyperlink then which can be used to traverse to the definition site. You can also notice that we have updated the text of TextView as 0.

The similar is not true for the Ids. We define Ids here in the layout definitions with + sign. They are then compiled into a new class type R, which can be used from rest of the application. They are added to a final class in R called id. You might need to rebuild the project if you have just updated an id. So

Now add the following code to IncrementActivity java class. This would define an event handler our Increment button. It accesses the TextView using the id discussed above using findViewById method. The method is defined in the parent class of the Activity. Since it returns a View type, we need to typecast the result to TextView. After getting the contents of the text view, we are just parsing it to an integer, incrementing it and assigning it back to the same TextView.

Now we need to hook-up this handler to our button. We can simply achieve this using the property definition window of the button. It lists the assignable methods defined in the activity associated with this layout definition. Let’s select buttonOnClick here.

Mapping Between Activity and Layout

Before running the project, let’s just take a moment to discuss a few things. First of all, we have just discussed that behaviors and layout of an activity is defined in its corresponding java and xml files. Now how they are mapped to each other. Actually, it is a two-way mapping. In the java file, we generally add the layout mapping in the onCreate() method. In the xml layout definition we set the context of the layout to be the specific activity.

Android View & Layout Components

All the UI components in Android are derived from View type. Here we have used a TextView and Button. Both of them are derived from View type. In addition to these we have used FrameworkLayout. Layouts are also specialized views. All layouts are derived from ViewGroup which inherits from View. These view groups are containers for other view objects.

Running Project

An android app can be run on a real or a virtual device. Here virtual devices are emulators available to test an app. As we run the project, the following dialog is available for selecting the device we want to test it on. It includes all the devices connected to the system used for development which have debugging enabled. We can also launch emulators for testing on virtual devices. Since I have previously added a virtual device for Galaxy Nexus, this is available in the list for selection.

We can manage the list of virtual devices (emulators) from AVD (Android Virtual Devices) manager.

As we start debugging the project, the IDE provides us a list of running devices. We can select either of them to run our app. We can also start a new device for this purpose.

Code Inspections

Android Studio is amazing in helping us determine the code issues. In the code editor it shows help based on the code inspection settings. We can update the inspection settings from Code Inspection window.

Debugging Apps

It must be remembered that breakpoints are hit only in the case when we debug the app. If we just run it, no breakpoints are hit. So make sure that we select a debug option from the menu drop down.

Although this is not recommended but we can always set an application to be debug-able in the android manifest.

You can see that the code inspection has highlighted this. Actually this flag is automatically set when an application is debugged from the editor. Setting this here explicitly also sets it in the apk generated for the app, which is not recommended.

Let’s Debug Incrementer App

Now let’s run the project. It installs and debugs application on that device. This is remote debugging on that device provided by ADB. We can discuss it later. All the messages are added to the console so that you might have an idea what’s going on here.

As the application is running and the button is being clicked, you can set breakpoint in the onClick handler for the button. It provides a comprehensive view of the current application state. We can also step through the code here.

You can notice that as we are hitting the button, it is incrementing the number in the view, which is as per our original requirement.

Download Code

You can download the app’s code from Github: