Creating a Twitter Client for Android: Setup & Overview
It goes without saying that many people use mobile devices to connect to social media services. In this series of tutorials, we will create a basic Twitter client for the Android platform. We will use the Twitter4J library to connect to Twitter. The app will display the user's home timeline, send tweets, retweet, and reply to tweets.
Here's a preview of the end result:
Also available in this series:
- Creating a Twitter Client for Android: Setup & Overview
- Creating a Twitter Client for Android: Building the Interface
- Creating a Twitter Client for Android: Creating a Timeline Database
- Creating a Twitter Client for Android: Retrieving Updates Using a Service
- Creating a Twitter Client for Android: Tweeting, Retweeting, and Replying
Step 1: Understanding How the App Will Work
Before we start building the app, let's take a moment to go over what we are trying to achieve and how we are going to do it! The app will involve a variety of techniques and Java/ Android utilities including an SQLite Database, a Service, a Broadcast Receiver, an Adapter and the Twitter4J methods themselves.
What the App Will Do
When the user runs the application for the first time, they will be presented with a prompt asking them to sign in to Twitter to authorize the app to use their account. At this point they will be redirected to a page in the Web browser, where Twitter will handle getting them signed in and authorizing the app for access. The user will then be redirected back to the app, with Twitter returning the authorization information required to implement the various tweeting and timeline functions.
Once the user has granted the app permission to use their account, and on subsequent app runs after that, the first thing they will see is their home Twitter timeline (as in the image above). The home timeline initially displays the most recent tweets, with newer tweets added as time passes. While the user is interacting with the app, a Service will periodically fetch new tweets and the code will refresh the timeline display accordingly.
Within each tweet in the timeline, the user will be able to see the Twitter username of the account in question, the time the tweet was sent relative to now, the tweeted text and the user profile icon image. If there are any URLs in the tweet text, the app will automatically treat these as Web links so that the user can click them to access the linked resources. The user will also be able to retweet and reply to each tweet in the timeline.
To send a tweet, the user will press the Tweet button at the top of the screen, which takes them to the Tweet Activity screen. Here they can enter and send their tweet. If the user chooses to reply to a tweet in their timeline, they will also be taken to the Tweet screen, with the username automatically populated in the tweet text-field and the underlying code storing the information required for replying to a particular tweet.
This app has a very specific remit, but once you finish developing it you may of course wish to enhance it. At the end of the last tutorial in the series we will run through some suggestions for further development, such as an Activity for viewing Twitter user profiles. The app as we will develop it here will allow the user to click through to the profile of a Twitter user in the Web browser by selecting their username within the timeline, linking to the Twitter website to give the user access to functions we have not provided within the app itself.
How the App Will Do All of This
The Twitter client app is going to have two main Activities: one for the timeline and one for tweeting. When the app starts up, it will create an SQLite Database to store the home timeline tweets, with an Adapter mapping the Database rows to Views within the application user interface. The app will also start a Service to run while the user interacts with it, updating the timeline with new tweets when they are available. To do this, the app will send and receive Broadcasts when new updates have been retrieved, so that it can refresh the visible tweets.
The application will only contain a few classes, but these classes are relatively complex. We will also need to import the Twitter4J library, create and reference various resource files and edit the project Manifest. If this seems like a lot to get on with, don't worry! We will work through and explain each step in detail. Let's get set up.
Step 2: Register the App with Twitter
Visit the Twitter Developers site and sign in with your own Twitter login details to register your app. Create a new app within the interface you see there. Enter a name for your app. For this tutorial series the app will be named TwitNice, but you will need to choose your own name. Enter a description and a website URL, which can simply be your own homepage. You can enter the same address (or really any address you own) as the callback URL; we will not need it for the app but you have to enter something to complete registration.
Once you have your app created in the Twitter Developer interface, you should be able to see its details. Browse to the Settings tab for the app and scroll down to the Application Type section. Select either Read and Write or Read, Write and Access Direct Messages. For this series we will not be accessing direct messages, but you may wish to extend your app to do this in future. You can change these settings at any time. Click the button at the bottom of the page to update your application settings.
Select the Details tab for your Twitter application. This area contains details you will need to note. In the OAuth settings section, copy the values for Consumer Key and Consumer Secret to a file on your computer for future reference. These should both be kept private. We will use the OAuth key and secret within the application code to carry out Twitter functions.
These settings are for verifying your developer access for this application. Later, we will also need to implement verifying the user and gaining permission interact with their tweets.
Step 3: Create a New Project in Eclipse
Time to create your project. In Eclipse, choose File, New, Project, then Android Project. Enter your project name, select Next and choose API level 8 to make sure the code in this tutorial series will not cause any problems. Click Next and enter your package name, then Finish to create your new project.
Step 4: Import the Twitter4J Resources
We will be using Twitter4J to handle interaction with Twitter within the app. This involves importing the library so that we can create objects defined in it, then use those objects to call the methods necessary to access Twitter. Visit the Twitter4J site and download the most recent stable version of the library. Once you have it downloaded, unpack the zipped file to a location of choice within the file system on your computer.
Now we need to add the Twitter4J library to your app's build path. To do this, select your project in the Eclipse Package Explorer, then choose the Project toolbar menu, then Properties. The Properties window should open. Select Java Build Path, then the Libraries tab.
To add the Twitter4J library to your project, choose Add External JARs, then browse to the location of the core JAR file for Twitter4J, which at the moment is named "twitter4j-core-android-2.2.5.jar" and is stored within the "lib" folder of the directory you unpacked. For newer versions of the library, you may need to look for a slightly different JAR file, but it should have roughly the same name. Once you have the JAR file added you will see it in the Libraries tab.
Click OK to close the Properties window. In your application directory, you should now see the JAR file in the Referenced Libraries section.
Your application now has the ability to reference and use the Twitter4J functionality. If you decide later that you want to add media functions such as image upload to your Twitter app, you will also need to add the Twitter4J media JAR file, which is in the same location as the core JAR.
Step 5: Edit the Project Manifest
To finish preparing the app, let's edit the project Manifest. Open the Manifest file from the Eclipse Package Explorer to see it in the editor. Switch to the AndroidManifest.xml tab to edit the code directly.
We need to make a few additions and amendments to the Manifest to prepare for the app. First, add the following permission element anywhere you like, as long as it's outside all other elements except the root manifest element itself:
<uses-permission android:name="android.permission.INTERNET" />
This lets the app access Internet resources. In the application element, alter the main Activity as follows:
<activity android:label="@string/app_name" android:launchMode="singleInstance" android:name=".TwitNiceActivity" > <intent-filter > <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> <intent-filter > <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="tnice-android" /> </intent-filter> </activity>
Within the opening Activity tag, alter the name attribute to suit the name of the main Activity class you chose when creating your project, or a name of your choice if you did not get Eclipse to generate your main Activity automatically.
The Intent Filter elements specify that your main Activity should be launched when the app starts up and that it will be able to open the Web browser so that we can get the user signed into Twitter for authorization.
Notice the data element near the bottom of this code. This is also for authenticating the app. You can alter the scheme attribute value if you like, but it is referenced in the application code so bear this in mind. It doesn't really matter what you put in here as long as it matches the Java code we will write later.
Finally, add another two elements to your Manifest, inside the application element but after the closing tag for the Activity element above:
<activity android:name=".NiceTweet" ></activity> <service android:name=".TimelineService" />
The Activity element is for the second screen in the app, which is for sending tweets. We are calling the Activity class "NiceTweet". If you want to give the class a different name feel free to do so, remembering that the class name you choose will need to match this element in the Manifest and references at various points in the application's Java code. The second element is for the Service we will implement to fetch Twitter updates. Again, feel free to change the class name if you wish.
Until the Next Time...
We have now laid the foundations for our Twitter client. In the next tutorial we will handle getting users to sign into Twitter to give the app permission to access their accounts. When the Twitter page returns the user to the app we will retrieve the authentication information and save it in the application preferences. After that the app will be able to fetch and display the user's timeline as well as sending tweets from their account.
In Part 2 of this series we will also create user interface elements for the app, including layouts and drawable resources. In Parts 3, 4 and 5 we will implement the Database, Adapter and Service for the app, as well as allowing the user to tweet, retweet and reply to tweets.