How to Enable Facebook / Video Deep Linking (Sharing)

This article will describe the various actions one would need to address in order to setup a branded "deep linking" experience using Video Meta Data and or the Player.

The use case, at a basic level, would be as follows:

1. User is watching a video on www.yourwebsite.com and wants to share the video they are watching to facebook.

2. The user then either clicks the Facebook share button within the player OR they grab the URL from your www.yourwebsite.com and paste this link into facebook.

3. The posting in facebook generates a graphical thumbnail which includes a title and a description.

4. When other users (friends) view this shared posting in Facebook they can click the post which will bring them back to www.yourwebsite.com where they are deep linked to watch the video in the player.

 

Lets explore how to make this happen.

Note: this requires development within your web page, this article should be for developers or web engineers that understand this process only.

 

Choosing your Link Structure

Choosing your link structure will require you to determine how you want to parse the URL generated either by the webpage or by the player.  The most important piece to include is a dynamic value that will represent the "Video Identifier" in your URL structure.  For example:

http://www.YourWebSite.com/videos/?video_id=[Video ID]

Once you have identified your linking structure you can then carry on to develop your website to properly parse the Video ID value as necessary.

The reason why you need to parse this Video ID value is for two key pieces of functionality:

1. Facebook, when scraping the link you are "sharing" to the page will look for key pieces of meta data within the <head> element of the page to populate the thumbnail, title, and description inline on the Facebook wall.

2. When the user clicks through from the Facebook posting, the player on your website will load the proper video to playback.

 

Requesting Meta Data for the Video

As mentioned above, the first piece needed for Facebook to correctly scrape/present the data for your video in a posting requires certain meta data fields to be present in the <head> of your document.

The following fields are described as necessary for such a use case by Facebook:

Note: prior to reading further it is helpful to understand Facebook's recommended best practices for sharing - https://developers.facebook.com/docs/sharing/best-practices

 

og:url

The canonical URL for your page. This should be the undecorated URL, without session variables, user identifying parameters, or counters. Likes and Shares for this URL will aggregate at this URL. For example, mobile domain URLs should point to the desktop version of the URL as the canonical URL to aggregate Likes and Shares across different versions of the page.

og:title

The title of your article. This shouldn't include branding such as your site name.

og:description

A brief description of the content, usually between 2 and 4 sentences. This will displayed below the title of the post on Facebook.

og:site_name

The name of your website (such as IMDb, not imdb.com).

og:image

The URL of the image that will appear when someone shares the content to Facebook. Please see Facebook's best practices guide to learn how to specify a high quality preview image and Facebook's documentation on images to specify width and height.

The process for populating these fields is a relatively simple one, following these steps will provide you with the information needed to collect the values for these tags:

1. Parse the Video Identifier from the URL

Example:

http://www.YourWebSite.com/videos/?video_id=55004749e4b07118348bf417

2. Use the Video Identifier to make a API Service request for the Video's meta data.  This can be done using the Search Service API with the Get Videos method. 

 

For further details, please see Search API get videos.

Note: the company key can be given to you by Customer Support.

  • Example (API request structure):
    • http://api.vidible.tv/{COMPANY_KEY}/video/{Vidible Video IDs}
  • Example (using our parsed Video ID):
    • http://api.vidible.tv/156723889193109/video/55004749e4b07118348bf417

You will then recieve a JSON object as a response, as an example:

