Integrate the Vidyard Partner App into your product

What is the Vidyard Partner App?

The Vidyard Partner App is an embeddable iframe that renders a single-page javascript application to interface with Vidyard's APIs.

The Partner App allows users to:

• Sign in to their Vidyard account and access their video library
• Share videos from their library (via the application or messaging tool that they're using; for example, an email client).
• Record new videos (camera or screen recording)
• Identify viewers who watch videos shared from the app (through use an email tracking token)

When a video is shared, the Partner App provides a simple callback through the use of a custom window event that the host application (you, the partner) can then use to retrieve details about the newly created player.

Integrating the Vidyard Partner App: who's responsible for what?

Register as a Vidyard partner

Before you can integrate the Partner App into your product, you must first register as a partner.

Email the following details to govideopartners@vidyard.com. Our team will reach our to discuss implementation details and, if approved, provide you with a unique clientId. The clientId is needed to embed Vidyard into your application.

1. The name of your product/application
2. A link to your company's website
3. A link to your product's privacy policy
4. A link to your product's terms of service
5. An icon (50-50px) for your product/application
   • We recommend a PNG file with a transparent background
6. The domains (both staging and production) where you'll be using the Partner App:
   • We'll add the domains to a list of permitted locations for your clientId
   • Your company must own the domains (i.e. localhost is not accepted); however, reserved domains (through a service like ngrok) are permitted.
   • Please include the full domain url including the protocol (http:// or https://)
7. A short blurb about what you plan to do with the Vidyard Partner App

Embed the Vidyard Partner App into your product

1. Create a div where the app will be displayed:
   

   <div id="VidyardApp"></div>

   • We recommend using an icon indicative of video creation. Download our video icon image to use.
     
2. Call the Vidyard library using the following embed code:
   • Enter your client ID in the provided location.
   • A typical and recommended use case involves adding a known recipient's email address to the embed script. This allows you to use response.embed_codes.thumbnail and response.embed_codes.branded_sharing_page to insert a hyperlinked thumbnail and video URL onto a page or a communication workflow.
     

     <script type="text/javascript" src="https://app.vidyard.com/v1/embed.js"></script>
     <script type="text/javascript">
       // You must create the Library before you can use it
       const library = Vidyard.goVideo.createLibrary(
         document.getElementById('VidyardApp'),
         {
           // The clientId for your application provided by Vidyard
           clientId: '<<provided client ID>>',
           recipientEmail: <<emailID>> //insert known email address
         }
       );
     </script>

3. Append the following callback script to the library embed code
   • The goal is to add a hyperlinked thumbnail and video sharing page URL on to a page or text editor using a function.

     library.on('player:created', function (response) {
      // Your code goes here in this function	
      alert('Player Created!');		
      console.log(response.player, response.embed_codes);		
     });

After the user inserts a video or playlist, the library will issue a callback (response.player) to the host application that contains the complete details of the player (player name, description, UUID, chapters, length, various settings, etc).

The data returned in response.embed_codes contains the player embed codes, video sharing link and thumbnail URL). This information allows your application to display the thumbnail, provide a direct link to the video sharing page, or embed the player.

Replace the alert and console.log functions with the action that you want your application to execute when a player is created.

Expected end result

An ideal output will look like the following (this the Vidyard Partner App in Gmail):

It is highly recommended that you include both the thumbnail image link and a link to the sharing page in the body of the message.

• The thumbnail encourages recipients of the video to clickthrough to the sharing page.
• The sharing page URL is important as a fallback (if images are blocked).
• The sharing page URL is also used by salesforce.com and other services that can scan the body of email messages to populate data in "video emails sent" reports.

The complete code

<!--
This div can be hidden this using 'display: none' or put it off screen if you are not ready to show it yet.

It must come before the embed script or be loaded prior to the Vidyard Partner App being used!
-->
<div id="VidyardApp"></div>
<script type="text/javascript" src="https://app.vidyard.com/v1/embed.js"></script>
<script type="text/javascript">
  // You must create the Library before you can use it
 const library = Vidyard.goVideo.createLibrary(
  document.getElementById('VidyardApp'),
  {
   // The clientId for your application provided by Vidyard
   clientId: '<<provided client ID>>',
   recipientEmail: <<emailID>> //insert known email address
  }
 );
  library.on('player:created', response => {
   // Your code goes here in this function
   alert('Player Created!');
   console.log(response.player, response.embed_codes);
  });
</script>

Identifying viewers

Vidyard uses browser cookies to help users identify who has watched a video(s). The cookie has an ID that Vidyard uses to associate a viewer's email address with their video view.

In the example above recipientEmail: <<emailID>> assumes the email address is a known value prior to adding the thumbnail and sharing link to a page. An API call is automatically made to generate and include a hashed email ID token with the sharing page link (a "vyetoken").

If the video recipient is not immediately known when the thumbnail and sharing link are created, use the Vidyard dashboard API to dynamically generate a new set that includes the vyetoken.

• Include the vyemailparameter in the POST call, either as a query string or in the body of the POST. This will ensure a "vyetoken" is appended to the sharing link and embed option.
• Because the Partner App is also compatible with our personalized video engine, a custom_id parameter in the embed code or sharing page link is required in order to populate personalized data. If a custom_id is present in the response.player callback, make sure to also include it as part of the POST call to generate the sharing page link or embed code.

REQUEST 
POST https://api.vidyard.com/api/v1/players/uuid=qrYGmWuYwTmEsPnVAiplgw/embed_codes
Accept: application/json
{
  "vyemail": "vbot@vidyard.com",
  "custom_id": "12345678"
}

RESPONSE
200 (OK)
{
  "sharing_page": "http://secure.vidyard.com/share/qrYGmWuYwTmEsPnVAiplgw?custom_id=12345678&vyetoken=c082e9eb-3f56-4488-874c-1ff5125fdb85",
  ...
}

Obtain viewer consent to use browser cookies

Vidyard uses browser cookies to tell users when someone has watched their videos and, if possible, identify who those viewers are.

With the introduction of data privacy laws in Europe (GDPR, May 2018) and elsewhere, it's important that, when needed, you build the proper consent mechanisms into your application wherever a viewer interacts with a video from Vidyard.

The Vidyard Player API contains methods that allow you to communicate to a video player whether a viewer has consented to having identified data passed to Vidyard.

Here's a helpful chart to determine whether you need to implement a cookie consent mechanism:

End user recording functionality

The Vidyard Partner App allows you users to record new videos directly from their library. The available recording options will differ depending on the browser being used.

If a recording option is not available, users should either open a different browser or record a video with the browser extension (for Chrome or Edge).