Custom Gadgets

2015 Important Update

YouTube will no longer be accepting requests for new gadgets or gadget refreshes after March 31, 2015. Any gadget or gadget refresh booked for 2015 that is approved and reserved before March 31, 2015 will not be impacted. The final date for gadgets (including refreshes) to launch is July 1, 2015 and all gadgets will be removed from YouTube on December 31, 2015. Should you have additional questions or concerns, please reach out to your Google account team.

Overview

On their YouTube channel, advertisers have the ability to showcase a custom gadget. In short, a custom gadget allows advertisers to design their own custom web applications and/or microsite on their YouTube channel. Once approved by YouTube, the gadget is embedded in an iframe on the channel’s custom tab. YouTube gadgets fill the center column in between the Guide on the left and the Related Channels column on the right

Recently, we’ve made a few changes to the layout of the desktop channel page that will affect developers who are building a new custom tab for a YouTube channel. Existing advertisers do not have to do anything. The channel page is being centered (rather than left-aligned) and the subscription guide will expand from a new app bar rather than always being fixed to the lefthand side of the page.

NOTE: If you have an existing fixed-width or flex-width gadget you do NOT need to do take any action.

Channel Template:

Gadget Example:

If the browser window is smaller than 1000 pixels wide, the center column will remain fixed at 850 pixels and a scrollbar will appear within the browser window. YouTube’s center column has been optimized to snap between 3 sizes depending on available browser window width: 850px, 1056px, and 1262px. This is a departure from how gadgets were previously treated as they are no longer completely flex-width on YouTube.

• 850 px center column (minimum desktop width)
• 1056 px center column
• 1262 px center column

YouTube brand channel gadgets are forms of online advertising, and depending on their scope, may require minimum advertising spend thresholds prior to launch approval. Always check in with your Google representative to discuss pricing implications prior to beginning development.

Size Specifications:
Below are the iframe dimensions that took effect in February 2014:

• Width (gadgets will snap between 3 widths depending on available browser space): The three widths are:
  • 850px
  • 1056px
  • 1262px
• Width (gadgets can be set to “fixed-width” so that they remain one size always):
  • Fixed width gadgets will always be 970 px wide.
  • Fixed width gadgets are slated for deprecation in June 2014
• Height: Specified by developer, maximum 10,000 px

Design Specifications:

• Iframe color is transparent
• There will be no extra borders around the iframe
• The page background color is #F1F1F1

Hosting requirements
All custom gadget assets and files must be hosted on a third-party server. YouTube doesn’t host any of the graphics or code for your gadget. After creating a custom gadget, deliver a single URL, with a non-IP address to YouTube. After the approval process, the Tech Producer will enable the brand channel account to turn on the custom gadget.

SSL (Secure Socket Layer) Requirement
All YouTube brand channel gadgets must be SSL compliant. Furthermore, any custom gadgets that leverage our Google Maps API will need to a) be built using HTML5 and b) use v3 of the JavaScript Maps API in order to meet this requirement. It is not possible to incorporate the JavaScript Maps API into a Flash gadget and remain fully SSL-compliant.

Gadget File Size
While we don’t have a specific maximum gadget size, gadgets should be optimized for a broad range of internet connection speeds, including slower dial-up and data connections.

Server Requirements
Custom gadget servers should not have a data transfer cap, which will ensure that your gadget continues to serve regardless of traffic levels. The entire contents of the gadget application must be served via SSL connection.

Guidelines for brand channel gadgets

Gadget Height (Desktop Only)
The desired iframe height of a gadget should be passed to YouTube using HTML5 window.postMessage(). If no height is passed to YouTube, the platform will fall back to a default height, currently 2000 pixels. We strongly recommend setting a gadget height rather than relying on the default, to ensure your gadget renders correctly and as intended. Here is some sample code that you can run from inside your iframe gadget to adjust the height on your YouTube channel’s custom tab:

