Overview

With video becoming the new normal, organizations have long wanted to have deeper insight into how the video content is being consumed to make more informed decisions related to marketing campaigns, lead conversion strategies, etc.


In this article, we will be using VIDIZMO REST Services to obtain video analytics related to a certain product that your organization owns and study the response to get meaningful data. This data can then be further used to construct dashboards within your own CRM for the team to base their lead-generation activities on.


To learn more about what VIDIZMO REST Services have to offer and how to get started with using them, see: VIDIZMO REST API Reference Guide.


Use-Case Scenario

Let's assume you have a Custom Attribute "Product Type" added within your Portal that allows you to label your content against the Product it belongs to. This Custom Attribute has value types such as Lite, Standard, Pro.


For your marketing division that heads the Standard product, you want to be able to retrieve all videos of Product Type: Standard, and be able to obtain analytics data on those videos.


In the next sections, we will walk you through using VIDIZMO REST APIs to fetch relevant information about marketing videos and analytics on those videos so that you may integrate it within your preferred CRM solution.


Acquire Access Token

If the videos you are trying to access have been allowed for anonymous access, then you do not need an authentication token, otherwise you will be required to acquire an access token from VIDIZMO and pass it in the Request Header for fetching media in your portal.


Please note that VIDIZMO associates roles to its users which determine the set of permissions a user is allowed to perform in a Portal. Similarly, while accessing a resource using REST API, you will have to consider its user context. This means that if you wish to access or search a video in your Portal's media library such as in this case, you will need to pass the authentication token of a user who has the permission to search and view those videos in the portal.


Note: Public/Anonymous Access is not applicable for Digital Evidence Management Product


In order to fetch videos related to a certain Product Type, we will be executing a api/v1/mashup/search API call with the following search criteria as Query Parameters in the Request URL:

  • The format of the mashup should be video
  • The value of the custom attribute Product Type
  • The video is published in the portal, which is defined by the attribute Status
  • The video is currently available in the portal, which is defined by the attribute Publishing Status
  • Bring back basic information related to the videos such as its title, description, creation-date, thumbnails, etc
  • Fetch first 20 videos that match the search criteria, which is defined by Page Size and Page Index


You can try it out yourself at: https://{your-portal-domain}/api/v1/doc/index.html#/Mashup/SearchMashupsByGet


Here is a sample request and response:


Assemble the Request Message

After you have acquired the authorization token, and have figured out the parameters against which you need to fetch videos from your portal, you can now proceed with sending the request with the following components:


Request Method: GET


Request URL: api/v1/mashup/search

https://{domain}/api/v1/mashup/search?PageIndex=0&PageSize=20&Status=Published&MashupFormats=Video&CustomAttributes=Product%20Type%3AStandard&PublishingStatus=CurrentPublished


Request Header:

Authorization: Bearer <token-obtained>
Content Type: application/json


Process the Response Message

To process the response, parse the response header and the response body. In the HTTPS GET request, you used the /mashup/search endpoint to retrieve the list of mashup based on the search criteria provided. Assuming that the response was successful, you should receive response header fields that are similar to the following:


Response Status Code: 200


Response Header:

 content-type: application/json; charset=utf-8 
 date: Tue, 10 Nov 2020 20:23:57 GMT 
 server: Kestrel 
 status: 200 
 x-powered-by: ASP.NET


And you should receive a response body that contains a list of mashups matching your search-criteria and their individual properties encoded in JSON format, similar to:


Response Body:

