Evernote China (YXBJ) Bootstrapping

Connecting to Evernote China w/ Bootstrapping API


General Description

Evernote provides a separate Chinese service called Yinxiang Biji (印象笔记) to give users in China a great Evernote experience. To read more background on what it's all about, why we did it, and what it means - see our China service launch blog post.

We want to make it easy for developers to build great apps and integrations that can reach all of our users. Our user base in China is growing quickly; it has already become our second largest country. You now can choose to integrate your apps with Yinxiang Biji, Evernote, or both.

For the most part, these services offer the same "Evernote" functionality. Evernote and Yinxiang Biji will be developed in parallel and share much of the code-base, API, and features. The API for each service is also identical, so our SDKs support both services. Sharing features between the two systems differ slightly in the following ways:

  • Yinxiang Biji supports public notes, but not public notebooks. Yinxiang Biji users can share notebooks with individual users.
  • Users must be logged in to Yinxiang Biji to view public notes.
  • Yinxiang Biji does not support sharing to social networks like Facebook and Twitter.

Since the Yinxiang Biji service is completely separate from the existing Evernote service, we built a bootstrapping protocol to help developers' apps work with both sets of users. We explain how bootstrapping works in detail below.


Description of Bootstrapping

For your app to work for users of both Evernote International and Yinxiang Biji, you must implement the bootstrapping protocol.

The concept behind "bootstrapping" is that it provides a way to know whether a user's account is most likely on evernote.com, yinxiang.com, or if they need to be presented with the option to choose.

The bootstrap server identifies these rules based on a combination of locale and country (determined by IP address). To communicate the result, the bootstrap server returns 1 or more profiles. A choice between services must only be provided to the user if multiple profiles are returned. The selection is necessary for the cases when a user is traveling, has a preference for a service, or may have already had an Evernote account prior to the launch of the Yinxiang Biji service. If only 1 profile is returned, either evernote.com or yinxiang.com will be identified as the service to use.

Your app needs to know this information before showing any Evernote UI since it changes the UI, naming, and branding. The naming and branding differences between Evernote International and Yinxiang Biji are detailed below.


How to Implement Evernote China in Your App when linking to a User's Evernote Account

iOS Developers: currently, the Evernote SDK for iOS will automatically perform the bootstrapping logic if the supportedService parameter is supplied when instantiating EvernoteSession. See the iOS SDK README for more information.

Also, if the Region Format setting (found in the International area under General in the Settings app on iOS) is set to Chinese > China, your app will receive the Evernote China bootstrap profile from the server.

Android Developers: the Evernote SDK for Android will contain similar functionality in an upcoming release.

Web App Developers:  you can use the accept-language header in the HTTP request to identify users that should be given a choice between connecting to www.evernote.com or app.yinxiang.com. Unlike other platforms, you do not need to call UserStore.getBootstrapInfo. If the accept-language is "zh-CN" or "zh_CN" (regardless of capitalization), the user should be prompted to choose between the two services "Evernote International" (for Evernote) and "印象笔记" (for Yinxiang Biji). For all other accept-language values, you will only show the Evernote International service.

All Others: we plan to add this feature to other SDKs in the future (as dictated by user demand).

To implement bootstrapping, your app will make a call to UserStore.getBootstrapInfo(), which returns 1 or more service "profiles" with a BootstrapInfo response. These profiles include a variety of settings - most importantly, the URLs you should use to access the service.

Summary of the Bootstrap Logic for an app:
  1. Your app shows a button/link to link a user's Evernote account.

    • If the device locale is Simplified Chinese, the button says "Link my Yinxiang Biji account" in Chinese.
    • If the device locale is something else, the button says "Link my Evernote account" in the appropriate language.
  2. When User taps/clicks to link their account, the app calls UserStore.getBootstrapInfo() to one of the 2 hardcoded bootstrap server URLs.

    • If the current locale is Simplified Chinese (zh, zh_CN, zh_Hans, zh_Hans_CN), choose the China bootstrap URL: app.yinxiang.com
    • Otherwise, choose the Evernote International bootstrap URL : www.evernote.com

    When calling UserStore.getBootstrapInfo(), the app will pass in the user's locale as a single [language]_[country] string (see UserStore.getBootstrapInfo() for details)

  3. Your app iterates through the returned list of BootstrapInfo.

    • If a single service profile is returned:

      • Go to step 4 below.
    • If multiple service profiles are returned:

      • Provide some sort of choice/dropdown to the user to allow them to select their service.
      • The preferred (i.e. 1st profile returned) should be shown as the default selection.
      • Once the user selects a service, your app can go to step 4 below.

      Note: 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").

  4. Your app initiates the OAuth process using the serviceHost value from the service profile (example profile below — e.g., https://serviceHost/oauth).

Rules for building the UserStore and NoteStore API requests with the the service profile settings' values:
  • The URL used for OAuth requests https://serviceHost/oauth.
  • The URL used for all subsequent UserStore API requests is assembled by appending “https://serviceHost/edam/user” to the returned EDAM base URL.
API Keys and Activation

Apps that implement bootstrapping will need their API Key activated on both production services (evernote.com and yinxiang.com). You may request to have your API Key activated from dev.evernote.com.


Profiles and IP Rules

The table below shows the rules combining IP and locale that the bootstrap server users in order to return one or more profiles.

IP Origin Country Locale Profiles (in order of preference)
China Mainland-China Evernote China, Evernote Intl
China Not Mainland-China Evernote Intl
Not China Mainland-China Evernote Intl, Evernote China
Not China Not Mainland-China Evernote Intl
*(“Mainland-China” locales include: zh, zh_CN, zh_Hans, zh_Hans_CN)
Example Service Profiles returned as BootstrapInfo when calling UserStore.getBootstrapInfo()

Evernote China Profile

Setting Production
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 International Profile

Setting Production
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

Branding Guidelines

The actual naming and branding of the two services is distinct.

Before the login & registration UIs can be complete, the branding of the services must be established. The following are the branding rules for Evernote China and Evernote International.

Company Name: Evernote

Product Name: Evernote International

Product Name (in Simplified Chinese): 印象笔记

Logo Downloads: Evernote International, 印象笔记.

Miscellany

Testing

Note that your app must be connecting to a production server—www.evernote.com or app.yinxiang.com—in order to be sent multiple bootstrap profiles. If your app is configured to connect to sandbox.evernote.com, only the bootstrap profile for Sandbox will be returned (irrespective of your language or locale settings).

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