Evernote China (YXBJ) Bootstrapping

Connecting to Evernote China w/ Bootstrapping API

• Original article

  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	https://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	https://evernote.com
  serviceHost	evernote.com
  supportUrl	https://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).