The Evernote SDK for Android Quick-start Guide

The purpose of this guide is to show you how to install the Evernote SDK for Android, configure OAuth and briefly introduce the Evernote Cloud API.

• What You Need

  Before we begin, make sure you have both of the following:

  1. An account on sandbox.evernote.com, Evernote's development server. Your application will be communicating with this server during development. If you don't yet have an account, you can create one here.
  2. An Evernote API key, which consists of a Consumer Key and a Consumer Secret. If you don't have an API key, you can request one here.
  3. A functional development environment containing the Android SDK.

  Additionally, this guide will be describing how to setup the Evernote SDK for Android to work with the Eclipse IDE. If Eclipse is not your preferred Android development tool, you'll probably need to modify how you follow the instructions in the next section so your environment is properly set up and configured.

• Getting the SDK

  All of Evernote's SDKs are housed on Github. To download the Evernote SDK for Android as a zip file, visit the SDK project page on Github and click the "ZIP" button near the top of the page.

  Extract the archive; the folder within the SDK that you'll be using in your Android project is the library folder.

  Adding the SDK to Your Project

  (Note: this is boosted directly from the README file included with the Evernote SDK for Android. If, for some reason, these instructions don't get the job done, see the README file.)

  1. Import the Android Library Project
     1. Open Eclipse
     2. From the File menu, choose New and then Project...
     3. Under Android, select "Android Project from Existing Code" and click Next
     4. Click Browse
     5. Select the library directory and click Open
     6. Click Finish
  2. Add the Android Library Project as a dependency in your app
     1. Right-click on your project and choose "Properties"
     2. In the Android section, in the Library area, click Add...
     3. Select library from the list and click OK
     4. Click Java Build Path and then select the Projects tab
     5. Click Add...
     6. Select Library and click OK
     7. Click OK

  From there, you can import all of the various packages and classes available in the SDK.

• Modifying AndroidManifest.xml

  We need to make a couple of modifications to the project's AndroidManifest.xml file before we begin writing the code to interact with the Evernote Cloud API.

  First, since our application (obviously) needs permission to access the Internet, we need to add the following uses-permission element within the manifest element, like so:

  Second, since the OAuth facility baked into the Evernote SDK for Android runs as an Activity, we'll declare it within the application element of AndroidManifest.xml:

• Connecting to the Evernote Cloud API

  All communication with the Evernote Cloud API uses the EvernoteSession object. Looking at the HelloEDAM.java file in the sample application included with the Evernote SDK for Android, we can see how to initialize and use EvernoteSession.

  Beginning just inside the declaration of the HelloEDAM class, you'll find these lines of code:

  CONSUMER_KEY and CONSUMER_SECRET are the two parts of your Evernote API key. Replace the placeholder text with your actual key and secret.

  EVERNOTE_HOST is the server with which your app will be interacting. While your app is in development, this host will be EvernoteSession.HOST_SANDBOX. Once your app is ready for production use and you've had your Evernote API key activated in our production environment, you'll need to change that value to EvernoteSession.HOST_PRODUCTION or EvernoteSession.HOST_CHINA if you're connecting to the Yinxiang Biji (Evernote China) service.

  At the bottom of the onCreate method, you'll see a call to setupSession() whose definition looks like this:

  Under the hood, EvernoteSession is a singleton object; if an instance has already been created when getInstance is called, that instance will be returned. Otherwise, a new instance is created and returned.

  The constructor takes four parameters:

  1. A Context object. this, in this case since Activity is a descendent of Context in the android class hierarchy.
  2. A consumer key (which we have defined as CONSUMER_KEY).
  3. A consumer secret (CONSUMER_SECRET in the sample app).
  4. The host we'll be connecting to (EVERNOTE_HOST here).

  Once EvernoteSession has been initialized—as mEvernoteSession in our app—we're almost ready to start making calls to the API. First, though, we need to authenticate.

• Authentication

  The Evernote Cloud API uses the OAuth protocol to authenticate users. Virtually all of the OAuth flow has been baked in to the Evernote SDK for Android, so authentication is actually quite simple:

  This begins the OAuth flow by prompting the user to authenticate with Evernote via a web view. Assuming they authenticate successfully, control will return to the main app view and onActivityResult will be called, completing the authentication process. A "stub" of this function might look like this:

  Within the if block that confirms the authentication was successful, you can add the code to make whatever changes to your application state are necessary (see the HelloEDAM.java implementation for a simple example).

  At this point, mEvernoteSession will be ready to send requests to the Evernote Cloud API.

• Making API Calls

  In the sample app, locate the doInBackground method of the EvernoteNoteCreator inner class. This is where virtually all of the interactions with the Evernote Cloud API take place. (We use doInBackground because all API calls we make are network requests and should be made on their own thread).

  There are two classes with which you should become familiar: NoteStore and UserStore. These allow you to access a user's Evernote data (notes, notebooks, etc.) and account information (premium status, user name, real name, etc.), respectively. Both of these objects are created using EvernoteSession methods: createNoteStore and createUserStore.

  The body of doInBackground is a fine example of the basics of the Evernote Cloud API. This method, essentially, creates a new note, attaches an image (called a Resource in Evernote API parlance) and sends the note to the API using this line of code:

  mEvernoteSession.createNoteStore is called, followed immediately by a call to createNote. createNote takes two parameters: the auth token (which was obtained during the authentication process) and the note object. Assuming the operation is successful, createdNote will now contain, among other values, a GUID that uniquely identifies the note.

• Synchronous v. Asynchronous API Calls

  Since Android requires that network operations be performed on separate threads (otherwise a NetworkOnMainThreadException is thrown), the Evernote SDK for Android includes facilities for asynchronously making calls to the Evernote Cloud API.

  You can use the AsyncUserStoreClient and AsyncNoteStoreClient objects to access UserStore and NoteStore, respectively. These objects are generated by the ClientFactory instance available in EvernoteSession. Here's a simple example that asynchrnonously requests the current authenticated user:

  By calling getClientFactory and, subsequently, createUserStoreClient, we have an asynchronous interface to UserStore. An instance of OnClientCallback will handle the result of the asynchronous API call and is required; it should also accept whichever data type is returned by the API when the function completes (User, in the above exmaple).

  If you'd prefer to do handle your own threading and bypass the asynchronous facilities included in the SDK, you can call getClient method provided by AsyncUserStoreClient and AsyncNoteStoreClient which will return the underlying UserStore.Client and NoteStore.Client objects, respectively.

• Conclusion

  The breadth of API functions available is beyond the scope of this guide, but you would do well to peruse the methods available in NoteStore and UserStore since they will represent the vast majority of your app's interactions with the Evernote Cloud API. The package index for the Android SDK can be found here.

  At this point, you should be familiar with how to download the Evernote SDK for Android and add it to your app, as well as configure your app to use OAuth and your Evernote Cloud API key. If you have any problems, you can search the Evernote Developer Forum or visit developer support.