Connecting your app to Evernote China using the Bootstrapping API
This past year, Evernote unveiled a new, completely 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. Initially, Yinxiang Biji will not have support for sharing and social features until we complete the integration with Chinese social networking companies.
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 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:
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.
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)
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").
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
Evernote International Profile
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): 印象笔记
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).