Keep Watching
Miguel Giraldo avatar
Written by Miguel Giraldo
Updated over a week ago

Requires Customer module.

Keep watching is the functionality that allows users to continue watching content from the point where they left off.

With the new keepwatching functionality, it is possible to obtain content and user information, allowing the development of views that indicate the progression of the content:

Video examples:

Audio example:

Integration with this service requires two parts:

  1. Integration with the Mediastream player

    1. The main requirement for using this service is the use of Mediastream players, since this will allow the recording of user consumption metrics.

    2. The functionality is available for any type of content, audio ondemand (AOD) or video ondemand (VOD).

    3. In order for the player to indicate the user that is consuming, the variable "customer" must be transfered,

      Video Integration:

    4. <!doctype html> 
      <html>
      <body>
      <div id="mdstrm-player"></div>
      <script>
      var playerOptions = {
      width: 640,
      height: 360,
      type: "media",
      id: "53453a861536b4526c9bd16e",
      customer: <Customer ID>
      autoplay: false,
      events: {
      }
      };
      var player = new MediastreamPlayer("mdstrm-player", playerOptions);
      player.videoPlay();
      </script>
      </body>
      </html>

      Audio Integration:

    5. <!doctype html> 
      <html>
      <head>
      <script src="https://player.cdn.mdstrm.com/lightning_player/api.js"></script>
      </head>
      <body>
      <div id="player-div">
      </div>
      <script>
      loadMSPlayer('player-div',
      {
      type: 'media',
      id: '5f7f563e34cd7e08221af329',
      customer: '<Customer ID>',
      volume: 0,
      appName: 'appName' }).then(player => {
      /** * Here you can use player api */
      console.log('** player loaded', player) }).catch(console.error)
      </script>
      </body>
      </html>
    6. The <Customer ID> value can be either a user registration platform or an external id, as long as it is sent as a STRING, it can be an email or any code that uniquely identifies the user who is consuming. With this integration, all the consumptions made by the user in this player with its configuration, will arrive on behalf of the user, and the player will associate them with the consumed content.

  2. Site integration

    It must be considered that integration is done using an api token, this token belongs to the account and should not be left public, since it can allow access to the rest of the account information. Therefore, the recommendation is to always make api calls from the server side.

    1. The second part of the integration is to link the user's registered information with the site where he/she is consuming, so that the user can effectively see the status of his/her content.

    1. For this purpose, the "keep-watching" api is available to request this information. The query to this api is done in the same way as the rest of the platform api:

      1. Send authentication through the X-API-Token header, sending the api token, with read privileges and access to the media module.

      2. Response:

        {
        "status": "OK",
        "data": [{
        "account": "<ACCOUNT ID>",
        "customer": "<CUSTOMER ID>",
        "media": "<MEDIA ID>",
        "date": "<PLAYBACK DATE>",//Fecha de la ultima reproducción sobre ese contenido por ese usuario
        "progress": <% progress>, //porcentaje de consumo del usuario en base a la duración.
        "time": <POSITION TIME> //segundo sobre el contenido en el que quedo el usuario en su ultimo consumo
        }]
        }
    2. Commonly implemented functionalities correspond to:

      1. List of the keep watching: A carousel that shows a summary of the medias left pending by the user.

        • This can be implemented by querying the endpoint as follows:

          Sample response:

          {
          "status": "OK",
          "data": [{
          "account": "<ACCOUNT ID>",
          "customer": "<CUSTOMER ID>",
          "media": <MEDIA OBJECT>,
          "date": "<PLAYBACK DATE>",
          "progress": <% progress>,
          "time": <POSITION TIME>
          },
          {
          "account": "<ACCOUNT ID>",
          "customer": "<CUSTOMER ID>",
          "media": <MEDIA OBJECT>,
          "date": "<PLAYBACK DATE>",
          "progress": <% progress>,
          "time": <POSITION TIME>
          }]
          }
        • If you do not pass any parameter other than the <Customer ID>, by default it will deliver the list of pending medias, that remain less than or equal to 95%.

      2. List of medias for a show or section: List more than one media and the playback status of each one for the user.

        • In this case one would be a list of specific medias, it is required to know their playback status in order to visualize them in mass, for example the following mockup:

          where you want to list 8 contents and immediately show which of them have already been viewed and which have not.

        • In this case the query is made to the next endpoint (without /list):
          GET https://api.platform.mediastre.am/keep-watching?customer=<Customer ID>&media[]=<Media ID 1>&media[]=<Media ID 2>

          Sample response:

          {
          "status": "OK",
          "data": [{
          "account": "<ACCOUNT ID>",
          "customer": "<CUSTOMER ID>",
          "media": "<MEDIA ID>",
          "date": "<PLAYBACK DATE>",
          "progress": <% progress>,
          "time": <POSITION TIME>
          },
          {
          "account": "<ACCOUNT ID>",
          "customer": "<CUSTOMER ID>",
          "media": "<MEDIA ID>",
          "date": "<PLAYBACK DATE>",
          "progress": <% progress>,
          "time": <POSITION TIME>
          }]
          }
        • In this case, an array of the media to be queried is sent to the user in the query and the API will respond only with those that have consumption.

      3. Keep watching in the player: when selecting a content that the player is positioned in the timeline where the user was.

        • The query must be performed as in the previous example, but passing only one media.

        • In this case the query is made to the same endpoint: GET https://api.platform.mediastre.am/keep-watching?customer=<Customer ID>&media[]=<Media ID>

          Sample response:

          {
          "status": "OK",
          "data": [{
          "account": "<ACCOUNT ID>",
          "customer": "<CUSTOMER ID>",
          "media": "<MEDIA ID>",
          "date": "<PLAYBACK DATE>",
          "progress": <% progress>,
          "time": <POSITION TIME>
          }]
          }
        • This will return the information of a single content for the requested user, with this information and the value of "time", this data must be passed to the player, with the starttime parameter supported in the playerOptions.

        • You can find more information about the player options by clicking on the following link: https://platform.mediastre.am/developer

          *You must have platform access

Examples:

Video player integration and consumption:


{
"status": "OK",
"data": [
{
"account": "<ACCOUNT ID>",
"customer": "<CUSTOMER ID>",
"media": {
"_id": "<MEDIA ID>",
"duration": 6393,
"thumbnails": [<THUMNAIL DEFAULT>],
"title": "<MEDIA TITLE>",
"preview": {
"mp4": "<URL PREVIEW>"
}
},
"date": "2022-01-20T14:14:51.216Z",
"progress": 5,
"time": 318.85
}
]
}

If you have any related questions please feel free to write to us.

Atte. Mediastream team

Did this answer your question?