Merge pull request #21 from SRGSSR/develop

Develop personal recommendation API

docs/README.md

@@ -24,7 +24,8 @@ A wide list of parameters are available.
  * `urn` (string): an unique identifier.
  * `recommendedList` (object): a recommended result list with proterties:
  	* `recommendationId` (string): the recommendation identifer from the service.
- 	* `urns`(array): array of `urn`.
+ 	* `urns` (array): array of `urn`.
+ 	* `title` (string, optional): title of the playlist.
  * `package` (string): Android package name or iOS bundle identifier.
  * `version` (string): mobile application version.
 
@@ -43,16 +44,22 @@ A wide list of parameters are available.
 * `/api/v1/whatisnew/text?package={package}&version={version}` : get WhatIsNewResult object.
 * `/api/v1/whatisnew/html?package={package}&version={version}` : get What's new html format.
 
-#### Recommendation
+#### Recommendation for a media
 
 * `/api/v2/playlist/recommendation/continuousPlayback/{urn}` : get media list object.
 	* `standalone` (optional, boolean): Recommendation for the playback mode. Default is `false`.
 	* Returns a `recommendedList` object.
 
-* `/api/v1/playlist/recommendation/continuousPlayback/{urn}` : get media list object.
+* *Deprecated* `/api/v1/playlist/recommendation/continuousPlayback/{urn}` : get media list object.
 	* `standalone` (optional, boolean): Recommendation for the playback mode. Default is `false`.
 	* `format` (optional, string): If set to `urn`, it returns an URN list. Default is `media` and redirects to an IL media list response.
 
+#### Personnal recommendation for a user
+
+* `/api/v2/playlist/recommendation/personalRecommendation` : get media list object.
+	* `user` (optional, string): `UserId` to use for a personal recommendation.
+	* Returns a `recommendedList` object.
+
 ## Private APIs
 
 Private APIs need a user authentification.

docs/RECOMMENDATION.md

@@ -7,25 +7,28 @@ Playfff is the middleware to deliver recommendations for Play SRG mobile applica
 
 ## Compatibility
 
-Since July 2018, Play Android (2.0.207 and more) and Play iOS (2.8.3-272 and more) applications currently use it.
+Since July 2018, Play Android (2.0.207 and more) and Play iOS (2.8.3-272 and more) applications currently use this recommendation service.
 
 ## Recommendation type
 
 ### Media ecommendation list for a media
 
-The API doesn't not support paginations, so mobile applications didn't implement pagination. The media recommendation list must have at least 49 items, the 50th is the requested media itself.
+The API doesn't not support paginations, so mobile applications didn't implement pagination. The media recommendation list must have at least 49 items, the 50th is the requested media.
 
 #### RTS `urn.contains(":rts:")`
 
-- For videos `urn.contains(":video:")`, ask Peach recommendation `continuous_playback_mobile`.
-- For audios `urn.contains(":audio:")`:
+- For videos `urn.contains(":video:")`, ask Peach recommendation `continuous_playback_mobile` service.
+- For audios `urn.contains(":audio:")`, Playfff recommendation. Based on IL requests, without personalization. Here is how it works:
 	- Get `IL-Media`. It returns an empty list if it's a `LIVESTREAM` or a `SCHEDULED_LIVESTREAM`.
-	- Get `IL-EpisodeComposition`, last 100 episodes. Sort in date ascending order.
-	- Determine if the media is a full length or a clip. Separate full length list and the clip list.
-	- Get the media position in the related lists. Split oldests and newests.
+	- Get `IL-EpisodeComposition` with last 100 episodes. Sort episodes with a date ascending order.
+	- Determine if the media is a full length or a clip.
+	- Separate in a full length list and a clip (audio only) list.
+	- Get the requested media position in the related list. Split oldests and newests.
 	- Recommendation list:
-		- Newest medias in date ascending order. Then:
-		- if `nextUrl` exists (show has more than 100 episodes), oldest medias in date descending order.		- else (show has less than 100 episodes), oldest medias in date ascending order.
+		- Newest medias in the date ascending order.
+		- Then:
+			- *If* `nextUrl` exists (show has more than 100 episodes), oldest medias in the date descending order.
+			- *Else* (show has less than 100 episodes), oldest medias in the date ascending order.
 
 #### Other BUs