Evernote SDK for iOS版本1.3.0

这是什么

Evernote云API (v1.25)的iOS封装，使用OAuth进行身份验证。

必读

请查看Evernote开发者门户页面。Apple风格的文档在这里：这里。

安装

注册Evernote API密钥（及密钥）

您可以在Evernote开发者门户页面上进行注册。

包含代码

您有几个选择

• 将evernote-sdk-ios文件夹复制到您的Xcode项目中。
• 将evernote-sdk-ios xcodeproj添加到您的项目/工作空间中。
• 将evernote-sdk-ios构建为静态库，并包含.h和.a。 （如果选择此选项，请确保将“其他链接器标志”中的“-ObjC”标志添加）。更多信息请参阅这里。
• 使用cocoapods，一个很好的Objective-C依赖管理器。我们的pod名称是"Evernote-SDK-iOS"。

链接到框架

evernote-sdk-ios依赖于某些框架，因此您需要将它们添加到"Link Binary With Libraries"构建阶段中任何目标的"链接二进制与库"。在"链接二进制与库"阶段添加以下框架

• Security.framework
• StoreKit.framework
• MobileCoreServices.framework
• libxml2.dylib

添加头文件搜索路径

将${SDKROOT}/usr/include/libxml2添加到您的头文件搜索路径。

修改您的应用程序主plist文件

创建一个键名为“URL Schemes”的数组，其中一个子项被称为“URL Schemes”。给它一个带前缀“en-”的消费者密钥的单一项

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string></string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>en-<consumer key></string>
        </array>
    </dict>
</array>

修改您的AppDelegate

首先您设置共享的EvernoteSession，使用您的消费者密钥和密钥进行配置。

SDK 现在默认支持云笔记服务。请确保您的消费者密钥已在 激活 中国服务。

在 AppDelegate 的 application:didFinishLaunchingWithOptions: 方法中执行类似以下操作。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Initial development is done on the sandbox service
    // Change this to BootstrapServerBaseURLStringUS to use the production Evernote service
    // Change this to BootstrapServerBaseURLStringCN to use the Yinxiang Biji production service
    // Bootstrapping is supported by default with either BootstrapServerBaseURLStringUS or BootstrapServerBaseURLStringCN
    // BootstrapServerBaseURLStringSandbox does not support the  Yinxiang Biji service
    NSString *EVERNOTE_HOST = BootstrapServerBaseURLStringSandbox;

    // Fill in the consumer key and secret with the values that you received from Evernote
    // To get an API key, visit http://dev.evernote.com/documentation/cloud/
    NSString *CONSUMER_KEY = @"your key";
    NSString *CONSUMER_SECRET = @"your secret";

    // set up Evernote session singleton
    [EvernoteSession setSharedSessionHost:EVERNOTE_HOST
                  consumerKey:CONSUMER_KEY  
                   consumerSecret:CONSUMER_SECRET];
}

在 AppDelegate 的 application:openURL:sourceApplication:annotation: 方法中执行类似以下操作。

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    BOOL canHandle = NO;
    if ([[NSString stringWithFormat:@"en-%@", [[EvernoteSession sharedSession] consumerKey]] isEqualToString:[url scheme]] == YES) {
    canHandle = [[EvernoteSession sharedSession] canHandleOpenURL:url];
    }
    return canHandle;
}

在 AppDelegate 的 applicationDidBecomeActive: 方法中执行类似以下操作。

- (void)applicationDidBecomeActive:(UIApplication *)application
{
        // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
        [[EvernoteSession sharedSession] handleDidBecomeActive];
}

现在您可以开始了。

在您的代码中使用 Evernote SDK

认证

在您的代码中，您需要在某个地方对 EvernoteSession 进行身份验证，并传递您的视图控制器。

通常你可以在一个“链接到 Evernote”的按钮动作中进行此类操作。

EvernoteSession *session = [EvernoteSession sharedSession];
[session authenticateWithViewController:self completionHandler:^(NSError *error) {
    if (error || !session.isAuthenticated) {
        // authentication failed :(
        // show an alert, etc
        // ...
    } else {
        // authentication succeeded :)
        // do something now that we're authenticated
        // ... 
    } 
}];

调用 authenticateWithViewController:completionHandler: 会启动 OAuth 流程。EvernoteSession 会打开一个新的模态视图控制器，以显示 Evernote 的 OAuth 网页并处理所有 OAuth 握手。当用户完成此过程后，Evernote 的模态视图控制器将关闭。

使用 EvernoteNoteStore 和 EvernoteUserStore 来对 Evernote API 进行异步调用

