Getting Started with the Evernote API (iOS)

The Evernote SDK for iOS Quick Start Guide

The purpose of this guide is describing how to download, install and configure the Evernote iOS SDK to work with your iOS application. If all goes well, this should take 10 minutes or less.

• 1. What You Need

  Before we begin, make sure you have all 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 have a testing account, 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 yet, you can request one here.
  3. The latest version of Xcode (4.3.2 at the time of this writing) running on an Intel Mac.
  4. An Xcode project where you can install the SDK. If you don’t have one or aren’t sure how to create one, you can read instructions on creating one.

  
  

  Additional Notes:

  • If your project does not use ARC, you'll need to set the -fobjc-arc compiler flag on all of the files in the Evernote SDK.

• 2. Downloading and Installing the SDK

  All of our SDKs are hosted with Github. Browse to the Evernote iOS SDK, click “Downloads” and choose “Download as zip” or “Download as tar.gz” (whichever you prefer). If you're comfortable using the Git version control system, you may also clone the SDK to your local machine using the git clone command.

  Once you have the SDK archive downloaded, there are a few ways to add it to your project:

  • Extract the download archive. It will contain a folder called evernote-sdk-ios. Drag this folder into your Xcode project and drop it on the main project directory. It should look something like this when you’re finished:

    

  • Add evernote-sdk-ios.xcodeproj to your project/workspace.
  • Build evernote-sdk-ios as a static library and include the header (.h) and archive (.a) files.
  • Use the cocoapods dependency manager for Objective C, where our pod is called "Evernote-SDK-iOS".

• 3. Configuring the SDK and OAuth

  The Evernote SDK for iOS communicates with the Evernote Cloud API using the OAuth protocol. The plumbing of OAuth is baked into the SDK, so we just need to configure our API key.

  In your application's main app delegate, locate the didFinishLaunchingWithOptions method. Near the end of this method (but before return YES;), add the following code:

  NSString *EVERNOTE_HOST = BootstrapServerBaseURLStringSandbox;
  NSString *CONSUMER_KEY = @"your-key";
  NSString *CONSUMER_SECRET = @"your-secret";
          
  [EvernoteSession setSharedSessionHost:EVERNOTE_HOST
                            consumerKey:CONSUMER_KEY
                         consumerSecret:CONSUMER_SECRET];

  EVERNOTE_HOST is the server to which your app will be connecting. BootstrapServerBaseURLStringSandbox is a constant defined in ENConstants.h representing our development server. This host should be used while your app is being built. When you're ready to release your app, you'll need to get your API key activated on production and change EVERNOTE_HOST to either BootstrapServerBaseURLStringUS (for the production Evernote service) or BootstrapServerBaseURLStringCN (for Yinxiang Biji, Evernote's Chinese service).

  After adding those lines of code, replace your-key and your-secret with the Consumer Key and Consumer Secret from your API key.

  The last lines of this snippet configure the EvernoteSession singleton object. Whenever your application needs to access the Evernote Cloud API, you'll use this instance (more on that in a second).

  Don't forget to include the EvernoteSession.h and ENConstants.h header files. Add these lines just below the other #import statements near the top of your source file:

  #import "EvernoteSession.h"
  #import "ENConstants.h"

• 4. Updating Your Application’s plist File

  Create an array key called URL types with a single array sub-item called URL Schemes. Give this a single item with your consumer key prefixed with en-:

  <key>CFBundleURLTypes</key>
  <array>
      <dict>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>en-yourkey</string>
          </array>
      </dict>
  </array>

  Your app's plist file can be found within the Support Files folder in your project. Right-click the file and choose Open As, then Source Code to edit it as XML. Feel free to add the XML near the top of the file (or wherever you'd like). Once you've finished, it should look like this:

  

