Integrating an iOS Application With Evernote: First Steps

One of the advantages of Evernote is its omnipresence. Our applications work on almost all significant mobile platforms, on the two most popular computer operating systems and in all other cases (via the web interface). But we are not going to stop there.

Now more and more mobile applications support the ability to read and send information to Evernote. We like it a lot, and we would like it to go on and on - the more ways you have to get access to your notes, the better (or so it seems to us). As a developer, you get access to more than 30 million of our users and you can instantly increase the value of your application in the eyes of these people, opening them up to connect with their external “digital memory”.
')
We decided to periodically publish guides for developers who are just starting to master the Evernote platform (or development in general) and want to integrate their applications with our service.

In this post, we describe the specific steps for integrating Evernote into an iOS test application. We will start a new project in Xcode, download and install the Evernote Software Development Kit (SDK) and create a simple application that will interact with Evernote via the Cloud API.

Before you begin, we list what you need for independent work in the future:

1. The sandbox.evernote.com server account is an Evernote sandbox server for developers. It is used to debug your applications running through the Evernote Cloud API. Test account can be created here .
2. Evernote API key ( Request key ). The API key consists of two parts: the consumer key and the consumer secret . ( Note: If you are developing your own application, then keep in mind that after finishing the development of the application, you will need to ask us to include your key on the main Evernote server. This can be done through the form on dev.evernote.com/support ).
3. The latest version of Xcode at the time of this writing is 4.3.2 installed on an Intel Mac.

All available? Great, then let's get started.

Our application will do exactly two things: show the name of the current user and the total number of notes in his account.

* It should be clarified that we chose this idea for the application completely by accident and at the time we started working we didn’t know if there was an API for easier access to this information *

Laying the foundation

Before we start writing code and impress the first users, we need to prepare the ground - create an Xcode project and install the Evernote SDK for iOS.

Creating an Xcode project

1. Launch Xcode and create a project using the menu: File> New> Project.
2. When you are asked to specify a project template, select “Application” under “iOS” in the left menu and click on “Single View Application”. Then click “Next”.
   
   
   
   
3. On the next screen, you will need to clarify several characteristics of the new application:
   
   • In the Product Name, enter “EvernoteCounter”.
   • Company Identifier can be arbitrary. This value is used to identify your application in the world, but since we are not going to let it go further than your computer, it does not matter. In the example we specified “com.somecompany”.
   • Enter Class Prefix “EC” (short for “EvernoteCounter”). This abbreviation will precede all class names when we start writing code.
   • Enter the “iPhone” in the Device Family.
   • Make sure all three checkboxes are cleared.
   • When you're done, the fields should be filled in like this:
     
     
4. At the end you will be asked to specify the location for saving the project. Choose it at your discretion.

That's it, your Xcode project is ready. Put it aside for a few minutes. In order for our application to interact with the Evernote Cloud API, we need an SDK. Let's get it and add it to the project.

Download and Install Evernote SDK for iOS

1. All Evernote SDKs are available on Github. Among them is the iOS SDK .
2. Click on the “Downloads” link in the middle on the right.
3. On the page that appears, click “Download as zip”. You will download the current version of the SDK.
4. Unzip the file and you will see a directory like this:
   
   

In the downloaded SDK directory, select the evernote-sdk-ios folder and drag it into your evernote-sdk-ios project:


Xcode will ask you a couple of questions about what you just did. Everything can be left by default - click “Finish”.

The Evernote SDK for iOS requires the Security.framework component, so you need to include it in the application development process:

1. Click on the project in the upper left corner of the Xcode window.
2. Click on “Build Phases” in the center of the top of the window.
3. Expand the “Link Binary With Libraries” list, then click on the plus sign in the lower left.
4. In the search bar of the list that appears, start typing “Security”.
5. When Security.framework appears in the list, click on it to highlight it, and then click “Add”:
   
   

Now that all the preparatory work has been completed, it is time to move on to the most interesting.

Creating an application

As already mentioned, our application should be able to do only one thing - to authorize the user in his Evernote account and show the total number of notes in this account.

Before we dive into the root functionality of our application, we need to configure it to authenticate through the Evernote Cloud API using OAuth. iOS SDK allows you to implement this bundle without problems in a couple of minutes.

Configuring OAuth

First, we need to modify ECAppDelegate.m . By default, Xcode automatically creates for us the didFinishLaunchingWithOptions method. Before making changes, this method looks like this:


Click on the image to view this code on Github

In order for OAuth to work, we need to create an instance of EvernoteSession with the correct host and authentication credentials. The modified ECAppDelegate.m will look like this:


Click on the image to view this code on Github

EVERNOTE_HOST is the remote host we will interact with. While the application is under development, we will need to contact sandbox.evernote.com, our sandbox server. Before releasing the application, do not forget to replace EVERNOTE_HOST with www.evernote.com www.evernote.com and request key activation on the main server, as we wrote earlier.

CONSUMER_KEY and CONSUMER_SECRET are the two parts of the API key that we previously received. So you will need to change the existing values ​​of the parameters of your real key.

Next, we initialize a new instance of EvernoteSession , then specify its properties: host, consumerKey and consumerSecret . Finally, our new session variable is assigned to a singleton object that will be used every time the application interacts with the Evernote Cloud API.

And we also need to remember to include EvernoteSession.h in the header file. Add the appropriate announcement immediately after our ECViewController.h is included in ECAppDelegate.m :


Click on the image to view this code on Github

Since the OAuth procedure involves authorizing our applications through a web page, you need to make sure that our application can handle open links. Fortunately, this is already embedded in the iOS SDK, and all we need to do is add this method to the end of our ECAppDelegate.m file (right before the end ):


