Sharing Notes
Private and public note sharing
A user can share his or her Evernote notes and notebooks with a specific user, a certain group of users or the world.
This diagram shows the different sharing options in Evernote:
Sharing options
[1] Generate unique URL giving access to everybody who knows the URL
[2] Grant access to a specific notebook to specific Evernote users
[3] Make a notebook public and share it with the world
Sharing a single note
Sharing a single note by URL
You can also share a single note by generating a URL that will allow anybody who knows the URL to view the note in a browser. The URL always shares the current content of the note, so if the note is changed after it is shared, the recipients will see the changes.
Important
An application may only turn on sharing for a note when the user explicitly chooses to do so - for example by tapping a "share" button. You may never enable sharing without the user's explicit consent.
To enable sharing by URL for a note, you must first turn on sharing using shareNote. This will generate a share key, which you can then use to assemble the URL:
https://host.evernote.com/shard/shardId/sh/noteGuid/noteKey
For example:
In the URL above, the shardId is s1, the note's GUID is 3554a82b-54d3-4673-8641-2bbcac94bbff, and the share key is d368012bd2c3ce342c709fefd26355a7.
$noteGuid = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
$shareKey = $noteStore->shareNote($authToken, $noteGuid);
$url = "https://www.evernote.com/shard/" + $shardId + "/sh/" + $noteGuid + "/" + $shareKey;
Sharing can be turned off for a given note using stopSharingNote. Once stopSharingNote has been called, previously shared URLs will stop working. If sharing is later re-enabled, a new share key will be generated and a new URL will need to be assembled.
An application can also read a shared single note if it has the components used to assemble the sharing URL. Here's how your can read the note that I shared above:
$sharedGuid = "3554a82b-54d3-4673-8641-2bbcac94bbff";
$sharedKey = "d368012bd2c3ce342c709fefd26355a7";
$sharedShard = "s1";
// Create a NoteStore client for the shard hosting the note's owner
// This could be a different shard than the user who is signed into Evernote from your app
$trans = new THttpClient(NOTESTORE_HOST, NOTESTORE_PORT, '/edam/note/' . $sharedShard, 'https');
$prot = new TBinaryProtocol($trans);
$sharedNoteStore = new NoteStoreClient($prot, $prot);
$sharedAuthResult = $ExternalNoteStore->authenticateToSharedNote($sharedGuid, $sharedKey);
$sharedAuthToken = $sharedAuthResult->authenticationToken;
$note = $sharedNoteStore->getNote($sharedAuthToken, $sharedNoteGuid, true, true, false, false);
Sharing entire notebooks
Users can also share entire notebooks, either with specific recipients or publicly. Notebooks that are shared with specific recipients can optionally require the recipient to log into Evernote to view the shared notebook. Premium users can also allow recipients to modify the notes within a shared notebook. Because of the number of possible configurations, sharing notebooks is relatively complex.
There are two data model objects involved in sharing notebooks - SharedNotebook and LinkedNotebook. The SharedNotebook object lives in the notebook owner's account - think of it as an invitation to view a specific notebook. The LinkedNotebook object lives in the share recipient's account and represents a persistent link to the notebook in the owner's account. Because users can view shared notebooks without logging into Evernote (if the notebook owner allows them to), there doesn't need to be a LinkedNotebook for every SharedNotebook.
Sharing a notebook
To share a notebook, you create a SharedNotebook object in the notebook owner's account. A SharedNotebook shares the notebook with a single email address, so to share a notebook with three friends, you will create three SharedNotebook objects.
$sharedNotebook = new edam_type_SharedNotebook();
// The email address of the person who the notebook is being shared with
$sharedNotebook->email = "recipient@email.com";
// Can the recipient browse the notebook without logging into Evernote?
$sharedNotebook->requireLogin = true;
// Is the recipient allowed to create new notes and modify existign notes in the notebook?
$sharedNotebook->notebookModifiable = false;
// The GUID of the Notebook that is being shared
$sharedNotebook->notebookGuid = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
$sharedNotebook = $noteStore->createSharedNotebook($accessToken, $sharedNotebook);
Creating a SharedNotebook doesn't automatically generate an invitation to the recipient. If your application turns on sharing for a notebook by creating a SharedNotebook, you will need to ensure that the recipient receives the information that they need to access the share. Similarly, LinkedNotebooks are not created automatically. The Evernote service can create a LinkedNotebook when a user views a shared notebook invitation in their browser, or your application can programmatically accept the share and create the LinkedNotebook in the recipient's account.
Reading notes from linked notebooks
When your application accesses a user's Evernote account through the Cloud API, you can get a list of LinkedNotebooks - notebooks owned by another user that have been shared with your user. Once you have that list, you can acess the notes in the owner's notebook. To do this, you need to create a second NoteStore connection, since the owner's account and the recipient's account may be on different shards. Using that NoteStore connection, you can obtain a second authentication token that will allow you to access the contents of the shared notebook.
$linkedNotebooks = $noteStore->listLinkedNotebooks($authToken);
$linkedNotebook = current($linkedNotebooks);
$parts = parse_url($linkedNotebook->noteStoreUrl);
if (!isset($parts['port'])) {
if ($parts['scheme'] === 'https') {
$parts['port'] = 443;
} else {
$parts['port'] = 80;
}
}
$sharedNoteStoreHttpClient =
new THttpClient($parts['host'], $parts['port'], $parts['path'], $parts['scheme']);
$sharedNoteStoreProtocol = new TBinaryProtocol($sharedNoteStoreHttpClient);
$sharedNoteStore = new NoteStoreClient($sharedNoteStoreProtocol, $sharedNoteStoreProtocol);
$sharedAuthResult =
$sharedNoteStore->authenticateToSharedNotebook($linkedNotebook->shareKey, $authToken);
$sharedAuthToken = $sharedAuthResult->authenticationToken;
$sharedNotebook = $sharedNoteStore->getSharedNotebookByAuth($sharedAuthToken);
// We now have the GUID of the Notebook object that was shared with us
$filter = new edam_notestore_NoteFilter();
$filter->notebookGuid = $sharedNotebook->notebookGuid;
$noteList = $sharedNoteStore->findNotes($sharedAuthToken, $filter, 0, 10);
print "Found " . $noteList->totalNotes . " shared notes\n";
Once you have an authentication token to read from the shared notebook, you can use any of the NoteStore functions to interact with the notes in that notebook. The sample code above uses findNotes to get all of the notes in the shared notebook. Note that you need to you must set the NoteFilter.notebookGuid to the appropriate notebook GUID when using findNotes and findNotesMetadata on a shared notebook.
Synchronizing linked notebooks
For a complete guide on synchronizing linked notebooks, download the synchronizing guide.