Custom Gadget Developer Guidelines

Hosting Requirements
Gadget Guidelines
User-Generated Content and Contests
Video Players
Language and Location Settings
Deep-Linking into a Gadget
Special Considerations
Planning & Timelines

2015 Important Update

YouTube will no longer be accepting requests for new gadgets or gadget refreshes after 31 March 2015. Any gadget or gadget refresh booked for 2015 that is approved and reserved before 31 March 2015 will not be affected. The final date for gadgets (including refreshes) to launch is 1 July 2015 and all gadgets will be removed from YouTube on 31 December 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 centre column 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. These changes 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 centred (rather than left-aligned) and the subscription guide will expand from a new app bar rather than always being fixed to the left-hand 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 centre column will remain fixed at 850 pixels and a scrollbar will appear within the browser window. YouTube's centre column has been optimised to snap between three 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 centre column (minimum desktop width)
  • 1056 px centre column
  • 1262 px centre column

YouTube brand channel gadgets are a form of online advertising. Depending on the scope of the gadgets, minimum advertising spend thresholds may be required prior to launch approval. Always contact your Google representative to discuss pricing implications prior to starting development.

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

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

Design Specifications:

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

Mobile:

All mobile gadgets will be taken offline on 1 April 2014.

After that date, several channels may have gadgets only on desktop, which could result in broken links on mobile devices if the gadget is linked from ads, annotations, video descriptions, etc. To prevent these broken links, we will be offering the ability to redirect custom tab URLs (youtube.com/user/username/custom OR youtube.com/user/username/tabname) to the desktop gadget URL in a web browser, if the gadget settings have been adjusted accordingly (see below). The microsite will open in the same window.

This option will be available from February 2014 in the "Edit Channel Navigation" menu under "Custom Tab" (only visible to channels enabled for a gadget). Note: If a channel opts in to this setting and the channel currently has a mobile gadget live, users will be redirected away from the custom tab to the gadget in a browser. It is therefore advisable to have a Tech Producer disable the mobile gadget before enabling the setting. As of 1 April, all mobile gadgets will be disabled and enabling the redirect should not cause any issues.

How to access the “Edit Channel Navigation" menu

The new “Mobile Redirect” setting


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. On completion of 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 optimised 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 function 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)
Details of the required iframe height of a gadget should be passed on 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 that you set a gadget height rather than rely on the default to ensure that 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 can be ignored because it is 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 cannot 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 their brand channel, including in a custom gadget.

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

User-Generated Content and Contests
If your custom gadget accepts direct submissions of user content, you must post a clear Terms and Conditions document that explains how the content will be used. In addition, you cannot claim ownership of or modify that content, which means that users reserve the right to remove their content from your gadget. All user submissions must first be uploaded to the user's account; the contest cannot solicit submissions directly to the advertiser's account. Please contact your Google Sales team before starting development of a contest or UGC campaign.

For custom contest gadgets, please review the Permitted Contest Gadgets section of Designing and Running a Contest, and YouTube's Contest Policies and Guidelines.

Video players
Video players from other services or proprietary players may not be used for gadgets, 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 customise 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 allows you to customise 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 customising 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 get video views to count towards the public YouTube views is to have the view initiated by the user via the standard built-in play button on the player. For more details, see Fig. 2.1 below.
Player Type How play is invoked for the first time? Is the view counted?
Embedded Player User clicks on native built-in play button Yes
Embedded Player cueVideoById called, and user clicks on built-in play button Yes
Embedded Player uses autoplay parameter No
Embedded Player player.playVideo() called No
Embedded Player player.loadVideoById() called No
Chromeless Player User clicks on native built-in play button Yes
Chromeless Player cueVideoById called, and user clicks on built-in play button Yes
Chromeless Player player.playVideo() called No
Chromeless Player player.loadVideoById() called No

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

Rule of Thumb:
If 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 get the user to click a native built-in play button – and this view will count.

    Views will NOT be counted if:
  • The user initiates playback via an API method such as 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 cannot 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" button, Facebook "Like" and "Recommend" buttons) 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 buttons or use other means that do not use an IFRAME. Social Media buttons 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 form 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 can be developed using HTML, Javascript or Flash. Flash is not generally recommended for YouTube gadget development due to scaling issues.
  • Flexible height gadgets must use HTML5.
  • Gadgets must 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, imagine you have a YouTube brand channel named ILoveCats. You have the custom tab enabled and have set its vanity URL to "Explore". The URL for the custom tab is therefore: http://www.youtube.com/user/ILoveCats/Explore – you have also set up the iframe URL to load a photo collage of your favourite cats being hosted at http://www.ilovecats.com/mycats. Your goal is to allow deep-linking to specific photos within your gadget so that visitors can easily share direct links to their favourite cats 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. For example, if each cat 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/mycats?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 utilising 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 utilise 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, contest, 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 an email address, which can be for one-off use only, and cannot be used for email list subscriptions and remarketing.
  • The gadget must 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 that 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 the list 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 that 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. Exceptions are made only in cases where the use of cookies is necessary for compliance with regulatory requirements, such as with video games or alcohol ads.
  • We do not allow the 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 another 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 unauthorised access, and the gadget must be secured against common security issues such as authentication/authorisation 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 and 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 buttons and controls, including the controls throughout the YouTube website and those in the YouTube player. For example, the "play" button (or controls of a similar appearance) should not be used anywhere within the gadget (except as a real play button for the chromeless player – see Video Players above).

Planning & Timelines
Before your gadget can appear on your channel, it must 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 the complexity of the project. Please contact your YouTube Technical Producer for more details on this process, as well as sample timelines.

How helpful is this article:

Feedback recorded. Thank you.
  • Not at all helpful
  • Not very helpful
  • Somewhat helpful
  • Very helpful
  • Extremely helpful