Click on the image to view this code on Github

Creating user interface

Now you can make a simple interface for our application. Click on ECViewController.xib on the left. The interest editor opens with settings calculated on the iPhone screen. Here we can drag, create and customize interface elements: buttons, text fields, etc. For this application, we will need a couple of text fields (one for the username in Evernote, another for the number of notes), a label for each field and a button, which will start the procedure. (Please note that text fields must be of the UILabel type, which will allow you to set their values ​​dynamically; we will discuss more about this later).

Drag all the necessary interface elements from the object library into the editor field. When you're done, it should look something like this:



We will need to declare the IBOutlet properties and the IBAction method to handle clicks on our button. Let's add all this to our ECViewController.h file:


Click on the image to view this code on Github

We now associate our text value areas, which will show the user name and the number of notes with their corresponding properties in the ECViewController ( usernameField and noteCountField ).

1. Click on ECViewController.xib in the project browser on the left to open our interface layout.
2. Then right-click on “File's Owner” under “Placeholders” to expand the links panel.
3. Click on the empty area to the right of the usernameField and drag it to the corresponding value area as shown here:
   
   
4. Do the same with noteCountField .

Now we need to associate our button with the retrieveUserNameAndNoteCount method that we announced earlier. To do this, hold down Control and drag the button to “File's Owner”. After you release the mouse button, select the retrieveUserNameAndNoteCount item in the “Sent Events” window that appears.

Now we have text fields and a button, ready to perform their tasks, and we need to do internal work in ECViewController.m . Here’s how the file looks like the default after it was generated by Xcode:


Click on the image to view this code on Github

To complete our tasks (show your username and number of notes in your account), you need to create two methods.
The first, of course, method that is called when you click on the button: retrieveUserNameAndNoteCount .

This method will be:

1. provide authentication with the Evernote Cloud API (and show an error message if something goes wrong);
2. receive information about the current user as an EDAMUser object. (by the way, “EDAM” stands for “Evernote Data Access and Management”);
3. specify username as value in usernameField ;
4. call another method to get the number of notes for this user.

Here is our method in finished form:


Click on the image to view this code on Github

Just do not be alarmed - now we will analyze all of this in detail.

First, we get a local instance of EvernoteSession (since it is a single instance (singleton), it will be the same as we created in ECAppDelegate.m ). Then we call authenticateWithCompletionHandler . This method attempts to verify that we authenticate our session with the Evernote Cloud API (more on this in the section on OAuth below). In the event of an error during authentication, or if authentication failed for some reason, information is recorded using the NSLog and displayed in a dialog box (an instance of UIAlertView ), and the authentication is reported to the user.

If the authentication is successful, we can go to the main logic of our application. It is important to remember that as soon as the application receives an authentication token, it will be valid for a year, then the user will have to log in again. However, if the user decides to reinstall your application, he will need to log in again.

First, you need to determine the account with which we work. To do this, create a local instance of EvernoteUserStore ( userStore ) and call its getUserWithSuccess method. This is an asynchronous request, which in response requests functions implemented as blocks (in fact, these are anonymous functions). The first block accepts a single EDAMUser parameter and reports that the request was successful. The second block ( failure ) takes one instance of NSError , which describes what went wrong. When an error is detected, the application simply registers it and does nothing more.

If the request to the API is successful, we request the username property from our EDAMUser instance and specify it as the value for the usernameField .

And finally, we call our other countAllNotesAndSetTextField method:


Click on the image to view this code on Github

This method, as its name speaks eloquently, counts the number of notes in your account and displays it on the screen. Let's see how it works.

First, we declare a noteCount counter noteCount . This variable will count the account notes (more on this later).

Then we create a local EvernoteNoteStore instance called noteStore . Using this object, we will request access to notes, notebooks, etc. from the Evernote Cloud API using methods such as listNotebooksWithSuccess (which we call in the next line). Since the Cloud API does not contain a ready-made way to get the number of all notes in an account, we need to do the following sequence of actions:

1. get a list of all notebooks in a user account using listNotebooksWithSuccess ;
2. go through this list and get the number of notes for each notebook.

The answer listNotebooksWithSuccess , like getUserWithSuccess , is a pair of blocks. The first handles a successful server response and takes a single NSArray parameter that contains a collection of EDAMNotebook objects — one for each notepad in the user account.

Each of our EDAMNotebook objects contains a unique GUID notepad identifier. Using this GUID, we create an instance of EDAMNoteFilter , which will allow us to find notes that are in the corresponding notepad. Finally, with EDAMNoteFilter as a parameter, we can call findNoteCountsWithFilter to get the number of notes in a given notebook (as an instance of an EDAMNoteCollectionsCounts object).

Now that we have a number, we add it to the noteCount variable and update the noteCountField on the screen. And here is the result:

Oauth

If the session does not pass authentication (that is, the token is not received), then when you click on the button, the application will transfer control to the mobile Safari, where the Evernote website will open. There, the user must log into his Evernote account and authorize our application to access his account.

After the user has logged in, the browser returns control to the application, and the process continues as if the user had just pressed a button. If everything went well, the user name and number of his notes will be displayed on the screen as shown above.

Finally

And another point worth noting: the EvernoteCounter application was created in order to show the ease of integration and use of our iOS SDK. If it were a real application for mass use, it would be necessary to pay much more attention to the conditions in which errors can potentially arise and the work on “protective” programming practices. However, they have been omitted here in order not to complicate for understanding the code of the test application.

The entire EvernoteCounter project for Xcode is available on Github. If you want to help and improve the code, feel free to suggest your edits (Please note that we are not talking about the new functionality of this application, but only to make the application even more suitable as a training tool.)