Evernote SDK for JavaScript Quick-start Guide

The purpose of this guide is describing how to download, install and configure the Evernote SDK for JavaScript (used in conjunction with the Apache Cordova library) and use it to build a simple iOS application.

  • What you need

    To complete this tutorial, you’ll need all of the following:

    1. An account on https://sandbox.evernote.com, Evernote’s development server. You’ll be connecting to this server while your application is in development.
    2. An Evernote API key, which consists of two values: a consumer key and a consumer secret. If you don’t have an API key yet, you can get one here.
    3. An Intel Mac running OS X 10.7.4 (Lion) or later.
    4. Xcode version 4.5 or newer. (available from the Mac App Store).
    5. The iOS SDK for iOS 6.0 or newer.
    6. The Xcode command line tools library from Apple.
  • Downloading and installing Apache Cordova

    To download and install the PhoneGap framework, which includes the Apache Cordova library, follow the steps described in the the PhoneGap documentation. After successfully completing all of thes steps described there, you should have a sample Xcode project that builds and runs in the iOS simulator. The application should look and behave as it does in the PhoneGap documentation.

    Installing the Evernote JavaScript SDK

    The Evernote SDK for JavaScript is hosted on Github. Download the minified version of the file — you’ll find a direct download URL in the README near the bottom of the page. Next, download the jsOAuth library. Drop both of these JavaScript files into your project’s www/js directory.

    To complete the installation, make sure you include the two JavaScript files in the <head> element of your project’s index.html file:

  • Adding OAuth configuration and login callback functions

    Within the app scope, add these lines. Make sure to substitute your consumer key and consumer secret for the placeholder values and remember that you’ll need to change the value of evernoteHostName to www.evernote.com when you’re ready to deploy your application in a production environment.

    Next, we need to add our login function which begins that OAuth flow.

    (Note that you'll want to replace the value of callbackUrl in your implementation.)

    Bind this function to a user action (such as clicking a button or submitting a form) to integrate it with your application. In our PhoneGap example, we’ve bound app.loginWithEvernote to a button in index.html:

    Notice that we’re passing an object literal to oauth.request; this object enumerates success and failure callback functions. As you’d expect, these will be called when the request succeeds or fails, respectively. Note that a failed login attempt will still result in a successful request; failure will be called when some mechanical error—such as a network issue—prevents the request from completing.

    The following implementation of success and failure will complete the OAuth flow and, if the process completes successfully, produce a valid authentication token that can be used to make calls against the Evernote Cloud API. These functions will also need to be defined with the app scope:

  • Testing your application

    After you’ve modified the source files indicated above, simply build and run your project in the iOS Simulator. If all goes well, clicking the “Click Me” button after the application launches will take you to the Evernote authentication screen and prompt your your username and password. After successfully authenticating, the web view showing the login screen will disappear and a list of the user’s notebooks will appear in the log section of Xcode.

    You can download our PhoneGap example project from Github.

  • FAQ’s

    “Can I build a browser-based Evernote client using this SDK?”

    Probably not; most browsers will disallow sending XMLHTTPRequests across domains, so there’s a very good chance that such an implementation wouldn’t work in most environments.

    “Where can I use this?”

    A number of platforms and frameworks that run on devices (like PhoneGap) and servers (like Node.js) are excellent places to work with the Evernote SDK for JavaScript.

  • Conclusion

    If you need assistance or have questions regarding the Evernote SDK for JavaScript, don’t hesitate to contact our Developer Support department.

    Be sure to look at our working PhoneGap example project from Github.

Stay on top of what's happening in the Evernote developer community.