{
  "mashups": [
    {
      "id": 266289, //id of the video
      "addedBy": { //details of the user who uploaded this video to the portal
        "id": 218003
      },
      "author": { //details of the author name associated with the video
        "firstName": "Esther",
        "lastName": "Fray",
        "id": 0
      },
      "tenant": { //details of the Portal in which media is uploaded
        "id": 18761,
        "tenantName": "LexCorp Incorporation",
        "subDomainUrl": "{your-portal-domain.com}",
        "isSSLEnable": false,
        "weight": 0
      },
      "category": { //details of the category to which media has been associated
        "id": 25820,
        "name": "Management",
        "weight": 0
      },
      "estimatedDuration": 109599, //duration of the video in milli-seconds
      "title": "LexCorp CEO shares Lex2020 Vision-Clipped", //title of the video
      "version": 12, //current version of the media - everytime the media is updated(title, tags, etc) - its version is updated 
      "thumbnails": [ //details regarding the 3 thumbnails saved against the video
        {
          "thumbnailURL": "http://{storage}/cdn/18761/lex/lexcorpceoshareslex2020visionmp4_clip_5439mp4/f078b8dfbd2e43709e6bdd06e1ae7eb1_3072k_1280x720_404.jpg",
          "thumbnailSize": 720
        },
        {
          "thumbnailURL": "http://{storage}/cdn/18761/lex/lexcorpceoshareslex2020visionmp4_clip_5439mp4/f078b8dfbd2e43709e6bdd06e1ae7eb1_3072k_1280x720_202.jpg",
          "thumbnailSize": 360
        },
        {
          "thumbnailURL": "http://{storage}/cdn/18761/lex/lexcorpceoshareslex2020visionmp4_clip_5439mp4/f078b8dfbd2e43709e6bdd06e1ae7eb1_3072k_1280x720_68.jpg",
          "thumbnailSize": 122
        }
      ],
      "createdDate": "2020-11-10T13:43:00.397", //UTC date and time for when the video was uploaded in the system
      "copyOfMashup": { // details of the video from which this video has either been clipped or copied. In this case, this is a clipped video.
        "id": 263486,
        "estimatedDuration": 0,
        "weight": 0,
        "format": "All",
        "isMyFlaggedMashup": false
      },
      "isDeleted": false, //whether the media resides in the recycle bin
      "isFeatured": true, //whether the media has been featured on the portal
      "updatedDate": "2020-11-10T20:21:36.167", // Last modified date
      "updatedBy": { //id of the user who modified the media last
        "id": 218003
      },
      "size": 12940084, //size of the video in bytes
      "showOnChannelLibrary": true, //whether video has been set to be accessible via Portal Library
      "parentTenant": { //details of the parent Account to a Portal, if any. In this case, the tenant in which media resides is itself an Account so there is no parent tenant to it.
        "id": 0,
        "isSSLEnable": false,
        "weight": 0
      },
      "defaultViewingAccess": "Anonymous", //access-rights set on the media
      "status": "Published", //whether media is published. Other values could be drafted, pending, rejected
      "weight": 39, //The order of the media in the featured media listing that determines its prominence and position on account homepage
      "format": "Video", //format of the media. Other values could be audio, image, document, collection, playlist, quiz, survey
      "isExpired": false, //has the media expired
      "isTranscriptionEnabled": true, //if transcription has been enabled on the media
      "isClipping": true, //if media is a clip generated from an original video in the portal. In this case, yes.
      "isRedaction": false, //if video has redaction enabled 
      "isFaceDetection": false, //if video has face detection enabled
      "isMyFlaggedMashup": false //if video has been flagged
    },
    {...}, //same details as above related to the second video matching search criteria
    {...}, //same details as above related to the third video matching search criteria
    {...}, //same details as above related to the fourth video matching search criteria
    {...} //same details as above related to the fifth video matching search criteria
  ],
  "totalCount": 5
}



The response shall help you retrieve video Ids, thumbnails, titles, descriptions and other relevant information to construct your own product knowledge base gallery within your dashboard. Let's look further into how you may obtain analytics for these videos based on the Ids we have obtained in the response.


Use REST APIs to obtain Video Analytics

Now since you have the media and their relevant Ids, let's look at how to obtain analytics on the media for an sketching an informed user engagement trend chart.


These are the statistics that we shall be obtaining on the videos:

  • impressions
  • views
  • completions
  • time played
  • comments
  • likes
  • favorites
  • shares
  • embeds
  • downloads


