The YouTube Subscribe Button lets you add a one-click Subscribe
button to any page. The button lets people subscribe to your YouTube channel without having to leave your site to either log in to YouTube or confirm their subscriptions.
To add a button, your application needs to load this JavaScript file:
https://apis.google.com/js/platform.js
You can add a button by using an element, such as a <div>
, that sets its class
to g-ytsubscribe
and uses other attributes to customize the button. The code below shows a simple integration that displays a Subscribe
button for the GoogleDevelopers channel.
<script src="https://apis.google.com/js/platform.js"></script> <div class="g-ytsubscribe" data-channel="GoogleDevelopers"></div>
You can also use the Google+ JavaScript API to render a button dynamically.
Note: If the channel associated with the button is a paid subscription channel, the button links to the channel rather than subscribing users automatically.
Contents
- Configuration options
- Configure a button
- Subscription button attributes
- Handling events
- Dynamic rendering
- Conditions of use
- Retrieve your channel ID
- Revision history
Configuration options
Configure a button
The tool below lets you configure an embedded subscription button. You can set the button's display options, preview the button, and copy the code needed to insert that button on your page.
Subscription button attributes
This section explains how to construct a <div>
element for a subscription button. The list below explains the element's required and optional attributes. Optional attributes let you control the button's layout and theme as well as choose whether to display the channel's subscriber count. You can also specify an event listener that handles events that the button fires when a user clicks the button.
-
Required
-
class
– Set the value tog-ytsubscribe
. This class identifies the<div>
element as a container for a subscription button and enables YouTube to dynamically resize the embedded button as explained in the next section. -
You must specify a value for one of the following two attributes:
data-channel
– The name of the channel associated with the button. Sample value:GoogleDevelopers
.data-channelid
– The channel ID associated with the button. Sample value:UC_x5XG1OV2P6uZZ5FSM9Ttw
. You can retrieve your channel ID in your YouTube account settings or by using the APIs Explorer at the end of this document. Learn more about working with channel IDs.
-
-
Optional
-
data-layout
– The format for the button. Valid attribute values are:default
– Displays a play button icon and the word 'subscribe' in the user's language, which is selected using either the user's language setting or location.full
– Displays the channel's avatar and channel title in addition to the standard button.
-
data-theme
– Specifies the color scheme to use for the button. Valid values aredefault
anddark
. Thedark
theme is intended for applications that place buttons over a darker background element. -
data-count
– Indicates whether the button displays the number of subscribers that the channel has. The button's default behavior is to display the subscriber count. However, the count is not displayed for paid channels. Valid values aredefault
andhidden
. -
data-onytevent
– Specifies the name of a JavaScript function that will handle event notifications related to the button. The button fires events when a user clicks the button to subscribe or unsubscribe from a channel.
-
Handling events
A Subscribe Button fires an event when a user clicks the button to subscribe to or unsubscribe from the associated channel. You can add the data-ytonevent
attribute to the widget element to specify an event listener that you want to receive event notifications.
The event listener needs to be a function that accepts a single payload
argument. The payload
is an object that always contains an eventType
property. The Subscribe Button supports the following events:
-
subscribe
: Indicates that the user subscribed to a channel. For this event type, thepayload
object also contains achannelExternalId
property that specifies the channel's YouTube channel ID. -
unsubscribe
: Indicates that the user subscribed from a channel. For this event type, thepayload
object also contains achannelExternalId
property that specifies the channel's YouTube channel ID.
The demo and sample code below demonstrate how an application can respond to these events. As shown in the code, the demo creates a Subscribe Button for the GoogleDevelopers channel as well as an empty <div>
element just below the button.
When you click the button, the JavaScript function receives an event notification and logs information about the event in the <div>
element. In browsers that support logging to window.console
, such as Chrome, the JavaScript code also logs the event in the console. (In Chrome, you can see this by opening the JavaScript console before trying the demo.)
Demo and sample code
Dynamic rendering
As an alternative to using the standard embed code from the configuration tool, you can dynamically render the Subscribe Button. This approach prevents the API's JavaScript from traversing the entire DOM to locate buttons, which can improve button rendering time.
As a part of the Google+ JavaScript API, the Subscribe Button supports standard go
and render
methods, which can be used to dynamically render subscription buttons. For example, you could use these methods to render a button that is not present when the DOM ready
event fires, such as on a page that is updated with AJAX.
Method | Description |
---|---|
gapi.ytsubscribe.go( |
Renders all subscription buttons in the specified container. Use this method if the subscription button elements that you want to render already exist. For example, if your application sends an AJAX request that returns the complete <div> element for a Subscribe Button, call the go() method to render the button.
|
gapi.ytsubscribe.render( |
Renders the Subscribe Button within the specified container. Use this method if the element that will contain the Subscribe Button does not already exist and needs to be constructed.
|
Rendering a button with gapi.ytsubscribe.go
The example below shows the code that you would use to call the gapi.ytsubscribe.go
method to dynamically render a button when the link is clicked.
Note: The configuration tool above also uses the go
method to render a new button when you update the button options or code.
Rendering a button with gapi.ytsubscribe.render
The example below shows the code that you would use to call the gapi.ytsubscribe.render
method to dynamically render a button when the link is clicked.
Conditions of use
By using the YouTube Subscribe Button, you agree to the YouTube API Terms of Service and all other relevant API documentation, including without limitation the Monetization Guidelines and Branding Guidelines. The YouTube Subscribe Button does not allow you to use the YouTube brand in any way not expressly authorized by the API Terms of Service and API documentation.
For clarity:
- You may not offer or promote prizes or rewards of any kind in exchange for clicking on a YouTube Subscribe Button.
- Buttons must be fully and clearly visible.
- You may not use a Subscribe Button to track any data about a user related to the user's actions or browsing activity, including without limitation whether or not a user clicks on a YouTube Subscribe Button. This prohibition includes but is not limited to using pixels, cookies, or other methods of recognizing when a user clicks on a YouTube button.
Retrieve your channel ID
You can use the form below to retrieve your channel ID or another channel's ID.
-
To retrieve your own channel ID, authorize the request by setting the Authorize requests using OAuth 2.0 button at the top of the form to
ON
. Then send the request by clicking the blue button at the bottom of the form. -
To retrieve the channel ID for any channel that has a YouTube channel name, set the
forUsername
property in the form below to the channel name and themine
property tofalse
.
Note: This form calls the YouTube Data API's channels.list
method. By default, the form sets the part
parameter value to snippet
and the mine
parameter value to true
.
Revision history
November 22, 2013
This update contains the following changes:
-
The JavaScript file that you should load to add your own button has changed to
https://apis.google.com/js/platform.js
. The old file,https://apis.google.com/js/plusone.js
will still be supported, but the new file is more efficient. -
The subscription button attributes section now explains how to use the
data-count
attribute to specify whether a Subscribe Button should show the associated channel's subscriber count. The configuration options section also now shows sample buttons that show and hide the subscriber count. Finally the tool for configuring your own button also supports this setting. -
The Subscribe Button now fires events when a user clicks the button to subscribe to a channel or unsubscribe from a channel. The new Handling events section explains how to identify a JavaScript function that listens for these events. The subscription button attributes section also explains the new
data-onytevent
attribute that you use to identify the event listener.In addition, the tool that lets you configure your own button now includes an option to indicate that you want to handle these events. When that option is selected, the button code includes a sample JavaScript function for you to modify.