引导过程

使用Bootstrapping API 将应用连接到印象笔记


General Description

在过去的一年里,Evernote 发布了一个全新的,完全独立的叫印象笔记的中国版服务。印象笔记可以给中国用户更好的用户体验。如果要了解这件事的来龙去脉,请访问我们的上线中国服务的博文

我们希望让开发者容易地开发可以让所有我们的用户使用的应用。我们在中国的用户群一直在快速增长;中国已经是用户数目第二大的国家。你可以选择把印象笔记和/或Evernote集成到你的应用。

对于大部分功能来说,这两个服务提供相同的 "Evernote" 功能。Evernote 和印象笔记是并行开发的并且共享大部分代码库、API 和功能。两个服务的 API 也是完全相同的,所以我们的 SDK 同时支持这两种服务。开始的时候,印象笔记不会支持共享和社交功能。当我们完成与中国本土的社交网络公司的集成后,才会开放这些功能。

因为印象笔记服务和已有的 Evernote 服务是完全分开的服务,我们开发了一个引导协议来帮助开发者的应用能够被这两类用户使用。我们会在下面介绍引导过程的细节。


引导过程的描述

如果你希望 Evernote 和印象笔记的用户都能使用你的应用,那么你必需实现引导协议。

”引导过程“提供了一种可以确认用户帐户所在服务的方法。用户帐户可以在 evernote.comyinxiang.com 上。如果引导过程不能确定,那么两种选项将会被显示出来让用户选择。

引导服务器所使用的规则是基于设备的区域设置和所在的国家(由 IP 地址决定)的。引导服务器返回一个或多个配置(profile)作为结果。如果返回了多个配置,那么必需提供所有的配置给用户并让用户进行选择。这个选择在一些情况下是必需的,比如用户正在旅行,用户偏好某个服务,或者用户在印象笔记上线前就有了 Evernote 帐户。如果只返回了一个配置,那么将使用 evernote.com 或 yinxiang.com。

因为不同的服务对应不同的界面,命名和品牌,你的应用需要在显示界面前就知道正确的服务信息。Evernote 与印象笔记之间的命名和品牌的差别在后面有详细介绍。


当连接到一个用户的帐户时,如何在你的应用中实现引导过程

iOS 开发者:目前,如果初始化 EvernoteSession 时提供了supportedService 参数,那么印象笔记 iOS SDK 会自动完成引导逻辑。请查看 iOS SDK README 来获取更多信息。

另外,如果区域格式(可在 iOS 的 Settings -> General -> International 中找到)设置成了 Chinese -> China,那么你的应用会从服务器收到印象笔记(中国)的引导配置。

Android 开发者: 印象笔记 Android SDK 会在即将到来的 release 版本中包含类似的功能。

Web 应用开发者:  你可以在 HTTP 请求头中使用 accept-language 头部信息,来辨别那些需要在 www.evernote.comapp.yinxiang.com 之间作出选择的用户。与其他平台不一样的是,你不需要调用UserStore.getBootstrapInfo。如果 accept-language 是“zh-CN” 或 “zh_CN”(不考虑大小写),那么就会提示用户在 "Evernote International" (Evernote 国际版) and "印象笔记" 两个服务之间作选择。对于所有其他的 accept-language 的值,则只会展示 Evernote International 版本的服务。

其余所有:我们计划在未来将此功能添加到其他的 SDK 中(按照用户提出的要求)

要实现引导过程,你的应用需要调用 UserStore.getBootstrapInfo()。这个函数会返回一个或多个保存在 BootstrapInfo 中的服务的“配置”。这些配置包括各种设置 - 最重要的就是你访问服务需要使用的 URL。