var new_height = JSON.stringify({"height": "1000px"});
top.postMessage(new_height, "https://www.youtube.com/");
top.postMessage(new_height, "http://www.youtube.com/");

Please note that the above code will produce an error in the JavaScript console, but these notifications may be ignored because it’s part of the postMessage method specification. YouTube will soon only support HTML5-compliant browsers so we strongly encourage our developers to ensure that their gadgets are HTML5 compliant.

Content
Any videos that the gadget plays must be hosted on YouTube and owned by the advertiser. In the case of a UGC contest, the entry videos are owned by the user (but still hosted on YouTube). Third-party servers or services may not be used for video ingestion (uploading) or hosting (playback).

All gadget content is subject to and must comply with YouTube’s Ad Policies, Terms of Service and Community Guidelines. YouTube account and channel owners are responsible for user-uploaded content that appears anywhere on your brand channel, including in a custom gadget.

Gadgets may link to other web pages, but all external links must spawn a new window.

User Generated Content and Contests
Please see YouTube’s Contest Policies & Guidelines page.

Video players
For gadgets, video players from other services or proprietary players may not be used, even if they show videos that are available on YouTube.

Desktop gadgets may only play videos using either the YouTube embedded player or the YouTube Chromeless Player. The embedded player provides the standard YouTube viewing experience, though you can customize some aspects of the player’s appearance as well as enable or disable certain features, such as the autoplay feature or keyboard controls. The chromeless player lets you customize the embedded player with your own controls, player ‘chrome’, and custom playlists and menus. The YouTube watermark in chromeless players must be clickable to the YouTube watch page.

Additional things to remember when selecting and customizing a video player:
• The YouTube watermark must always be visible and clickable.
• CSS and JavaScript can be programmed to create dynamic dimensions that ensure proper video player proportions across various screen sizes and orientations. If dimensions are fixed, the player may be cut off on smaller screen sizes.
• The player should always give users the option to pause and/or stop the video and include intuitive volume controls.
• The only way to have video views count toward the public YouTube views is to have the view initiated by the user via the standard built-in play btn on the player. For more details, see Fig. 2.1 below.

Fig. 2.1: Chart showing whether or not a view counts with various configurations of the YouTube player.

Rule of Thumb:
Any time a user initiates a playback using the native player controls, that playback should count. Using an API method to PLAY a video does not count. BUT, you can use cueVideoById and then have the user click a native built in play btn and it will count.

Views will NOT be counted if:

• The user initiates playback via an API method like playVideo or loadVideoById
• The video autoplays via the autoplay parameter

Animated GIFs

Animated GIFs can be included in a gadget provided that they adhere to the following guidelines:
• The loop sequence is three (3) seconds or less
• They are “click to initiate” — they cannnot merely play within the gadget, a user needs to click to view
• They include a call-out stating that they are animated GIFs
• Each animated GIF file size is no larger than 250K

Third-Party Social Networks
Many snippets of code that third-party social networking platforms provide to customers for placing on external websites (Twitter “follow” btn, Facebook “like” and “recommend” btns) use an IFRAME to bring in their content. Social Media IFRAME content is not permitted in YouTube gadgets for security reasons and therefore these implementation methods are not allowed. You can, of course, create your own btns or use other means that do not use an IFRAME. Social Media btns should click offsite and allow users to perform the action in the new offsite window.

Language and location settings
It’s possible to get the visitor’s YouTube language preference in order to display the gadget in a specific language. We provide this value to the gadget iframe in the shape of a GET variable. As a best practice, you should ALWAYS notify your YouTube Technical Producer if you will be using this feature.

The two language parameters are passed as GET variables they are called lang and hl and can be read the following way, &lang=xx where xx is the ISO639-1 value of the language, en.wikipedia.org/wiki/List_of_ISO_639-1_codes

The hl variable follows the format hl=xx_XX where the xx is the main language and the XX is the variation of the language, for example French Canadian displays as hl=FR_ca