In order to fetch analytics on our product videos, we will be using api/v1/analytics/search API call with the following search criteria as Query Parameters in the Request URL:

  • The IDs of the videos we obtained that belonged to our desired Product Type
  • Start Date in UTC format for 1st October 2020 - this defines the start of the period you wish to fetch analytics against
  • End Date in UTC format  for 31st October 2020 -this defines the end of the period you wish to fetch analytics against
  • The frequency of the statistics obtained to be monthly - this helps you segregate data based on a period
  • Force Refresh as true - this fetches updated records from the database. However, to reduce direct hits, it is recommended to have this value as false and fetch records from cache instead. The default refresh time for analytics is 15 minutes.


You can try it out yourself here: https://{your-portal-domain}/api/v1/doc/index.html#/Analytics/SearchAnalyticsByGet


Here is a sample request and response:


Assemble the Request Message

Here is how you can send the request to obtain analytics:

 

Request Method: GET


Request URL: api/v1/analytics/search

https://{domain}/api/v1/analytics/search?MashupIds=266289&MashupIds=263488&MashupIds=263487&MashupIds=263481&MashupIds=263482&MashupAnalyticsParts=MashupAnalyticsStats&StartDate=2020-10-01T00%3A00%3A00.000Z&EndDate=2020-10-31T23%3A59%3A59.999Z&StatsFrequency=Monthly&ForceRefresh=true


Request Header:

Authorization: Bearer <token-obtained>
Content Type: application/json


Process the Response Message

Assuming that the response was successful, you should receive response header fields that are similar to the following:


Response Status Code: 200


Response Header:

 content-type: application/json; charset=utf-8 
 date: Wed, 11 Nov 2020 14:35:23 GMT 
 server: Kestrel
 status: 200 
 x-powered-by: ASP.NET

And you should receive a response body that contains a list of mashups matching your search-criteria and their individual properties encoded in JSON format, similar to:


Response Body:

{
  "mashupStats": [
    {
      "mashupId": 263481, //id of the video
      "tenantId": 1871, //id of te portal to which the video belongs
      "totalComments": 43, //comments on the video
      "totalFavorites": 32, //how many users have favorited the content for easy access
      "totalViews": 566, //how many views the content has received
      "totalLikes": 110, //how many likes have the content received
      "totalViewers": 147, //how many unique number of viewers have watched the content
      "totalCompletions": 48, //how many times the video has been watched in completion
      "totalImpressions": 765, //how many times the video has been loaded but not watched
      "totalPlayTime": 367721, //how much time (in seconds) has the video been played by users
      "totalBuffers": 462, //how much time (in seconds) has the video been buffered
      "totalErrors": 7, //how many errors did the player throw while playing this video
      "totalFormAttempts": 0, //how many times has the quiz/survey been submitted - this is only applicable for mashup_format = Quiz,Survey
      "totalDownloads": 18, //how many times the video has been downloaded
      "totalShares": 65, //how many times the video has been shared via link
      "totalFeedbackImprovements": 2, //how many times did user give feedback on a video as an improvement
      "totalFeedbackIssues": 0, //how many times did user give feedback on a video as an issue
      "totalFeedbackQuestions": 4, //how many times did user give feedback on a video as a question
      "totalFeedbackAbusive": 0, //how many times did user give feedback on a video as a complaint against abusive content
      "totalFeedbackOthers": 9, //how many times did user give any miscellaneous feedback on a video
      "addedDateTime": "2020-09-30T20:00:00", //when was the video uploaded in the portal
      "lastUpdatedTime": "2020-11-11T14:30:00"//when was the video last modified in the portal
    },
    {...}, //same details as above related to the mashupId=263482 
    {...}, //same details as above related to the mashupId=263487 
    {...}, //same details as above related to the mashupId=263488 
    {...} //same details as above related to the mashupId=263489
  ]
}


The response body shall help you further use these actionable insights and construct your own dashboard for every video related to the Standard Product Type. This information shall be a key resource for the marketing and business development departments to use it to construct valuable charts and infographics for the rest of the team to base their next campaigns on.


Read Next