[{
    "id": {Video ID},
    "creationDate": {Video creation date},
    "modificationDate": {Video modification date},
    "name": {Video name},
    "description": {Video description},
    "shortDescription": {Video short description},
    "category": {Video categories array},
    "startDate": {Video start date},
    "endDate": {Video end date},
    "publishDate": {Video publication date},
    "author": {Video authors array},
    "keywords": {Video keywords array},
    "rating": {Video rating array},
    "credit": {Video credit},
    "copyright": {Video copyright},
    "length": {Video duration seconds},
    "rssVideoId": {Video GUID},
    "transcript": {Video transcript},
    "media": {Video media: emotions, tags, conditions, specialties},
    "metadata": {Video metadata key-values},
    "feedThumbnail": {Original thumbnail URL, width, height},
    "systemThumbnails": {Array of thumbnails' URL, width, height}
}]
 

With this response you can use the necessary matching data fields to use as values for the Facebook meta data, an example below:

Vidible Object Facebook Meta Data
"id": {Video ID}
<meta property="og:url"
content="http://www.YourWebsite.com/videos/?video_id={Video ID}" />
 "name": {Video name}
<meta property="og:title"
content="http://www.YourWebsite.com/videos/?video_id={Video ID}" />

"description": {Video description}

OR

"shortDescription": {Video short description}

<meta property="og:description"
content="http://www.YourWebsite.com/videos/?video_id={Video ID}" />
 
<meta property="og:site_name"
content="Static Name of your Site" />
"systemThumbnails": {Array of thumbnails' URL, width, height}
<meta property="og:image"
content="One of the Thumbnail URLs from the Array" />

 Note: its important to understand that these <meta> elements need to be declared when the server creates the documented vs. when the browser renders the document.  This means that creating these <meta> elements on the client side using JavaScript will not work correctly.  This is because Facebook is scraping this data and most dynamic client side code will not render things properly when Facebook performs its scrape.

Once this data population is complete and in the <head> of your document you can then move onto connecting the player's logic to playback/load the proper video ID as defined in your website's URL.

 

Passing the Video ID to our Player

Passing the Video ID from your website's URL to the Player will make sure that the link in which the user has clicked on to "view the video" actually occurs.  Without passing on the Video ID to the player your user will be presented with the first video in the playlist as predefined in the players server side setup.  

Note: For further details, please see the Playlists section.

 

The player embed "tag" has a option parameter (key value pair) to pass in a Video ID.  This parameter only accepts a value upon load of the player.  This means you cannot dynamically update the video after the player has been loaded (not through this method).

Note: For further details, please see, Player API tag.

The following steps should be taken to load the player dynamically with the proper Video ID:

1. Parse the video ID from your website's URL (as done in previous steps for meta data).

2. Add the "vid" parameter to the player script URL (delivery service request) per the examples below:

Example (without vid parameter, the default):

<!-- TAG START { player: "Player: Woven Demo", owner: "Vidible", for: "Vidible" } -->
<div class="vdb_player vdb_5501f6a9e4b0e99aea2ef8d350d595ec0364e95588c77bd2">
    <script type='text/javascript' src="//delivery.vidible.tv/jsonp/pid=5501f6a9e4b0e99aea2ef8d3/50d595ec0364e95588c77bd2.js"></script>
</div>
<!-- TAG END { date: 03/12/15 } -->

Example (WITH vid parameter, developer adjusted):

<!-- TAG START { player: "Player: Woven Demo", owner: "Vidible", for: "Vidible" } -->
<div class="vdb_player vdb_5501f6a9e4b0e99aea2ef8d350d595ec0364e95588c77bd2">
    <script type='text/javascript' src="//delivery.vidible.tv/jsonp/pid=5501f6a9e4b0e99aea2ef8d3/vid=[Vidible Video ID]/50d595ec0364e95588c77bd2.js"></script>
</div>
<!-- TAG END { date: 03/12/15 } -->

3. Pass in the Video ID into the value of the "vid" parameter

<!-- TAG START { player: "Player: Woven Demo", owner: "Vidible", for: "Vidible" } -->
<div class="vdb_player vdb_5501f6a9e4b0e99aea2ef8d350d595ec0364e95588c77bd2">
    <script type='text/javascript' src="//delivery.vidible.tv/jsonp/pid=5501f6a9e4b0e99aea2ef8d3/vid=55004749e4b07118348bf417/50d595ec0364e95588c77bd2.js"></script>
</div>
<!-- TAG END { date: 03/12/15 } -->

 This step can be done dynamically as the document is rendered on the client side, as long as the value is passed in prior to the delivery service call (the request for the player JS).

 

Finalizing

Once you have completed these steps you have the basic pieces which are needed and can be controlled by your development team.  There are additional pieces which are controlled by the team as well as "optional" features that should be considered.

1. The player's sharing URL - The URL in which the player generates from its UI is controlled by an "Extra" from within the player.  This is something that once you have your URL structure ready, the Support team can configure for you.

2. Dynamic update of the website URL to match the Video ID in which the user is watching. (Note: its highly recommended to complete this step, for proper share URL use case handling.)

  1. To Dynamically update the Video ID in the URL you can use the player's event API to listen for "VIDEO_START" event, which will contain the Video ID as a apart of the event object. 

    Note: For further details, please see, Player API tag.

  2. Upon capturing this field as a part of the event, you can update your websites URL to contain the proper Video ID as a part of your URL structure.
Have more questions? Submit a request