We also provide a parameter for the visitor’s own choice of YouTube location, this parameter is gl and looks like this&gl=xx where xx is the ISO abbreviation of the country.

You can also simply use IP detection as your method of deciding how to display dynamic content based on location.

HTML5 / Javascript / Flash

• Desktop gadgets may be developed using HTML, Javascript or Flash. Flash is generally not recommended for YouTube gadget development due to scaling issues.
• Flexible height gadgets must use HTML5.
• Gadgets may not modify your brand channel page by dynamically changing or modifying HTML or cookies belonging to the page.
• Be aware that due to the iframe content, the web page presenting the brand channel gadget is showing content across domains, and anchor linking or “hot linking” within the gadget may be affected.

Deep-Linking into a YouTube Brand Channel Gadget
To facilitate deep-linking within gadgets, YouTube allows a single URL parameter, x, to be passed to the Gadget. This is accomplished by extracting the x-parameter from the YouTube URL and appending it to the iFrame URL.

As an example, say you have a YouTube Brand Channel named ILoveCats. You have the Custom Tab enabled and have set it’s vanity URL to “Explore”. Then the URL for the Custom Tab is: http://www.youtube.com/user/ILoveCats/Explore — you have also set the iFrame URL up to load a photo collage of your favorite kitties being hosted at http://www.ilovecats.com/mykitties. Your goal is to allow deep-linking to specific photos within your gadget so that visitors can easily share direct links to their favorite kitties with each other. In order to do this, you would do the following:

• Append a URL parameter named x to the URL of your Custom Tab. The value you assign to x should be something that you will be able to parse later. So for example if each kitten has a unique name and you want to allow people to deep-link directly to ‘Fred’, your YouTube Brand Channel URL would be http://www.youtube.com/user/ILoveCats/Explore?x=fred
• YouTube will automatically extract the x name-value pair and append it to the iFrame URL. So when your Custom Tab loads, it will load the following URL into the iFrame: http://www.ilovecats/mykitties?x=fred
  Note that x is the only parameter that YouTube will pass.
• At this point, you can read the value of the x-parameter from your url (e.g. accessing document.location via Javascript), parse it, and take the desired action. In this case, we would read the value ‘fred’ and update our photo gallery gadget so that the photo of Fred is being displayed.

Other Considerations:

It is important to note that if the Custom Tab within a YouTube Brand Channel is set as the default, the channel URL, rather than the Vanity URL for the Custom Tab can be used for deep linking. Using the example above, if the Custom Tab was set as the default tab for the ILoveCats Brand Channel, either http://www.youtube.com/user/ILoveCats?x=fred
or
http://www.youtube.com/user/ILoveCats/Explore?x=fred would deep-link correctly.

If the Custom Tab is not set as the default tab, links that do not include the Vanity URL for the Custom Tab will not deep link correctly. Also, note that the Vanity URL can be changed by the owner of a channel at any time. However, if the Vanity URL is changed after deep links utilizing the Vanity URL have been shared, all links that were distributed using the old Vanity URL will result in a ‘404 Not Found’ error. As a best practice, please ensure that deep-links always utilize the most current vanity URL for the Custom Tab.

Flash & Plug-ins

We do not allow gadgets to use any plug-ins other than Flash and the Google Earth Plug-in. You can use the Google Earth Plug-in inside your gadget as long as your gadget follows these additional guidelines:
• Due to legal concerns, your brand channel cannot show the Google Earth Plug-in in some countries; always check the latest Google Maps/Earth API Legal Notices. Use the IP/locale GEO redirect field, which appears under the Tracking and Redirects features in the Branding Options tab, to set up these restrictions.
• Your gadget may not require users to download the Google Earth Plug-in, though you can display a call-to-action to download the plug-in.

Personal User Data

