开发规范和建议

给第三方开发者的准则和建议

印象笔记API授权协议

如果你准备使用印象笔记或者Evenote International API，你必须接受印象笔记API授权协议中的条款。请确保你在接受协议之前已经阅读并且理解了印象笔记API授权协议中的所有条款。当前正在生效的协议发布在 http://dev.yinxiang.com/doc/reference/api_license.php。

印象笔记商标和使用准则

我们使用商标来标识我们的产品和服务，包括名字、logo、单词、字符和颜色等。为保证我们的产品和服务不被混淆，同时也为保证我们同开发人员、合作伙伴及Evernote大生态系统中的其他成员之间的关系，我们指定了一些使用准则。当你设计和命名你的应用、产品和域名的时候，你必须遵循这些准则。关于印象笔记商标和使用准则的详细内容请参考http://www.yinxiang.com/trademark/。

正确显示印象笔记服务名称

• 在应用中需要显示印象笔记服务的名称时，必须使用印象笔记;
• 在应用中需要显示Evernote International的名称时，必须使用Evernote International或者EVERNOTE INTERNATIONAL;
• 任何时候，当需要使用Evernote单词来标识Evernote服务时，必须使用Evernote或者EVERNOTE；禁止使用evernote或者EverNote。

错误处理

当你使用云API开发的时候，你的应用必须正确的处理API返回的错误。有三个最常见并且在应用中应该妥善处理的错误：Authentication Failure， Quota Exceeded 和 Maximum Note Size。

当调用云API的时候，如果碰到EDAMUserException或者EDAMNotFoundException异常，你的应用绝对不要自动重试该API，因为这些错误不会自己解决。

关于更多错误处理的内容，请参考该文档。

注销机制

在你的应用中，我们要求你必须提供一个机制让用户从印象笔记或者Evernote International服务中退出并且清除缓存在你的应用中的所有信息。

同时支持印象笔记和Evernote International

印象笔记和Evernote International服务是完全独立的，但是在中国既有印象笔记用户也有Evernote International用户，所以一般建议开发者同时支持两种服务。幸运的是它们使用的API是完全相同的，所以开发者只需要做很少的工作就能让应用同时支持两个服务：

• 申请在印象笔记和Evernote International都激活API key；
• 在应用中实现引导过程(bootstrapping)协议。

如果你的应用只面向中国用户，也可以不实现引导过程协议，但是应该提供选项让用户选择使用印象笔记还是Evernote International。当使用印象笔记服务的时候，服务器地址为app.yinxiang.com，当使用Evernote International的时候，服务器地址为www.evernote.com。

保存到印象笔记

印象笔记不是一个面向社交网络的服务，所以当第三方应用保存信息到印象笔记中的时候，不应该使用类似“分享到印象笔记”的描述，我们建议开发者使用“保存到印象笔记”来描述该功能。

sourceURL属性

每一条笔记都有一个sourceURL属性，它标识了这条笔记的来源。它可以帮助用户访问原始的网站以获取更多的关于该笔记的信息，并且用户还可以通过该属性进行搜索。如果你的应用中保存的信息有准确的来源，我们强烈建议设置该属性。关于该属性的具体描述，请访问API参考文档.下图展示了设置sourceURL属性后，在印象笔记Web版查看该笔记的视图。

良好的用户体验

良好的用户体验不仅体现在第三方应用本身的用户界面和交互设计上，而且要求应用所生成的笔记有非常好的可读性。为了让用户获得更好的阅读体验，我们建议开发者在应用里面使用内联CSS来格式化笔记。关于如何在印象笔记API中使用CSS,请参考该文档。

需要注意的是：在使用CSS来格式化笔记信息的时候，开发者需要确保笔记在所有平台都能很好的显示，包括桌面设备和移动设备。例如，笔记不应该在桌面电脑上能正确显示，而在iPhone上却看起来很糟。 下面的图片展示了一条由第三方应用生成的，格式非常好的笔记。