• 5. Including Apple’s Security Framework

  For our OAuth implementation to work correctly, we need to include Apple’s Security.framework package in our application’s build process.

  Select your main project in the document browser on the left-hand side of Xcode. In the right-hand pane, choose “Build Phases”, then expand the “Link Binary with Libraries” row below. Click the + to add a new library.

  This will bring up the library browser dialog. In the search field at the top, begin typing “Security” until Security.framework is visible:

  

  Click Security.framework, then click “Add”.

  We’re now ready to test our application’s ability to authenticate via OAuth. Let’s do that now.

• 6. Testing OAuth

  Before we continue, we should make sure everything is working as it should. Let’s create a very simple test that will authenticate with the Evernote Cloud API via OAuth and successfully make an API call (UserStore.getUser, in this case).

  (Note: the following implementation is meant to be an example that a new user can quickly build and run to make sure things are working. How you structure your application, etc. is up to you.)

  We’re going to create a single button that does everything. It won’t be pretty, but it will let us know we’ve got everything wired up correctly.

  Open your app’s main UIViewController header file and add these two lines:

  @property (strong, nonatomic) IBOutlet UIButton *testButton;
  - (IBAction)testEvernoteAuth:(id)sender;

  Click over to your application’s .xib file and drag a single Round Rect Button onto the canvas. You can change the button text if you like, but you don’t need to for this exercise. After you’ve placed the button, click on “File’s Owner” under Placeholders on the left, then hold the Ctrl key while you drag onto the button. When you release, you’ll see a list of outlets for that button. Select testButton from the list.

  Next, click the button on the canvas and drag it onto “First Responder” under Placeholders while holding the Ctrl key. When you release, a menu titled “Send Events” will appear. Click testEvernoteAuth.

  Open your application’s UIViewController implementation file (the .m file). In that file, just above @end at the bottom of the file, add this code:

  - (IBAction)testEvernoteAuth:(id)sender
  {
      EvernoteSession *session = [EvernoteSession sharedSession];
      NSLog(@"Session host: %@", [session host]);
      NSLog(@"Session key: %@", [session consumerKey]);
      NSLog(@"Session secret: %@", [session consumerSecret]);
      
      [session authenticateWithViewController:self completionHandler:^(NSError *error) {
          if (error || !session.isAuthenticated){
              if (error) {
                  NSLog(@"Error authenticating with Evernote Cloud API: %@", error);
              }
              if (!session.isAuthenticated) {
                  NSLog(@"Session not authenticated");
              }
          } else {
              // We're authenticated!
              EvernoteUserStore *userStore = [EvernoteUserStore userStore];
              [userStore getUserWithSuccess:^(EDAMUser *user) {
                  // success
                  NSLog(@"Authenticated as %@", [user username]);
              } failure:^(NSError *error) {
                  // failure
                  NSLog(@"Error getting user: %@", error);
              } ];
          }
      }];
  }

  Finally, at the top of the same file, add #import statements for EvernoteSession.h and EvernoteUserStore.h (as well as the header file for your main application delegate):

  #import "EATAppDelegate.h"
  #import "EvernoteSession.h"
  #import "EvernoteUserStore.h"

• 7. The Acid Test

  Assuming everything is in order, you should now be able to build your application and see a single button. When you click (or tap) that button for the first time, you’ll be taken to Evernote’s Web UI to authorize our test app to access your account. Once you enter the correct account credentials and click Authorize, the Web view will disappear and the Output area of Xcode should tell you something like this:

  2012-07-03 17:05:23.992 EvernoteAuthTest[2954:f803] Authenticated as [your username]

• 8. In Conclusion

  As previously stated, this guide is designed to get you quickly up and running with the Evernote SDK for iOS. Essentially, everything in the “Testing OAuth” section can be removed from your application and you’ll still be able to make calls to the Evernote Cloud API.

  Congratulations - you're on your way to building another fantastic integration with Evernote!

  If Something Goes Wrong

  If you follow the above instructions and you’re not able to produce the desired result, head over to our support page.