• Personal user data can only be collected for user generated content, contests, or “one time” lead generation forms (forms that only send one follow-up email for a specific purpose, not add the user to a marketing email list). Tech Producer approval required.
• If collecting information from users, the gadget must clearly specify that the third party is collecting the data, not YouTube.
• For UGC or contests, only first name, last name, and email address may be collected and only for the purposes of administering the contest. In general, without a contest or UGC, a gadget may only collect email address, which can be for a one-time use only, not for email list subscriptions and remarketing.
• The gadget needs to be accompanied by a link to a privacy policy that explains what user data is collected by the gadget and for what purpose it will be used.
• Your gadget should send any user information that it collects to your servers. YouTube will not store user data collected by your gadget.
• YouTube will only share usernames with the third party. YouTube will not share email addresses or other identifying information from user profiles.

Gadget Tracking

• We recommend that you integrate Google Analytics with any custom gadget that you develop. To ensure visits are tracked properly in the Custom Tab, please check security settings on Microsoft Internet Explorer and follow this workaround.
• Please note that Google Analytics support for troubleshooting and integration questions is only available to Google Analytics Premium customers. You can learn more about the services here.
• You can use other third-party tracking solutions, subject to prior review, to track user actions in your gadgets. You can create and/or read cookies on ad impressions or other user actions. YouTube will only approve a gadget that uses a third-party tracking solution if you use a certified vendor. Here is the list of certified vendors in the Americas. Here is thelist of certified vendors for EMEA.

Privacy and Security

• Developers and advertisers must take reasonable steps to ensure that the gadget is secure from attacks that could put the servers hosting the gadget or users at risk. This includes making sure the servers hosting the gadget have industry standard security controls, including up-to-date security patches, securely configuring all software on the systems, hardening the operating system, performing regular security tests and scans, and other applicable best practices.
• We do not allow advertisers to use Flash Cookies/LSOs in any ads or brand channels. Note, exceptions are only given in cases where the use of cookies is necessary for compliance with regulators’ requirements, such as with video games or alcohol ads.
• We do not allow collection of authentication credentials for third party websites such as YouTube, Facebook, or Twitter. Under no circumstances may the gadget use Google’s ClientLogin API or ask for credentials for user accounts at Google, YouTube, Facebook, Twitter, or other 3rd party services.
• Authentication must be handled using OAuth or other approved authentication method where credentials are not collected directly by the gadget. The gadget should not request more privileges than necessary for the user’s intended action.
• All user data collected from the gadget must be adequately protected against unauthorized access, and the gadget must be secured against common security issues such as authentication/authorization problems, SQL injection, XSS, CSRF, clickjacking, XSSI, etc.
• Your gadget may not promote the installation of client software, malware or other deceptive Internet applications.
• All gadgets require that the sponsor is easily identifiable to the user.
• Any security incident that affects the systems hosting the gadget, or user data related to YouTube (such as OAuth tokens) must be reported to Google immediately, within 24 hours of detection.
• All gadgets are subject to security inspection and assessment by Google at any time. If we discover material vulnerabilities, it will be your responsibility to fix them and, if the vulnerabilities expose users to unnecessary risk, we may suspend the gadget until the problems have been corrected.

Core YouTube Features
Custom gadgets are free to use YouTube APIs but should not replicate the “look and feel” of the YouTube platform, channels, or watch page, or YouTube site btns and controls, — including the controls throughout the YouTube website and those in the YouTube player. For example, the “play” btn (or controls of a similar appearance) should not be used anywhere within the gadget (except as a real play btn for the chromeless player – see Video Players above).

Planning & Timelines
Before your gadget can appear on your channel, it needs to be reviewed by YouTube. We recommend that you include a YouTube Tech Producer in your process before starting development. When planning the development for your channel, allow 3-5 business days for initial review before development begins. We also require 3-5 business days for final review, not including additional time required for any changes.

Timelines and production schedules will vary based on complexity of the project. Please contact your YouTube Technical Producer for more details on this process and example timelines.

For more information on Multi Channel Network’s and YouTube how to videos please check back weekly or subscribe here.