Ad Units and Code Generation

An ad unit is the set of ads displayed as a result of one piece of the AdSense ad code. As you would expect, you can fully manage your ad unit inventory by creating, deleting, editing and updating ad units using the AdSense Host API. You can also also generate the ad code needed to show ads on your site.

An ad unit defines size, colors, fonts and corner styles. Ad units also allow the host to create channels for performance tracking. These two concepts are applied at different times: the former at ad unit creation and the latter in the code generation stage.

Ad unit styles

The following can be customized when creating ad units:

  • Size
  • Type
  • Custom Style: colors, corners and font
  • Backup Option
  • Mobile settings (WAP)

Size

Size is a string similar to "SIZE_728_90" where the first integer is width and the last is height. Remember there is a limited set of sizes so check the AdSense web interface for an updated list.

Example ad unit 1 Example ad unit 2
Figure 1: Different ad units sizes

Type

Text, image or rich media ads are examples of ad types that may appear on your page.

Types can be TEXT, TEXT_IMAGE, IMAGE, or LINK. Not all formats (sizes) are allowed for image ads so check the AdSense Help page for an updated list.

Custom Styles

A custom style overrides the default colors, fonts and other cosmetic properties of the ad unit and the displayed ads.

"customStyle": {
  "colors": {
    "border": "800040",
    "title": "0000CC",
    "background": "FFFDFD",
    "text": "1F1F1F",
    "url": "008000"
  },
  "corners": "VERY_ROUNDED"
  "font": {
    "family": "ACCOUNT_DEFAULT_FAMILY",
    "size": "ACCOUNT_DEFAULT_SIZE"
  }
}

Currently there is no way to apply saved styles to ad units so a full definition of custom style is required, as well as corners (SQUARE, SLIGHTLY_ROUNDED or VERY_ROUNDED) , font families (ACCOUNT_DEFAULT_FAMILY, ADSENSE_DEFAULT_FAMILY , ARIAL, TIMES or VERDANA) and font sizes (ACCOUNT_DEFAULT_SIZE, ADSENSE_DEFAULT_SIZE , SMALL, MEDIUM or LARGE).

Slightly rounded and very rounded corners
Figure 2: Slightly rounded and very rounded corner styles.

Backup option

When Google has no targeted ads available, you can define a backup option to display so that your layout is not affected. It can be a blank space, a solid color or the URL of an HTML page that you've implemented.

Mobile settings

Mobile settings let you configure things like markup language or scripting language to use in WAP devices.

Read more

To better understand how these properties are defined, take a look at the Resource Representation on the Adunits documentation page. For a more detailed explanation of these concepts, visit the AdSense Help page.

Code generation

Once an ad unit is created, a small JavaScript snippet is needed to show ads on a page. This is generated with the API using the getAdCode method:

GET https://www.googleapis.com/adsensehost/v4.1/accounts/accountId/adclients/adClientId/adunits/adUnitId/adcode

The account ID is the publisher's ID that must be stored by the host from the association session stage, specifically at the token verification step.

Bear in mind that in order to create an ad unit, an ad client ID is needed. The product code needed to show content ads is "AFC". It may be already generated for you so list your ad clients to determine your ad client ID.

Having the account ID, ad client ID and the ID for the ad unit, the code can be now generated. The resulting structure for the AFC product contains a small string that needs to be placed on the HTML code of the page. The asynchronous ad code looks like this:

<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- leaderboard -->
<ins class="adsbygoogle"
    style="display:inline-block;width:728px;height:90px"
    data-ad-client="ca-pub-xxxxxxxxxxxxxxxx"
    data-ad-host="ca-host-pub-xxxxxxxxxxxxxxxx"
    data-ad-slot="1234567890"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Note that width and height are defined in this code so it must be regenerated when resizing. Also remember that this code must be stored on the host's side, not regenerated for each impression.

Custom channels

In the AdSense Host API, custom channels (host custom channels!) are associated to ad units at code generation. The getAdCode method can be called using an optional parameter called hostCustomChannelId. This field is included in the generated code so each time a custom channel is added to or removed from an ad unit, it must be regenerated.

<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- leaderboard -->
<ins class="adsbygoogle"
    style="display:inline-block;width:728px;height:90px"
    data-ad-client="ca-pub-xxxxxxxxxxxxxxxx"
    data-ad-host="ca-host-pub-xxxxxxxxxxxxxxxx"
    data-ad-slot="1234567890"
    data-ad-host-channel = "123456789"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Multiple custom channels can track the performance of an ad unit and multiple ad units can be tracked by a custom channel.