应用中的引导过程的逻辑:
  1. 你的应用显示一个连接用户印象笔记帐户的按钮或链接。

    • 如果设备的区域设置是简体中文,按钮显示“连接到我的印象笔记帐户”。
    • 如果设备的区域设置是其他语言,按钮用恰当的语言显示“连接到我的 Evernote 帐户”。
  2. 当用户通过点击来连接到他们的帐户时,应用会在其中一个硬编码的引导服务器 URL 上调用 UserStore.getBootstrapInfo()

    • 如果当前的区域设置时简体中文(zh, zh_CN, zh_Hans, zh_Hans_CN),那么选择使用中国的引导 URL:app.yinxiang.com
    • 否则,选择 Evernote 国际版的引导 URL:www.evernote.com

    当调用 UserStore.getBootstrapInfo() 时,应用将用户的区域设置作为一个单一的 [language]_[country] 字符串传递进去。(详细的信息请参考 UserStore.getBootstrapInfo()

  3. 你的应用遍历所返回的 BootstrapInfo 列表

    • 如果只返回了一个服务配置:

      • 跳到下面的第四步。
    • 如果返回了多个服务配置:

      • 提供给用户选项/下拉列表来让用户选择他们的服务。
      • 偏好的配置(就是返回的第一个配置)应当显示为默认选项。
      • 一旦用户选择了一个服务,你的应用就可以来到下面的第四步。

      注意:when presenting the user with the option to select their service, the names must appear as "Evernote International" (for Evernote) and "印象笔记" for Yinxiang Biji. Optionally, you can use "我是印象笔记用户" in your UI (which means "I am a Yinxiang Biji user").给用户提供选项选择服务的时候,选项名称必须显示为“Evernote International”(Evernote 国际版)和“印象笔记”。或者,你可以在 UI 中显示“我是印象笔记用户”。

  4. 你的应用使用服务配置中的 serviceHost 值来发起一个 OAuth 认证过程(例如 https://serviceHost/oauth)。

根据服务配置的值创建 UserStore 和 NoteStore API 请求的规则:
  • 用作 OAuth 请求的 URL 是 https://serviceHost/oauth
  • 把 “/edam/user” 添加到返回的 EDAM 基本 URL 后面就可以组成用作后续 UserStore API 请求的 URL。
API Key 的激活

实现引导过程的应用需要在两个生产服务(evernote.com 和 yinxiang.com)上激活它们的 API key ()。你可以在 dev.evernote.com 申请激活你的 API key。


配置和 IP 规则

下表显示了引导服务器为了返回一个或多个配置所使用的结合 IP 地址和区域设置的规则。

IP 来源国家 区域设置 配置(按照偏好排序)
中国 中国大陆 印象笔记,Evernote 国际版
中国 中国大陆以外 Evernote 国际版
中国以外 中国大陆 Evernote 国际版,印象笔记
中国以外 中国大陆以外 Evernote 国际版
*(“中国大陆” 区域设置包括:zh, zh_CN, zh_Hans, zh_Hans_CN)
调用 UserStore.getBootstrapInfo() 返回的 BootstrapInfo 形式的服务配置示例

印象笔记配置

设置 生产环境中的值
marketingUrl http://yinxiang.com
serviceHost app.yinxiang.com
supportUrl https://support.yinxiang.com
accountEmailDomain m.yinxiang.com
enableTwitteSharing False
enableFacebookSharing False
enabledSharedNotebooks False
enableSingleNoteSharing False
enableSponsoredAccounts False
enableGiftSubscriptions False

Evernote 国际版配置

设置 生产环境中的值
marketingUrl http://evernote.com
serviceHost evernote.com
supportUrl http://www.evernote.com/about/contact/support/
accountEmailDomain m.evernote.com
enableTwitteSharing True
enableFacebookSharing True
enabledSharedNotebooks True
enableSingleNoteSharing True
enableSponsoredAccounts True
enableGiftSubscriptions True

品牌指导方针

两个服务的命名和品牌示不同的。

在登陆和注册界面完成之前,必需要确定服务的品牌。下面是印象笔记和 Evernote 国际版的品牌原则

公司名称: Evernote

产品名称: Evernote International

产品名称(简体中文): 印象笔记

Logo 下载: Evernote International, 印象笔记

其他

测试

注意:要接收多个引导配置,你的应用必须连接到产品环境的服务器——www.evernote.com 或 app.yinxiang.com。如果你的应用连接到的是 sandbox.evernote.com,那么只会接收到 Sandbox 的引导配置(与你的语言或地区设置无关)。