EvernoteNoteStore 和 EvernoteUserStore 都有一个便利构造函数，它使用了共享的 EvernoteSession。
所有 API 调用都是异步的，在后台 GCD 队列上执行。您提供成功和失败回调块。例如，

EvernoteNoteStore *noteStore = [EvernoteNoteStore noteStore];
[noteStore listNotebooksWithSuccess:^(NSArray *notebooks) {
                                // success... so do something with the returned objects
                                NSLog(@"notebooks: %@", notebooks);
                            }
                            failure:^(NSError *error) {
                                // failure... show error notification, etc
                                if([EvernoteSession isTokenExpiredWithError:error]) {
                                    // trigger auth again
                                    // auth code is shown in the Authenticate section
                                }
                                NSLog(@"error %@", error);                                            
                            }];

有关 Evernote NoteStore 和 UserStore API 的完整信息，请参考 Evernote 开发者门户页面。

创建笔记内容

SDK 包含一个 ENML 编写器，可以帮助您编写笔记。这对于编写带样式的笔记很有用，支持将资源如图片添加到笔记中，也支持将加密字段写入到 Evernote。例如，

ENMLWriter* myWriter = [[ENMLWriter alloc] init];
[myWriter startDocument];
[myWriter startElement:@"span"];
[myWriter startElement:@"br"];
[myWriter endElement];
[myWriter writeResource:resource];
[myWriter endElement];
[myWriter endDocument];
EDAMNote *newNote = [[EDAMNote alloc] init];
newNote.content = myWriter.contents;
newNote.title = "Test note";
newNote.contentLength = myWriter.contents.length;

resource 是类型为 EDAMResource。更多示例请参见示例应用程序代码。

提示用户安装 Evernote for iOS 应用

如果需要检查 Evernote for iOS 应用是否已安装，您可以使用以下代码。

[[EvernoteSession sharedSession] isEvernoteInstalled]

如果需要提示用户安装 Evernote for iOS 应用，您可以使用以下代码。

[[EvernoteSession sharedSession] installEvernoteAppUsingViewController:self]

使用任何与 Evernote for iOS 相关函数的首选方式是

if([[EvernoteSession sharedSession] isEvernoteInstalled]) {
// Invoke Evernote for iOS related function
}
else {
// Prompt user to install the app
[[EvernoteSession sharedSession] installEvernoteAppUsingViewController:self];
}

使用 Evernote for iOS 应用创建/查看笔记

为此，需要安装最新的 Evernote for iOS 应用。您可以发送文本/html或文本/plain类型的内容。您还可以发送附件。

创建新笔记：：

EDAMNote *note = <create a new note here>
[[EvernoteSession sharedSession] setDelegate:self];
[[EvernoteNoteStore noteStore] saveNewNoteToEvernoteApp:note withType:@"text/html"];

查看笔记：：

EDAMNote *noteToBeViewed : <Get the note that you want to view>
[[EvernoteNoteStore noteStore] viewNoteInEvernote:noteToBeViewed];

您还可以在示例应用程序中看到此功能的示例。

查看笔记

您可以使用此功能在您的应用程序中查看笔记。您将需要包含 ENMLUtitlity.h。

以下是一个示例。此示例需要您设置一个网页视图或任何其他 html 渲染器。

[[EvernoteNoteStore noteStore] getNoteWithGuid:<guid of note to be displayed> withContent:YES withResourcesData:YES withResourcesRecognition:NO withResourcesAlternateData:NO success:^(EDAMNote *note) {
            ENMLUtility *utltility = [[ENMLUtility alloc] init];
            [utltility convertENMLToHTML:note.content withResources:note.resources completionBlock:^(NSString *html, NSError *error) {
                if(error == nil) {
                    [self.webView loadHTMLString:html baseURL:nil];
                }
            }];
        } failure:^(NSError *error) {
            NSLog(@"Failed to get note : %@",error);
        }];

在示例应用程序中的笔记浏览器中查看一些代码示例。

处理过期的认证令牌

您应该检查过期的认证令牌，并在认证令牌过期或被用户撤销后重新触发身份验证。

您可以在错误块中使用 if(EvernoteSession isTokenExpiredWithError:error]) 检查会话是否过期。

常见问题解答（FAQ）

Evernote SDK 支持ARC吗？

是的。要在非ARC项目中使用SDK，请将Evernote SDK中的所有文件都使用 -fobjc-arc 编译器标志。

如果我想要自己进行Evernote Thrift编码怎么办？

EvernoteNoteStore 和 EvernoteUserStore 是在Thrift之上的一个抽象层，并试图减少一些不必要的复杂性。尽管如此，您仍然可以访问底层的Thrift客户端对象：查看EvernoteSession的userStore和noteStore属性。